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

Documentation generated for frePPLe by  doxygen