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 */
73 xmlrpc_nil, /* null value, eg NULL */
74 xmlrpc_base64, /* base64 value, eg binary data */
75 xmlrpc_boolean, /* boolean [0 | 1] */
76 xmlrpc_datetime, /* datetime [ISO8601 | time_t] */
77 xmlrpc_double, /* double / floating point */
78 xmlrpc_int, /* integer */
79 xmlrpc_string, /* string */
80 xmlrpc_vector /* vector, aka list, array */
84 /****d* VALUE/XMLRPC_VECTOR_TYPE
88 * Defines data types for XMLRPC_VECTOR.
89 * Deprecated for public use. See XMLRPC_VALUE_TYPE_EASY
95 typedef enum _XMLRPC_VECTOR_TYPE {
96 xmlrpc_vector_none, /* not an array */
97 xmlrpc_vector_array, /* no values may have key names */
98 xmlrpc_vector_mixed, /* some values may have key names */
99 xmlrpc_vector_struct /* all values must have key names */
100 } XMLRPC_VECTOR_TYPE;
103 /****d* VALUE/XMLRPC_VALUE_TYPE_EASY
105 * XMLRPC_VALUE_TYPE_EASY
107 * Defines data types for XMLRPC_VALUE, including vector types.
110 * XMLRPC_REQUEST_TYPE
113 typedef enum _XMLRPC_VALUE_TYPE_EASY {
114 xmlrpc_type_none, /* not a value */
115 xmlrpc_type_empty, /* empty value, eg NULL */
116 xmlrpc_type_base64, /* base64 value, eg binary data */
117 xmlrpc_type_boolean, /* boolean [0 | 1] */
118 xmlrpc_type_datetime, /* datetime [ISO8601 | time_t] */
119 xmlrpc_type_double, /* double / floating point */
120 xmlrpc_type_int, /* integer */
121 xmlrpc_type_string, /* string */
122 /* -- IMPORTANT: identical to XMLRPC_VALUE_TYPE to this point. -- */
123 xmlrpc_type_array, /* vector array */
124 xmlrpc_type_mixed, /* vector mixed */
125 xmlrpc_type_struct /* vector struct */
126 } XMLRPC_VALUE_TYPE_EASY;
130 /****d* VALUE/XMLRPC_REQUEST_TYPE
132 * XMLRPC_REQUEST_TYPE
134 * Defines data types for XMLRPC_REQUEST
140 typedef enum _xmlrpc_request_type {
141 xmlrpc_request_none, /* not a valid request */
142 xmlrpc_request_call, /* calling/invoking a method */
143 xmlrpc_request_response, /* responding to a method call */
144 } XMLRPC_REQUEST_TYPE;
147 /****d* VALUE/XMLRPC_ERROR_CODE
151 * All existing error codes
153 * XMLRPC_REQUEST_ERROR
156 typedef enum _xmlrpc_error_code {
157 xmlrpc_error_none = 0, /* not an error */
158 xmlrpc_error_parse_xml_syntax = -32700,
159 xmlrpc_error_parse_unknown_encoding = -32701,
160 xmlrpc_error_parse_bad_encoding = -32702,
161 xmlrpc_error_invalid_xmlrpc = -32600,
162 xmlrpc_error_unknown_method = -32601,
163 xmlrpc_error_invalid_params = -32602,
164 xmlrpc_error_internal_server = -32603,
165 xmlrpc_error_application = -32500,
166 xmlrpc_error_system = -32400,
167 xmlrpc_error_transport = -32300
171 #define xmlrpc_error_parse_xml_syntax_str "parse error. not well formed."
172 #define xmlrpc_error_parse_unknown_encoding_str "parse error. unknown encoding"
173 #define xmlrpc_error_parse_bad_encoding_str "parse error. invalid character for encoding"
174 #define xmlrpc_error_invalid_xmlrpc_str "server error. xml-rpc not conforming to spec"
175 #define xmlrpc_error_unknown_method_str "server error. method not found."
176 #define xmlrpc_error_invalid_params_str "server error. invalid method parameters"
177 #define xmlrpc_error_internal_server_str "server error. internal xmlrpc library error"
178 #define xmlrpc_error_application_str "application error."
179 #define xmlrpc_error_system_str "system error."
180 #define xmlrpc_error_transport_str "transport error."
184 /****d* VALUE/XMLRPC_VERSION
188 * Defines xml vocabulary used for generated xml
190 * XMLRPC_REQUEST_OUTPUT_OPTIONS
191 * XMLRPC_REQUEST_To_XML ()
194 typedef enum _xmlrpc_version {
195 xmlrpc_version_none = 0, /* not a recognized vocabulary */
196 xmlrpc_version_1_0 = 1, /* xmlrpc 1.0 standard vocab */
197 xmlrpc_version_simple = 2, /* alt more readable vocab */
198 xmlrpc_version_danda = 2, /* same as simple. legacy */
199 xmlrpc_version_soap_1_1 = 3 /* SOAP. version 1.1 */
203 /****s* VALUE/XMLRPC_REQUEST_OUTPUT_OPTIONS
205 * XMLRPC_REQUEST_OUTPUT_OPTIONS
207 * Defines output options for generated xml
210 * XML_ELEM_OUTPUT_OPTIONS
211 * XMLRPC_REQUEST_To_XML ()
214 typedef struct _xmlrpc_request_output_options {
215 STRUCT_XML_ELEM_OUTPUT_OPTIONS xml_elem_opts; /* xml_element specific output options */
216 XMLRPC_VERSION version; /* xml vocabulary to use */
217 } STRUCT_XMLRPC_REQUEST_OUTPUT_OPTIONS, *XMLRPC_REQUEST_OUTPUT_OPTIONS;
220 /****s* VALUE/XMLRPC_REQUEST_INPUT_OPTIONS
222 * XMLRPC_REQUEST_INPUT_OPTIONS
224 * Defines options for reading in xml data
227 * XML_ELEM_INPUT_OPTIONS
228 * XMLRPC_REQUEST_From_XML ()
231 typedef struct _xmlrpc_request_input_options {
232 STRUCT_XML_ELEM_INPUT_OPTIONS xml_elem_opts; /* xml_element specific output options */
233 } STRUCT_XMLRPC_REQUEST_INPUT_OPTIONS, *XMLRPC_REQUEST_INPUT_OPTIONS;
236 /****s* VALUE/XMLRPC_ERROR
240 * For the reporting and handling of errors
243 typedef struct _xmlrpc_error {
244 XMLRPC_ERROR_CODE code;
245 STRUCT_XML_ELEM_ERROR xml_elem_error; /* xml_element errors (parser errors) */
246 } STRUCT_XMLRPC_ERROR, *XMLRPC_ERROR;
250 /****d* VALUE/XMLRPC_CASE_COMPARISON
252 * XMLRPC_CASE_COMPARISON
254 * Defines case comparison options for XMLRPC_VALUE/VECTOR API's
260 typedef enum _xmlrpc_case_comparison {
261 xmlrpc_case_insensitive, /* use case-insensitive compare */
262 xmlrpc_case_sensitive /* use case-sensitive compare */
263 } XMLRPC_CASE_COMPARISON;
266 /****d* VALUE/XMLRPC_CASE
270 * Defines case behavior when setting IDs in XMLRPC_VALUE API's
272 * XMLRPC_CASE_COMPARISON
276 typedef enum _xmlrpc_case {
277 xmlrpc_case_exact, /* leave case alone */
278 xmlrpc_case_lower, /* lower-case id */
279 xmlrpc_case_upper /* upper-case id */
283 /* if you don't like these defaults, you can set them with XMLRPC_SetDefaultIdCase*() */
284 #define XMLRPC_DEFAULT_ID_CASE XMLRPC_GetDefaultIdCase()
285 #define XMLRPC_DEFAULT_ID_CASE_SENSITIVITY XMLRPC_GetDefaultIdCaseComparison()
287 /* opaque (non-public) types. defined locally in xmlrpc.c */
288 typedef struct _xmlrpc_request* XMLRPC_REQUEST;
289 typedef struct _xmlrpc_server* XMLRPC_SERVER;
290 typedef struct _xmlrpc_value* XMLRPC_VALUE;
292 /****d* VALUE/XMLRPC_Callback
296 * Function prototype for user defined method handlers (callbacks).
298 * XMLRPC_ServerRegisterMethod ()
299 * XMLRPC_ServerCallMethod ()
304 typedef XMLRPC_VALUE (*XMLRPC_Callback)(XMLRPC_SERVER server, XMLRPC_REQUEST input, void* userData);
307 /* ID Case Defaults */
308 XMLRPC_CASE XMLRPC_GetDefaultIdCase(void);
309 XMLRPC_CASE XMLRPC_SetDefaultIdCase(XMLRPC_CASE id_case);
310 XMLRPC_CASE_COMPARISON XMLRPC_GetDefaultIdCaseComparison(void);
311 XMLRPC_CASE_COMPARISON XMLRPC_SetDefaultIdCaseComparison(XMLRPC_CASE_COMPARISON id_case);
313 /* Vector manipulation */
314 int XMLRPC_VectorSize(XMLRPC_VALUE value);
315 XMLRPC_VALUE XMLRPC_VectorRewind(XMLRPC_VALUE value);
316 XMLRPC_VALUE XMLRPC_VectorNext(XMLRPC_VALUE value);
317 int XMLRPC_SetIsVector(XMLRPC_VALUE value, XMLRPC_VECTOR_TYPE type);
318 int XMLRPC_AddValueToVector(XMLRPC_VALUE target, XMLRPC_VALUE source);
319 int XMLRPC_AddValuesToVector(XMLRPC_VALUE target, ...);
320 int XMLRPC_VectorRemoveValue(XMLRPC_VALUE vector, XMLRPC_VALUE value);
321 XMLRPC_VALUE XMLRPC_VectorGetValueWithID_Case(XMLRPC_VALUE vector, const char* id, XMLRPC_CASE_COMPARISON id_case);
325 XMLRPC_VALUE XMLRPC_CreateValueBoolean(const char* id, int truth);
326 XMLRPC_VALUE XMLRPC_CreateValueBase64(const char* id, const char* s, int len);
327 XMLRPC_VALUE XMLRPC_CreateValueDateTime(const char* id, time_t time);
328 XMLRPC_VALUE XMLRPC_CreateValueDateTime_ISO8601(const char* id, const char *s);
329 XMLRPC_VALUE XMLRPC_CreateValueDouble(const char* id, double f);
330 XMLRPC_VALUE XMLRPC_CreateValueInt(const char* id, int i);
331 XMLRPC_VALUE XMLRPC_CreateValueString(const char* id, const char* s, int len);
332 XMLRPC_VALUE XMLRPC_CreateValueEmpty(void);
333 XMLRPC_VALUE XMLRPC_CreateVector(const char* id, XMLRPC_VECTOR_TYPE type);
336 void XMLRPC_CleanupValue(XMLRPC_VALUE value);
339 XMLRPC_VALUE XMLRPC_RequestSetError (XMLRPC_REQUEST request, XMLRPC_VALUE error);
340 XMLRPC_VALUE XMLRPC_RequestGetError (XMLRPC_REQUEST request);
343 XMLRPC_VALUE XMLRPC_CopyValue(XMLRPC_VALUE value);
344 XMLRPC_VALUE XMLRPC_DupValueNew(XMLRPC_VALUE xSource);
347 void XMLRPC_SetValueDateTime(XMLRPC_VALUE value, time_t time);
348 void XMLRPC_SetValueDateTime_ISO8601(XMLRPC_VALUE value, const char* s);
349 void XMLRPC_SetValueDouble(XMLRPC_VALUE value, double val);
350 void XMLRPC_SetValueInt(XMLRPC_VALUE value, int val);
351 void XMLRPC_SetValueBoolean(XMLRPC_VALUE value, int val);
352 const char *XMLRPC_SetValueString(XMLRPC_VALUE value, const char* s, int len);
353 void XMLRPC_SetValueBase64(XMLRPC_VALUE value, const char* s, int len);
354 const char *XMLRPC_SetValueID_Case(XMLRPC_VALUE value, const char* id, int len, XMLRPC_CASE id_case);
355 #define XMLRPC_SetValueID(value, id, len) XMLRPC_SetValueID_Case(value, id, len, XMLRPC_DEFAULT_ID_CASE)
358 const char* XMLRPC_GetValueString(XMLRPC_VALUE value);
359 int XMLRPC_GetValueStringLen(XMLRPC_VALUE value);
360 int XMLRPC_GetValueInt(XMLRPC_VALUE value);
361 int XMLRPC_GetValueBoolean(XMLRPC_VALUE value);
362 double XMLRPC_GetValueDouble(XMLRPC_VALUE value);
363 const char* XMLRPC_GetValueBase64(XMLRPC_VALUE value);
364 time_t XMLRPC_GetValueDateTime(XMLRPC_VALUE value);
365 const char* XMLRPC_GetValueDateTime_ISO8601(XMLRPC_VALUE value);
366 const char* XMLRPC_GetValueID(XMLRPC_VALUE value);
368 /* Type introspection */
369 XMLRPC_VALUE_TYPE XMLRPC_GetValueType(XMLRPC_VALUE v);
370 XMLRPC_VALUE_TYPE_EASY XMLRPC_GetValueTypeEasy(XMLRPC_VALUE v);
371 XMLRPC_VECTOR_TYPE XMLRPC_GetVectorType(XMLRPC_VALUE v);
373 /* Parsing and Creating XML */
374 XMLRPC_REQUEST XMLRPC_REQUEST_FromXML(const char* in_buf, int len, XMLRPC_REQUEST_INPUT_OPTIONS in_options);
375 XMLRPC_VALUE XMLRPC_VALUE_FromXML(const char* in_buf, int len, XMLRPC_REQUEST_INPUT_OPTIONS in_options);
376 char* XMLRPC_REQUEST_ToXML(XMLRPC_REQUEST request, int *buf_len);
377 char* XMLRPC_VALUE_ToXML(XMLRPC_VALUE val, int* buf_len);
379 /* Request manipulation funcs */
380 const char* XMLRPC_RequestSetMethodName(XMLRPC_REQUEST request, const char* methodName);
381 const char* XMLRPC_RequestGetMethodName(XMLRPC_REQUEST request);
382 XMLRPC_REQUEST XMLRPC_RequestNew(void);
383 void XMLRPC_RequestFree(XMLRPC_REQUEST request, int bFreeIO);
384 XMLRPC_REQUEST_OUTPUT_OPTIONS XMLRPC_RequestSetOutputOptions(XMLRPC_REQUEST request, XMLRPC_REQUEST_OUTPUT_OPTIONS output);
385 XMLRPC_REQUEST_OUTPUT_OPTIONS XMLRPC_RequestGetOutputOptions(XMLRPC_REQUEST request);
386 XMLRPC_VALUE XMLRPC_RequestSetData(XMLRPC_REQUEST request, XMLRPC_VALUE data);
387 XMLRPC_VALUE XMLRPC_RequestGetData(XMLRPC_REQUEST request);
388 XMLRPC_REQUEST_TYPE XMLRPC_RequestSetRequestType(XMLRPC_REQUEST request, XMLRPC_REQUEST_TYPE type);
389 XMLRPC_REQUEST_TYPE XMLRPC_RequestGetRequestType(XMLRPC_REQUEST request);
391 /* Server Creation/Destruction; Method Registration and Invocation */
392 XMLRPC_SERVER XMLRPC_ServerCreate(void);
393 XMLRPC_SERVER XMLRPC_GetGlobalServer(void); /* better to use XMLRPC_ServerCreate if you can */
394 void XMLRPC_ServerDestroy(XMLRPC_SERVER server);
395 int XMLRPC_ServerRegisterMethod(XMLRPC_SERVER server, const char *name, XMLRPC_Callback cb);
396 XMLRPC_Callback XMLRPC_ServerFindMethod(XMLRPC_SERVER server, const char* callName);
397 XMLRPC_VALUE XMLRPC_ServerCallMethod(XMLRPC_SERVER server, XMLRPC_REQUEST request, void* userData);
399 #include "xmlrpc_introspection.h"
401 /* Fault interrogation funcs */
402 int XMLRPC_ValueIsFault (XMLRPC_VALUE value);
403 int XMLRPC_ResponseIsFault(XMLRPC_REQUEST response);
404 int XMLRPC_GetValueFaultCode (XMLRPC_VALUE value);
405 int XMLRPC_GetResponseFaultCode(XMLRPC_REQUEST response);
406 const char* XMLRPC_GetValueFaultString (XMLRPC_VALUE value);
407 const char* XMLRPC_GetResponseFaultString (XMLRPC_REQUEST response);
410 /* Public Utility funcs */
411 XMLRPC_VALUE XMLRPC_UtilityCreateFault(int fault_code, const char* fault_string);
412 void XMLRPC_Free(void* mem);
413 const char* XMLRPC_GetVersionString(void);
415 /****d* VALUE/XMLRPC_MACROS
417 * Some Helpful Macros
419 * Some macros for making life easier. Should be self-explanatory.
421 * XMLRPC_AddValueToVector ()
422 * XMLRPC_VectorGetValueWithID_Case ()
427 /* Append values to vector */
428 #define XMLRPC_VectorAppendString(vector, id, s, len) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueString(id, s, len))
429 #define XMLRPC_VectorAppendBase64(vector, id, s, len) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueBase64(id, s, len))
430 #define XMLRPC_VectorAppendDateTime(vector, id, time) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDateTime(id, time))
431 #define XMLRPC_VectorAppendDateTime_ISO8601(vector, id, s) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDateTime_ISO8601(id, s))
432 #define XMLRPC_VectorAppendDouble(vector, id, f) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueDouble(id, f))
433 #define XMLRPC_VectorAppendInt(vector, id, i) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueInt(id, i))
434 #define XMLRPC_VectorAppendBoolean(vector, id, i) XMLRPC_AddValueToVector(vector, XMLRPC_CreateValueBoolean(id, i))
436 /* Get named values from vector */
437 #define XMLRPC_VectorGetValueWithID(vector, id) XMLRPC_VectorGetValueWithID_Case(vector, id, XMLRPC_DEFAULT_ID_CASE_SENSITIVITY)
438 #define XMLRPC_VectorGetStringWithID(vector, id) XMLRPC_GetValueString(XMLRPC_VectorGetValueWithID(vector, id))
439 #define XMLRPC_VectorGetBase64WithID(vector, id) XMLRPC_GetValueBase64(XMLRPC_VectorGetValueWithID(vector, id))
440 #define XMLRPC_VectorGetDateTimeWithID(vector, id) XMLRPC_GetValueDateTime(XMLRPC_VectorGetValueWithID(vector, id))
441 #define XMLRPC_VectorGetDoubleWithID(vector, id) XMLRPC_GetValueDouble(XMLRPC_VectorGetValueWithID(vector, id))
442 #define XMLRPC_VectorGetIntWithID(vector, id) XMLRPC_GetValueInt(XMLRPC_VectorGetValueWithID(vector, id))
443 #define XMLRPC_VectorGetBooleanWithID(vector, id) XMLRPC_GetValueBoolean(XMLRPC_VectorGetValueWithID(vector, id))
452 #endif /* not XMLRPC_ALREADY_INCLUDED */