freppleinterface.h
Go to the documentation of this file.
00001 /*************************************************************************** 00002 file : $URL: http://svn.code.sf.net/p/frepple/code/trunk/include/freppleinterface.h $ 00003 version : $LastChangedRevision: 1715 $ $LastChangedBy: jdetaeye $ 00004 date : $LastChangedDate: 2012-07-19 21:37:46 +0200 (Thu, 19 Jul 2012) $ 00005 ***************************************************************************/ 00006 00007 /*************************************************************************** 00008 * * 00009 * Copyright (C) 2007-2012 by Johan De Taeye, frePPLe bvba * 00010 * * 00011 * This library is free software; you can redistribute it and/or modify it * 00012 * under the terms of the GNU Affero General Public License as published * 00013 * by the Free Software Foundation; either version 3 of the License, or * 00014 * (at your option) any later version. * 00015 * * 00016 * This library is distributed in the hope that it will be useful, * 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 00019 * GNU Affero General Public License for more details. * 00020 * * 00021 * You should have received a copy of the GNU Affero General Public * 00022 * License along with this program. * 00023 * If not, see <http://www.gnu.org/licenses/>. * 00024 * * 00025 ***************************************************************************/ 00026 00027 /** @file freppleinterface.h 00028 * @brief Public header file for C and C++. 00029 * 00030 * This is the public header file for high-level access to the library 00031 * functionality.<br> 00032 * The methods listed provide also a safe interface API for accessing the 00033 * library functionality from C, C++, Visual Basic and other programming 00034 * languages. 00035 * 00036 * When extending the library, use the header file frepple.h instead.<br> 00037 * It provides a more detailed API to interface with frePPLe. 00038 */ 00039 00040 #ifndef FREPPLE_INTERFACE_H 00041 #define FREPPLE_INTERFACE_H 00042 00043 #ifdef __cplusplus 00044 #include <string> 00045 #endif 00046 00047 // For a windows shared library we use the C calling convention: __stdcall. 00048 // Only such functions can be called from VBA... 00049 // For cygwin we don't use the __stdcall, but still need the export/import. 00050 #undef DECLARE_EXPORT 00051 #if defined(WIN32) && !defined(DOXYGEN) 00052 #ifdef __CYGWIN__ 00053 #ifdef FREPPLE_CORE 00054 #define DECLARE_EXPORT(type) __declspec (dllexport) type 00055 #else 00056 #define DECLARE_EXPORT(type) __declspec (dllimport) type 00057 #endif 00058 #else 00059 #ifdef FREPPLE_CORE 00060 #define DECLARE_EXPORT(type) __declspec (dllexport) type __stdcall 00061 #else 00062 #define DECLARE_EXPORT(type) __declspec (dllimport) type __stdcall 00063 #endif 00064 #endif 00065 #else 00066 #define DECLARE_EXPORT(type) type 00067 #endif 00068 00069 /** This method returns a version string. */ 00070 DECLARE_EXPORT(const char*) FreppleVersion(); 00071 00072 /** This function should be called once when the client application starts, 00073 * and before calling any other function in the API. 00074 * 00075 * This method is synchronous, i.e. it returns only when the complete 00076 * processing is finished. The method can throw exceptions, and the client 00077 * is responsible for defining the correct handlers for these. 00078 */ 00079 DECLARE_EXPORT(void) FreppleInitialize(int, char*[]); 00080 00081 /** The character buffer pointed to by the first parameter contains data in 00082 * XML format that is passed on to frePPLe for processing.<br> 00083 * The second argument specifies whether frePPLe should validate the data 00084 * against the XSD schema.<br> 00085 * The last argument specifies whether frePPLe needs to perform only the 00086 * validation and skip the actual processing. 00087 * 00088 * The client is responsible for the memory management in the data buffer. 00089 * 00090 * This method is synchroneous, i.e. it returns only when the complete 00091 * processing is finished. The method can throw exceptions, and the client 00092 * is responsible for defining the correct handlers for these. 00093 */ 00094 DECLARE_EXPORT(void) FreppleReadXMLData(const char*, bool, bool); 00095 00096 /** The first parameter is the name of a file that contains data in XML 00097 * format for frePPLe processing. If a NULL pointer is passed, frepple 00098 * will read from the standard input.<br> 00099 * The second argument specifies whether frePPLe should validate the data 00100 * against the XSD schema.<br> 00101 * The last argument specifies whether frePPLe needs to perform only the 00102 * validation and skip the actual processing. 00103 * 00104 * This method is synchroneous, i.e. it returns only when the complete 00105 * processing is finished. The method can throw exceptions, and the client 00106 * is responsible for defining the correct handlers for these. 00107 */ 00108 DECLARE_EXPORT(void) FreppleReadXMLFile(const char*, bool, bool); 00109 00110 /** Execute the Python code in a file. 00111 * 00112 * This method is synchroneous, i.e. it returns only when the complete 00113 * processing is finished. The method can throw exceptions, and the client 00114 * is responsible for defining the correct handlers for these. 00115 */ 00116 DECLARE_EXPORT(void) FreppleReadPythonFile(const char*); 00117 00118 /** Calling this function will save the frePPLe data in the file that 00119 * is passed as the argument. 00120 * 00121 * This method is synchroneous, i.e. it returns only when the complete 00122 * processing is finished. The method can throw exceptions, and the client 00123 * is responsible for defining the correct handlers for these. 00124 */ 00125 DECLARE_EXPORT(void) FreppleSaveFile(const char*); 00126 00127 /** This function causes the frepple executable to shut down in an orderly 00128 * way. 00129 * 00130 * This method is synchroneous, i.e. it returns only when the complete 00131 * processing is finished. The method can throw exceptions, and the client 00132 * is responsible for defining the correct handlers for these. 00133 */ 00134 DECLARE_EXPORT(void) FreppleExit(); 00135 00136 #ifdef __cplusplus 00137 /** Echo a message in the frePPLe log stream (which is either a file or 00138 * the standard output stream). 00139 * 00140 * This function is only available when using C++. The same functionality 00141 * is available to C with the function FreppleLog(const char*). 00142 */ 00143 DECLARE_EXPORT(void) FreppleLog(const std::string&); 00144 00145 /* The functions listed below can be called from C. */ 00146 extern "C" 00147 { 00148 00149 #endif 00150 /** Echo a message in the frePPLe log stream (which is either a file or 00151 * the standard output stream). 00152 */ 00153 DECLARE_EXPORT(void) FreppleLog(const char*); 00154 00155 /** Same as FreppleInitialize, but catches all exceptions and returns a 00156 * status instead. 00157 * 00158 * Use this function when calling the library from C or VB applications. 00159 * @see FreppleInitialize 00160 */ 00161 DECLARE_EXPORT(int) FreppleWrapperInitialize(int argc, char* argv[]); 00162 00163 /** Same as FreppleReadXMLData, but catches all exceptions and returns a 00164 * status instead. 00165 * 00166 * Use this function when calling the library from C or VB applications. 00167 * @see FreppleReadXMLData 00168 */ 00169 DECLARE_EXPORT(int) FreppleWrapperReadXMLData(char*, bool, bool); 00170 00171 /** Same as FreppleReadXMLFile, but catches all exceptions and returns a 00172 * status instead. 00173 * 00174 * Use this function when calling the library from C or VB applications. 00175 * @see FreppleReadXMLFile 00176 */ 00177 DECLARE_EXPORT(int) FreppleWrapperReadXMLFile(const char*, bool, bool); 00178 00179 /** Same as FreppleReadPythonFile, but catches all exceptions and returns a 00180 * status instead. 00181 * 00182 * Use this function when calling the library from C or VB applications. 00183 * @see FreppleReadPythonFile 00184 */ 00185 DECLARE_EXPORT(int) FreppleWrapperReadPythonFile(const char*); 00186 00187 /** Same as FreppleSaveFile, but catches all exceptions and returns a 00188 * status instead. 00189 * 00190 * Use this function when calling the library from C or VB applications. 00191 * @see FreppleSaveFile 00192 */ 00193 DECLARE_EXPORT(int) FreppleWrapperSaveFile(char*); 00194 00195 /** Same as FreppleExit, but catches all exceptions and returns a 00196 * status instead. 00197 * 00198 * Use this function when calling the library from C or VB applications. 00199 * @see FreppleExit 00200 */ 00201 DECLARE_EXPORT(int) FreppleWrapperExit(); 00202 00203 #ifdef __cplusplus 00204 } // End of "extern C" 00205 #endif 00206 00207 #endif // End of FREPPLE_INTERFACE_H