freppleinterface.h

Go to the documentation of this file.
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
Generated by  doxygen 1.6.2-20100208