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