freppleinterface.h
Go to the documentation of this file.
1 /***************************************************************************
2  * *
3  * Copyright (C) 2007-2013 by Johan De Taeye, frePPLe bvba *
4  * *
5  * This library is free software; you can redistribute it and/or modify it *
6  * under the terms of the GNU Affero General Public License as published *
7  * by the Free Software Foundation; either version 3 of the License, or *
8  * (at your option) any later version. *
9  * *
10  * This library is distributed in the hope that it will be useful, *
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13  * GNU Affero General Public License for more details. *
14  * *
15  * You should have received a copy of the GNU Affero General Public *
16  * License along with this program. *
17  * If not, see <http://www.gnu.org/licenses/>. *
18  * *
19  ***************************************************************************/
20 
21 /** @file freppleinterface.h
22  * @brief Public header file for C and C++.
23  *
24  * This is the public header file for high-level access to the library
25  * functionality.<br>
26  * The methods listed provide also a safe interface API for accessing the
27  * library functionality from C, C++, Visual Basic and other programming
28  * languages.
29  *
30  * When extending the library, use the header file frepple.h instead.<br>
31  * It provides a more detailed API to interface with frePPLe.
32  */
33 
34 #ifndef FREPPLE_INTERFACE_H
35 #define FREPPLE_INTERFACE_H
36 
37 #ifdef __cplusplus
38 #include <string>
39 #endif
40 
41 // For a windows shared library we use the C calling convention: __stdcall.
42 // Only such functions can be called from VBA...
43 // For cygwin we don't use the __stdcall, but still need the export/import.
44 #undef DECLARE_EXPORT
45 #if defined(WIN32) && !defined(DOXYGEN)
46  #ifdef __CYGWIN__
47  #ifdef FREPPLE_CORE
48  #define DECLARE_EXPORT(type) __declspec (dllexport) type
49  #else
50  #define DECLARE_EXPORT(type) __declspec (dllimport) type
51  #endif
52  #else
53  #ifdef FREPPLE_CORE
54  #define DECLARE_EXPORT(type) __declspec (dllexport) type __stdcall
55  #else
56  #define DECLARE_EXPORT(type) __declspec (dllimport) type __stdcall
57  #endif
58  #endif
59 #else
60  #define DECLARE_EXPORT(type) type
61 #endif
62 
63 /** This method returns a version string. */
64 DECLARE_EXPORT(const char*) FreppleVersion();
65 
66 /** This function should be called once when the client application starts,
67  * and before calling any other function in the API.
68  *
69  * This method is synchronous, i.e. it returns only when the complete
70  * processing is finished. The method can throw exceptions, and the client
71  * is responsible for defining the correct handlers for these.
72  */
74 
75 /** The character buffer pointed to by the first parameter contains data in
76  * XML format that is passed on to frePPLe for processing.<br>
77  * The second argument specifies whether frePPLe should validate the data
78  * against the XSD schema.<br>
79  * The last argument specifies whether frePPLe needs to perform only the
80  * validation and skip the actual processing.
81  *
82  * The client is responsible for the memory management in the data buffer.
83  *
84  * This method is synchroneous, i.e. it returns only when the complete
85  * processing is finished. The method can throw exceptions, and the client
86  * is responsible for defining the correct handlers for these.
87  */
88 DECLARE_EXPORT(void) FreppleReadXMLData(const char*, bool, bool);
89 
90 /** The first parameter is the name of a file that contains data in XML
91  * format for frePPLe processing. If a NULL pointer is passed, frepple
92  * will read from the standard input.<br>
93  * The second argument specifies whether frePPLe should validate the data
94  * against the XSD schema.<br>
95  * The last argument specifies whether frePPLe needs to perform only the
96  * validation and skip the actual processing.
97  *
98  * This method is synchroneous, i.e. it returns only when the complete
99  * processing is finished. The method can throw exceptions, and the client
100  * is responsible for defining the correct handlers for these.
101  */
102 DECLARE_EXPORT(void) FreppleReadXMLFile(const char*, bool, bool);
103 
104 /** Execute the Python code in a file.
105  *
106  * This method is synchroneous, i.e. it returns only when the complete
107  * processing is finished. The method can throw exceptions, and the client
108  * is responsible for defining the correct handlers for these.
109  */
110 DECLARE_EXPORT(void) FreppleReadPythonFile(const char*);
111 
112 /** Calling this function will save the frePPLe data in the file that
113  * is passed as the argument.
114  *
115  * This method is synchroneous, i.e. it returns only when the complete
116  * processing is finished. The method can throw exceptions, and the client
117  * is responsible for defining the correct handlers for these.
118  */
119 DECLARE_EXPORT(void) FreppleSaveFile(const char*);
120 
121 /** This function causes the frepple executable to shut down in an orderly
122  * way.
123  *
124  * This method is synchroneous, i.e. it returns only when the complete
125  * processing is finished. The method can throw exceptions, and the client
126  * is responsible for defining the correct handlers for these.
127  */
129 
130 #ifdef __cplusplus
131 /** Echo a message in the frePPLe log stream (which is either a file or
132  * the standard output stream).
133  *
134  * This function is only available when using C++. The same functionality
135  * is available to C with the function FreppleLog(const char*).
136  */
137 DECLARE_EXPORT(void) FreppleLog(const std::string&);
138 
139 /* The functions listed below can be called from C. */
140 extern "C"
141 {
142 
143 #endif
144  /** Echo a message in the frePPLe log stream (which is either a file or
145  * the standard output stream).
146  */
147  DECLARE_EXPORT(void) FreppleLog(const char*);
148 
149  /** Same as FreppleInitialize, but catches all exceptions and returns a
150  * status instead.
151  *
152  * Use this function when calling the library from C or VB applications.
153  * @see FreppleInitialize
154  */
156 
157  /** Same as FreppleReadXMLData, but catches all exceptions and returns a
158  * status instead.
159  *
160  * Use this function when calling the library from C or VB applications.
161  * @see FreppleReadXMLData
162  */
163  DECLARE_EXPORT(int) FreppleWrapperReadXMLData(char*, bool, bool);
164 
165  /** Same as FreppleReadXMLFile, but catches all exceptions and returns a
166  * status instead.
167  *
168  * Use this function when calling the library from C or VB applications.
169  * @see FreppleReadXMLFile
170  */
171  DECLARE_EXPORT(int) FreppleWrapperReadXMLFile(const char*, bool, bool);
172 
173  /** Same as FreppleReadPythonFile, but catches all exceptions and returns a
174  * status instead.
175  *
176  * Use this function when calling the library from C or VB applications.
177  * @see FreppleReadPythonFile
178  */
180 
181  /** Same as FreppleSaveFile, but catches all exceptions and returns a
182  * status instead.
183  *
184  * Use this function when calling the library from C or VB applications.
185  * @see FreppleSaveFile
186  */
188 
189  /** Same as FreppleExit, but catches all exceptions and returns a
190  * status instead.
191  *
192  * Use this function when calling the library from C or VB applications.
193  * @see FreppleExit
194  */
196 
197 #ifdef __cplusplus
198 } // End of "extern C"
199 #endif
200 
201 #endif // End of FREPPLE_INTERFACE_H