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: 1505 $  $LastChangedBy: jdetaeye $
00004   date : $LastChangedDate: 2011-08-26 18:55:08 +0200 (Fri, 26 Aug 2011) $
00005  ***************************************************************************/
00006 
00007 /***************************************************************************
00008  *                                                                         *
00009  * Copyright (C) 2007-2011 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();
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();
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

Documentation generated for frePPLe by  doxygen