00001 /*************************************************************************** 00002 file : $URL: https://frepple.svn.sourceforge.net/svnroot/frepple/tags/0.8.0/include/freppleinterface.h $ 00003 version : $LastChangedRevision: 1011 $ $LastChangedBy: jdetaeye $ 00004 date : $LastChangedDate: 2009-08-05 12:59:02 +0200 (Wed, 05 Aug 2009) $ 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., 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 synchroneous, 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(); 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 /** Calling this function will save the frePPLe data in the file that 00112 * is passed as the argument. 00113 * 00114 * This method is synchroneous, i.e. it returns only when the complete 00115 * processing is finished. The method can throw exceptions, and the client 00116 * is responsible for defining the correct handlers for these. 00117 */ 00118 DECLARE_EXPORT(void) FreppleSaveFile(const char*); 00119 00120 /** This function causes the frepple executable to shut down in an orderly 00121 * way. 00122 * 00123 * This method is synchroneous, i.e. it returns only when the complete 00124 * processing is finished. The method can throw exceptions, and the client 00125 * is responsible for defining the correct handlers for these. 00126 */ 00127 DECLARE_EXPORT(void) FreppleExit(); 00128 00129 #ifdef __cplusplus 00130 /** Echo a message in the frePPLe log stream (which is either a file or 00131 * the standard output stream). 00132 * 00133 * This function is only available when using C++. The same functionality 00134 * is available to C with the function FreppleLog(const char*). 00135 */ 00136 DECLARE_EXPORT(void) FreppleLog(const std::string&); 00137 00138 /* The functions listed below can be called from C. */ 00139 extern "C" 00140 { 00141 00142 #endif 00143 /** Echo a message in the frePPLe log stream (which is either a file or 00144 * the standard output stream). 00145 */ 00146 DECLARE_EXPORT(void) FreppleLog(const char*); 00147 00148 /** Same as FreppleInitialize, but catches all exceptions and returns a 00149 * status instead. 00150 * 00151 * Use this function when calling the library from C or VB applications. 00152 * @see FreppleInitialize 00153 */ 00154 DECLARE_EXPORT(int) FreppleWrapperInitialize(); 00155 00156 /** Same as FreppleReadXMLData, 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 FreppleReadXMLData 00161 */ 00162 DECLARE_EXPORT(int) FreppleWrapperReadXMLData(char*, bool, bool); 00163 00164 /** Same as FreppleReadXMLFile, 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 FreppleReadXMLFile 00169 */ 00170 DECLARE_EXPORT(int) FreppleWrapperReadXMLFile(const char*, bool, bool); 00171 00172 /** Same as FreppleSaveFile, 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 FreppleSaveFile 00177 */ 00178 DECLARE_EXPORT(int) FreppleWrapperSaveFile(char*); 00179 00180 /** Same as FreppleExit, 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 FreppleExit 00185 */ 00186 DECLARE_EXPORT(int) FreppleWrapperExit(); 00187 00188 #ifdef __cplusplus 00189 } // End of "extern C" 00190 #endif 00191 00192 #endif // End of FREPPLE_INTERFACE_H