freppleinterface.h
Go to the documentation of this file.00001 /*************************************************************************** 00002 file : $URL: https://frepple.svn.sourceforge.net/svnroot/frepple/trunk/include/freppleinterface.h $ 00003 version : $LastChangedRevision: 652 $ $LastChangedBy: jdetaeye $ 00004 date : $LastChangedDate: 2008-01-09 17:48:42 +0100 (Wed, 09 Jan 2008) $ 00005 ***************************************************************************/ 00006 00007 /*************************************************************************** 00008 * * 00009 * Copyright (C) 2007 by Johan De Taeye * 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA * 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.<br> 00074 * The parameter is a string with the name of the Frepple home directory. 00075 * If the parameter is NULL, the setting of the environment variable 00076 * FREPPLE_HOME is used instead. 00077 * 00078 * This method is synchroneous, i.e. it returns only when the complete 00079 * processing is finished. The method can throw exceptions, and the client 00080 * is responsible for defining the correct handlers for these. 00081 */ 00082 DECLARE_EXPORT(void) FreppleInitialize(const char*); 00083 00084 /** The character buffer pointed to by the first parameter contains data in 00085 * XML format that is passed on to Frepple for processing.<br> 00086 * The second argument specifies whether frepple should validate the data 00087 * against the XSD schema.<br> 00088 * The last argument specifies whether Frepple needs to perform only the 00089 * validation and skip the actual processing. 00090 * 00091 * The client is responsible for the memory management in the data buffer. 00092 * 00093 * This method is synchroneous, i.e. it returns only when the complete 00094 * processing is finished. The method can throw exceptions, and the client 00095 * is responsible for defining the correct handlers for these. 00096 */ 00097 DECLARE_EXPORT(void) FreppleReadXMLData(char*, bool, bool); 00098 00099 /** The first parameter is the name of a file that contains data in XML 00100 * format for Frepple processing. If a NULL pointer is passed, frepple 00101 * will read from the standard input.<br> 00102 * The second argument specifies whether frepple should validate the data 00103 * against the XSD schema.<br> 00104 * The last argument specifies whether Frepple needs to perform only the 00105 * validation and skip the actual processing. 00106 * 00107 * This method is synchroneous, i.e. it returns only when the complete 00108 * processing is finished. The method can throw exceptions, and the client 00109 * is responsible for defining the correct handlers for these. 00110 */ 00111 DECLARE_EXPORT(void) FreppleReadXMLFile(const char*, bool, bool); 00112 00113 /** Calling this function will save the Frepple data in the file that 00114 * is passed as the argument. 00115 * 00116 * This method is synchroneous, i.e. it returns only when the complete 00117 * processing is finished. The method can throw exceptions, and the client 00118 * is responsible for defining the correct handlers for these. 00119 */ 00120 DECLARE_EXPORT(void) FreppleSaveFile(char*); 00121 00122 #ifdef __cplusplus 00123 /** Calling this function returns a text buffer with the frepple data 00124 * model. 00125 * 00126 * This method can consume a lot of memory for big models!<br> 00127 * This method is synchroneous, i.e. it returns only when the complete 00128 * processing is finished. The method can throw exceptions, and the client 00129 * is responsible for defining the correct handlers for these. 00130 * 00131 * This function is only available when using C++. The same functionality 00132 * is available to C with the function FreppleWrapperSaveString. 00133 * @see FreppleWrapperSaveString 00134 */ 00135 DECLARE_EXPORT(std::string) FreppleSaveString(); 00136 #endif 00137 00138 /** This function causes the frepple executable to shut down in an orderly 00139 * way. 00140 * 00141 * This method is synchroneous, i.e. it returns only when the complete 00142 * processing is finished. The method can throw exceptions, and the client 00143 * is responsible for defining the correct handlers for these. 00144 */ 00145 DECLARE_EXPORT(void) FreppleExit(); 00146 00147 #ifdef __cplusplus 00148 /** Echo a message in the frePPLe log stream (which is either a file or 00149 * the standard output stream). 00150 * 00151 * This function is only available when using C++. The same functionality 00152 * is available to C with the function FreppleLog(const char*). 00153 */ 00154 DECLARE_EXPORT(void) FreppleLog(const std::string); 00155 00156 /* The functions listed below can be called from C. */ 00157 extern "C" 00158 { 00159 00160 #endif 00161 /** Echo a message in the frePPLe log stream (which is either a file or 00162 * the standard output stream). 00163 */ 00164 DECLARE_EXPORT(void) FreppleLog(const char*); 00165 00166 /** Same as FreppleInitialize, but catches all exceptions and returns a 00167 * status instead. 00168 * 00169 * Use this function when calling the library from C or VB applications. 00170 * @see FreppleInitialize 00171 */ 00172 DECLARE_EXPORT(int) FreppleWrapperInitialize(const char*); 00173 00174 /** Same as FreppleReadXMLData, but catches all exceptions and returns a 00175 * status instead. 00176 * 00177 * Use this function when calling the library from C or VB applications. 00178 * @see FreppleReadXMLData 00179 */ 00180 DECLARE_EXPORT(int) FreppleWrapperReadXMLData(char*, bool, bool); 00181 00182 /** Same as FreppleReadXMLFile, but catches all exceptions and returns a 00183 * status instead. 00184 * 00185 * Use this function when calling the library from C or VB applications. 00186 * @see FreppleReadXMLFile 00187 */ 00188 DECLARE_EXPORT(int) FreppleWrapperReadXMLFile(const char*, bool, bool); 00189 00190 /** Same as FreppleSaveFile, but catches all exceptions and returns a 00191 * status instead. 00192 * 00193 * Use this function when calling the library from C or VB applications. 00194 * @see FreppleSaveFile 00195 */ 00196 DECLARE_EXPORT(int) FreppleWrapperSaveFile(char*); 00197 00198 /** Same as FreppleSaveString, but catches all exceptions, returns a status 00199 * code and also leaves the memory buffer management to the user.<br> 00200 * This function can consume a lot of memory for big models! 00201 * 00202 * Use this function when calling the library from C or VB applications. 00203 * @see FreppleSaveString 00204 */ 00205 DECLARE_EXPORT(int) FreppleWrapperSaveString(char*, unsigned long); 00206 00207 /** Same as FreppleExit, but catches all exceptions and returns a 00208 * status instead. 00209 * 00210 * Use this function when calling the library from C or VB applications. 00211 * @see FreppleExit 00212 */ 00213 DECLARE_EXPORT(int) FreppleWrapperExit(); 00214 00215 #ifdef __cplusplus 00216 } // End of "extern C" 00217 #endif 00218 00219 #endif // End of FREPPLE_INTERFACE_H
Documentation generated by
