2 This file is part of libXMLRPC - a C library for xml-encoded function calls.
4 Author: Dan Libby (dan@libby.com)
5 Epinions.com may be contacted at feedback@epinions-inc.com
9 Copyright 2000 Epinions, Inc.
11 Subject to the following 3 conditions, Epinions, Inc. permits you, free
12 of charge, to (a) use, copy, distribute, modify, perform and display this
13 software and associated documentation files (the "Software"), and (b)
14 permit others to whom the Software is furnished to do so as well.
16 1) The above copyright notice and this permission notice shall be included
17 without modification in all copies or substantial portions of the
20 2) THE SOFTWARE IS PROVIDED "AS IS", WITHOUT ANY WARRANTY OR CONDITION OF
21 ANY KIND, EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
22 IMPLIED WARRANTIES OF ACCURACY, MERCHANTABILITY, FITNESS FOR A PARTICULAR
23 PURPOSE OR NONINFRINGEMENT.
25 3) IN NO EVENT SHALL EPINIONS, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,
26 SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES OR LOST PROFITS ARISING OUT
27 OF OR IN CONNECTION WITH THE SOFTWARE (HOWEVER ARISING, INCLUDING
28 NEGLIGENCE), EVEN IF EPINIONS, INC. IS AWARE OF THE POSSIBILITY OF SUCH
33 #ifndef XMLRPC_ALREADY_INCLUDED
34 #define XMLRPC_ALREADY_INCLUDED 1
37 #include "xml_element.h"
38 #include <time.h> /* for time_t */
44 /* allow version to be specified via compile line define */
45 #ifndef XMLRPC_LIB_VERSION
46 #define XMLRPC_LIB_VERSION "0.51"
49 /* this number, representing the date, must be increased each time the API changes */
50 #define XMLRPC_API_NO 20020623
52 /* this string should be changed with each packaged release */
53 #define XMLRPC_VERSION_STR "xmlrpc-epi v. " XMLRPC_LIB_VERSION
55 /* where to find more info. shouldn't need to change much */
56 #define XMLRPC_HOME_PAGE_STR "http://xmlprc-epi.sourceforge.net/"
59 /****d* VALUE/XMLRPC_VALUE_TYPE
63 * Defines data types for XMLRPC_VALUE
64 * Deprecated for public use. See XMLRPC_VALUE_TYPE_EASY
70 typedef enum _XMLRPC_VALUE_TYPE {
71 xmlrpc_none, /* not a value */
72 xmlrpc_empty, /* empty value, eg NULL */
73 xmlrpc_base64, /* base64 value, eg binary data */
74 xmlrpc_boolean, /* boolean [0 | 1] */
75 xmlrpc_datetime, /* datetime [ISO8601 | time_t] */
76 xmlrpc_double, /* double / floating point */
77 xmlrpc_int, /* integer */
78 xmlrpc_string, /* string */
79 xmlrpc_vector /* vector, aka list, array */
83 /****d* VALUE/XMLRPC_VECTOR_TYPE
87 * Defines data types for XMLRPC_VECTOR.
88 * Deprecated for public use. See XMLRPC_VALUE_TYPE_EASY
94 typedef enum _XMLRPC_VECTOR_TYPE {
95 xmlrpc_vector_none, /* not an array */
96 xmlrpc_vector_array, /* no values may have key names */
97 xmlrpc_vector_mixed, /* some values may have key names */
98 xmlrpc_vector_struct /* all values must have key names */
102 /****d* VALUE/XMLRPC_VALUE_TYPE_EASY
104 * XMLRPC_VALUE_TYPE_EASY
106 * Defines data types for XMLRPC_VALUE, including vector types.
109 * XMLRPC_REQUEST_TYPE
112 typedef enum _XMLRPC_VALUE_TYPE_EASY {
113 xmlrpc_type_none, /* not a value */
114 xmlrpc_type_empty, /* empty value, eg NULL */
115 xmlrpc_type_base64, /* base64 value, eg binary data */
116 xmlrpc_type_boolean, /* boolean [0 | 1] */
117 xmlrpc_type_datetime, /* datetime [ISO8601 | time_t] */
118 xmlrpc_type_double, /* double / floating point */
119 xmlrpc_type_int, /* integer */
120 xmlrpc_type_string, /* string */
121 /* -- IMPORTANT: identical to XMLRPC_VALUE_TYPE to this point. -- */
122 xmlrpc_type_array, /* vector array */
123 xmlrpc_type_mixed, /* vector mixed */
124 xmlrpc_type_struct /* vector struct */
125 } XMLRPC_VALUE_TYPE_EASY;
129 /****d* VALUE/XMLRPC_REQUEST_TYPE
131 * XMLRPC_REQUEST_TYPE
133 * Defines data types for XMLRPC_REQUEST
139 typedef enum _xmlrpc_request_type {
140 xmlrpc_request_none, /* not a valid request */
141 xmlrpc_request_call, /* calling/invoking a method */
142 xmlrpc_request_response, /* responding to a method call */
143 } XMLRPC_REQUEST_TYPE;
146 /****d* VALUE/XMLRPC_ERROR_CODE
150 * All existing error codes
152 * XMLRPC_REQUEST_ERROR
155 typedef enum _xmlrpc_error_code {
156 xmlrpc_error_none = 0, /* not an error */
157 xmlrpc_error_parse_xml_syntax = -32700,
158 xmlrpc_error_parse_unknown_encoding = -32701,
159 xmlrpc_error_parse_bad_encoding = -32702,
160 xmlrpc_error_invalid_xmlrpc = -32600,
161 xmlrpc_error_unknown_method = -32601,
162 xmlrpc_error_invalid_params = -32602,
163 xmlrpc_error_internal_server = -32603,
164 xmlrpc_error_application = -32500,
165 xmlrpc_error_system = -32400,
166 xmlrpc_error_transport = -32300
170 #define xmlrpc_error_parse_xml_syntax_str "parse error. not well formed."
171 #define xmlrpc_error_parse_unknown_encoding_str "parse error. unknown encoding"
172 #define xmlrpc_error_parse_bad_encoding_str "parse error. invalid character for encoding"
173 #define xmlrpc_error_invalid_xmlrpc_str "server error. xml-rpc not conforming to spec"
174 #define xmlrpc_error_unknown_method_str "server error. method not found."
175 #define xmlrpc_error_invalid_params_str "server error. invalid method parameters"
176 #define xmlrpc_error_internal_server_str "server error. internal xmlrpc library error"
177 #define xmlrpc_error_application_str "application error."
178 #define xmlrpc_error_system_str "system error."
179 #define xmlrpc_error_transport_str "transport error."
183 /****d* VALUE/XMLRPC_VERSION
187 * Defines xml vocabulary used for generated xml
189 * XMLRPC_REQUEST_OUTPUT_OPTIONS
190 * XMLRPC_REQUEST_To_XML ()
193 typedef enum _xmlrpc_version {
194 xmlrpc_version_none = 0, /* not a recognized vocabulary */
195 xmlrpc_version_1_0 = 1, /* xmlrpc 1.0 standard vocab */
196 xmlrpc_version_simple = 2, /* alt more readable vocab */
197 xmlrpc_version_danda = 2, /* same as simple. legacy */
198 xmlrpc_version_soap_1_1 = 3 /* SOAP. version 1.1 */
202 /****s* VALUE/XMLRPC_REQUEST_OUTPUT_OPTIONS
204 * XMLRPC_REQUEST_OUTPUT_OPTIONS
206 * Defines output options for generated xml
209 * XML_ELEM_OUTPUT_OPTIONS
210 * XMLRPC_REQUEST_To_XML ()
213 typedef struct _xmlrpc_request_output_options {
214 STRUCT_XML_ELEM_OUTPUT_OPTIONS xml_elem_opts; /* xml_element specific output options */
215 XMLRPC_VERSION version; /* xml vocabulary to use */
216 } STRUCT_XMLRPC_REQUEST_OUTPUT_OPTIONS, *XMLRPC_REQUEST_OUTPUT_OPTIONS;
219 /****s* VALUE/XMLRPC_REQUEST_INPUT_OPTIONS
221 * XMLRPC_REQUEST_INPUT_OPTIONS
223 * Defines options for reading in xml data
226 * XML_ELEM_INPUT_OPTIONS
227 * XMLRPC_REQUEST_From_XML ()
230 typedef struct _xmlrpc_request_input_options {
231 STRUCT_XML_ELEM_INPUT_OPTIONS xml_elem_opts; /* xml_element specific output options */
232 } STRUCT_XMLRPC_REQUEST_INPUT_OPTIONS, *XMLRPC_REQUEST_INPUT_OPTIONS;
235 /****s* VALUE/XMLRPC_ERROR
239 * For the reporting and handling of errors
242 typedef struct _xmlrpc_error {
243 XMLRPC_ERROR_CODE code;
244 STRUCT_XML_ELEM_ERROR xml_elem_error; /* xml_element errors (parser errors) */
245 } STRUCT_XMLRPC_ERROR, *XMLRPC_ERROR;
249 /****d* VALUE/XMLRPC_CASE_COMPARISON
251 * XMLRPC_CASE_COMPARISON
253 * Defines case comparison options for XMLRPC_VALUE/VECTOR API's
259 typedef enum _xmlrpc_case_comparison {
260 xmlrpc_case_insensitive, /* use case-insensitive compare */
261 xmlrpc_case_sensitive /* use case-sensitive compare */
262 } XMLRPC_CASE_COMPARISON;
265 /****d* VALUE/XMLRPC_CASE
269 * Defines case behavior when setting IDs in XMLRPC_VALUE API's
271 * XMLRPC_CASE_COMPARISON
275 typedef enum _xmlrpc_case {
276 xmlrpc_case_exact, /* leave case alone */
277 xmlrpc_case_lower, /* lower-case id */
278 xmlrpc_case_upper /* upper-case id */
282 /* if you don't like these defaults, you can set them with XMLRPC_SetDefaultIdCase*() */
283 #define XMLRPC_DEFAULT_ID_CASE XMLRPC_GetDefaultIdCase()
284 #define XMLRPC_DEFAULT_ID_CASE_SENSITIVITY XMLRPC_GetDefaultIdCaseComparison()
286 /* opaque (non-public) types. defined locally in xmlrpc.c */
287 typedef struct _xmlrpc_request* XMLRPC_REQUEST;
288 typedef struct _xmlrpc_server* XMLRPC_SERVER;
289 typedef struct _xmlrpc_value* XMLRPC_VALUE;
291 /****d* VALUE/XMLRPC_Callback
295 * Function prototype for user defined method handlers (callbacks).
297 * XMLRPC_ServerRegisterMethod ()
298 * XMLRPC_ServerCallMethod ()
303 typedef XMLRPC_VALUE (*XMLRPC_Callback)(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
306 /* ID Case Defaults */
307 XMLRPC_CASE XMLRPC_GetDefaultIdCase(void);
308 XMLRPC_CASE XMLRPC_SetDefaultIdCase(XMLRPC_CASE id_case);
309 XMLRPC_CASE_COMPARISON XMLRPC_GetDefaultIdCaseComparison(void);
310 XMLRPC_CASE_COMPARISON XMLRPC_SetDefaultIdCaseComparison(XMLRPC_CASE_COMPARISON id_case);
312 /* Vector manipulation */
313 int XMLRPC_VectorSize(XMLRPC_VALUE value);
314 XMLRPC_VALUE XMLRPC_VectorRewind(XMLRPC_VALUE value);
315 XMLRPC_VALUE XMLRPC_VectorNext(XMLRPC_VALUE value);
316 int XMLRPC_SetIsVector(XMLRPC_VALUE value, XMLRPC_VECTOR_TYPE type);
317 int XMLRPC_AddValueToVector(XMLRPC_VALUE target, XMLRPC_VALUE source);
318 int XMLRPC_AddValuesToVector(XMLRPC_VALUE target, ...);
319 int XMLRPC_VectorRemoveValue(XMLRPC_VALUE vector, XMLRPC_VALUE value);
320 XMLRPC_VALUE XMLRPC_VectorGetValueWithID_Case(XMLRPC_VALUE vector, const char* id, XMLRPC_CASE_COMPARISON id_case);
324 XMLRPC_VALUE XMLRPC_CreateValueBoolean(const char* id, int truth);
325 XMLRPC_VALUE XMLRPC_CreateValueBase64(const char* id, const char* s, int len);
326 XMLRPC_VALUE XMLRPC_CreateValueDateTime(const char* id, time_t time);
327 XMLRPC_VALUE XMLRPC_CreateValueDateTime_ISO8601(const char* id, const char *s);
328 XMLRPC_VALUE XMLRPC_CreateValueDouble(const char* id, double f);
329 XMLRPC_VALUE XMLRPC_CreateValueInt(const char* id, int i);
330 XMLRPC_VALUE XMLRPC_CreateValueString(const char* id, const char* s, int len);
331 XMLRPC_VALUE XMLRPC_CreateValueEmpty(void);
332 XMLRPC_VALUE XMLRPC_CreateVector(const char* id, XMLRPC_VECTOR_TYPE type);
335 void XMLRPC_CleanupValue(XMLRPC_VALUE value);
338 XMLRPC_VALUE XMLRPC_RequestSetError (XMLRPC_REQUEST request, XMLRPC_VALUE error);
339 XMLRPC_VALUE XMLRPC_RequestGetError (XMLRPC_REQUEST request);
342 XMLRPC_VALUE XMLRPC_CopyValue(XMLRPC_VALUE value);
343 XMLRPC_VALUE XMLRPC_DupValueNew(XMLRPC_VALUE xSource);
346 void XMLRPC_SetValueDateTime(XMLRPC_VALUE value, time_t time);
347 void XMLRPC_SetValueDateTime_ISO8601(XMLRPC_VALUE value, const char* s);
348 void XMLRPC_SetValueDouble(XMLRPC_VALUE value, double val);
349 void XMLRPC_SetValueInt(XMLRPC_VALUE value, int val);
350 void XMLRPC_SetValueBoolean(XMLRPC_VALUE value, int val);
351 const char *XMLRPC_SetValueString(XMLRPC_VALUE value, const char* s, int len);
352 void XMLRPC_SetValueBase64(XMLRPC_VALUE value, const char* s, int len);
353 const char *XMLRPC_SetValueID_Case(XMLRPC_VALUE value, const char* id, int len, XMLRPC_CASE id_case);
354 #define XMLRPC_SetValueID(value, id, len) XMLRPC_SetValueID_Case(value, id, len, XMLRPC_DEFAULT_ID_CASE)
357 const char* XMLRPC_GetValueString(XMLRPC_VALUE value);
358 int XMLRPC_GetValueStringLen(XMLRPC_VALUE value);
359 int XMLRPC_GetValueInt(XMLRPC_VALUE value);
360 int XMLRPC_GetValueBoolean(XMLRPC_VALUE value);
361 double XMLRPC_GetValueDouble(XMLRPC_VALUE value);
362 const char* XMLRPC_GetValueBase64(XMLRPC_VALUE value);
363 time_t XMLRPC_GetValueDateTime(XMLRPC_VALUE value);
364 const char* XMLRPC_GetValueDateTime_ISO8601(XMLRPC_VALUE value);
365 const char* XMLRPC_GetValueID(XMLRPC_VALUE value);
367 /* Type introspection */
368 XMLRPC_VALUE_TYPE XMLRPC_GetValueType(XMLRPC_VALUE v);
369 XMLRPC_VALUE_TYPE_EASY XMLRPC_GetValueTypeEasy(XMLRPC_VALUE v);
370 XMLRPC_VECTOR_TYPE XMLRPC_GetVectorType(XMLRPC_VALUE v);
372 /* Parsing and Creating XML */
373 XMLRPC_REQUEST XMLRPC_REQUEST_FromXML(const char* in_buf, int len, XMLRPC_REQUEST_INPUT_OPTIONS in_options);
374 XMLRPC_VALUE XMLRPC_VALUE_FromXML(const char* in_buf, int len, XMLRPC_REQUEST_INPUT_OPTIONS in_options);
375 char* XMLRPC_REQUEST_ToXML(XMLRPC_REQUEST request, int *buf_len);
376 char* XMLRPC_VALUE_ToXML(XMLRPC_VALUE val, int* buf_len);
378 /* Request manipulation funcs */
379 const char* XMLRPC_RequestSetMethodName(XMLRPC_REQUEST request, const char* methodName);
380 const char* XMLRPC_RequestGetMethodName(XMLRPC_REQUEST request);
381 XMLRPC_REQUEST XMLRPC_RequestNew(void);
382 void XMLRPC_RequestFree(XMLRPC_REQUEST request, int bFreeIO);
383 XMLRPC_REQUEST_OUTPUT_OPTIONS XMLRPC_RequestSetOutputOptions(XMLRPC_REQUEST request, XMLRPC_REQUEST_OUTPUT_OPTIONS output);
384 XMLRPC_REQUEST_OUTPUT_OPTIONS XMLRPC_RequestGetOutputOptions(XMLRPC_REQUEST request);
385 XMLRPC_VALUE XMLRPC_RequestSetData(XMLRPC_REQUEST request, XMLRPC_VALUE data);
386 XMLRPC_VALUE XMLRPC_RequestGetData(XMLRPC_REQUEST request);
387 XMLRPC_REQUEST_TYPE XMLRPC_RequestSetRequestType(XMLRPC_REQUEST request, XMLRPC_REQUEST_TYPE type);
388 XMLRPC_REQUEST_TYPE XMLRPC_RequestGetRequestType(XMLRPC_REQUEST request);
390 /* Server Creation/Destruction; Method Registration and Invocation */
391 XMLRPC_SERVER XMLRPC_ServerCreate(void);
392 XMLRPC_SERVER XMLRPC_GetGlobalServer(void); /* better to use XMLRPC_ServerCreate if you can */
393 void XMLRPC_ServerDestroy(XMLRPC_SERVER server);
394 int XMLRPC_ServerRegisterMethod(XMLRPC_SERVER server, const char *name, XMLRPC_Callback cb);
395 XMLRPC_Callback XMLRPC_ServerFindMethod(XMLRPC_SERVER server, const char* callName);
396 XMLRPC_VALUE XMLRPC_ServerCallMethod(XMLRPC_SERVER server, XMLRPC_REQUEST request, void* userData);
398 #include "xmlrpc_introspection.h"
400 /* Fault interrogation funcs */
401 int XMLRPC_ValueIsFault (XMLRPC_VALUE value);
402 int XMLRPC_ResponseIsFault(XMLRPC_REQUEST response);
403 int XMLRPC_GetValueFaultCode (XMLRPC_VALUE value);
404 int XMLRPC_GetResponseFaultCode(XMLRPC_REQUEST response);
405 const char* XMLRPC_GetValueFaultString (XMLRPC_VALUE value);
406 const char* XMLRPC_GetResponseFaultString (XMLRPC_REQUEST response);
409 /* Public Utility funcs */
410 XMLRPC_VALUE XMLRPC_UtilityCreateFault(int fault_code, const char* fault_string);
411 void XMLRPC_Free(void* mem);
412 const char* XMLRPC_GetVersionString(void);
414 /****d* VALUE/XMLRPC_MACROS
416 * Some Helpful Macros
418 * Some macros for making life easier. Should be self-explanatory.
420 * XMLRPC_AddValueToVector ()
421 * XMLRPC_VectorGetValueWithID_Case ()
426 /* Append values to vector */
427 #define XMLRPC_VectorAppendString(vector, id, s, len) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueString(id, s, len))
428 #define XMLRPC_VectorAppendBase64(vector, id, s, len) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueBase64(id, s, len))
429 #define XMLRPC_VectorAppendDateTime(vector, id, time) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDateTime(id, time))
430 #define XMLRPC_VectorAppendDateTime_ISO8601(vector, id, s) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDateTime_ISO8601(id, s))
431 #define XMLRPC_VectorAppendDouble(vector, id, f) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDouble(id, f))
432 #define XMLRPC_VectorAppendInt(vector, id, i) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueInt(id, i))
433 #define XMLRPC_VectorAppendBoolean(vector, id, i) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueBoolean(id, i))
435 /* Get named values from vector */
436 #define XMLRPC_VectorGetValueWithID(vector, id) XMLRPC_VectorGetValueWithID_Case(vector, id, XMLRPC_DEFAULT_ID_CASE_SENSITIVITY)
437 #define XMLRPC_VectorGetStringWithID(vector, id) XMLRPC_GetValueString(XMLRPC_VectorGetValueWithID(vector, id))
438 #define XMLRPC_VectorGetBase64WithID(vector, id) XMLRPC_GetValueBase64(XMLRPC_VectorGetValueWithID(vector, id))
439 #define XMLRPC_VectorGetDateTimeWithID(vector, id) XMLRPC_GetValueDateTime(XMLRPC_VectorGetValueWithID(vector, id))
440 #define XMLRPC_VectorGetDoubleWithID(vector, id) XMLRPC_GetValueDouble(XMLRPC_VectorGetValueWithID(vector, id))
441 #define XMLRPC_VectorGetIntWithID(vector, id) XMLRPC_GetValueInt(XMLRPC_VectorGetValueWithID(vector, id))
442 #define XMLRPC_VectorGetBooleanWithID(vector, id) XMLRPC_GetValueBoolean(XMLRPC_VectorGetValueWithID(vector, id))
451 #endif /* not XMLRPC_ALREADY_INCLUDED */