| 1 |
Nomad XML-RPC Library |
| 2 |
by Trystan Scott Lee |
| 3 |
|
| 4 |
Please note that the Atheme team has modified the original code a little bit. |
| 5 |
|
| 6 |
================================================================================== |
| 7 |
|
| 8 |
The Nomad XML-RPC Library is a light weight, simple implentation of the XML-RPC |
| 9 |
specification (http://www.xmlrpc.com/spec), allowing developers to write applications |
| 10 |
that can process XML-RPC requests. |
| 11 |
|
| 12 |
The lib does not provide you with a socket listener it is up to the developer to |
| 13 |
handle the process of reading and writting to the sockets. |
| 14 |
|
| 15 |
Type |
| 16 |
./configure |
| 17 |
make |
| 18 |
make sample |
| 19 |
|
| 20 |
================================================================================== |
| 21 |
|
| 22 |
xml_register_method : register a xml-rpc method and its function which will handle the |
| 23 |
data that is processed. |
| 24 |
|
| 25 |
xmlrpc_unregister_method : unregister a xml-rpc method, this will clean up the memory |
| 26 |
used to register the method |
| 27 |
|
| 28 |
xmlrpc_set_buffer : set the function to which the lib will pass its data when its done |
| 29 |
formatting the answer |
| 30 |
|
| 31 |
xmlrpc_set_options : Some options are define able for each method call these are |
| 32 |
XMLRPC_HTTP_HEADER : in the spec http headers are required, however many implementations |
| 33 |
such as PHP do not send the http headers, use XMLRPC_ON, XMLRPC_OFF |
| 34 |
to enable |
| 35 |
|
| 36 |
XMLRPC_ENCODE : the spec allows you to set the text encoding, note that the default |
| 37 |
is off as defined by the spec |
| 38 |
|
| 39 |
XMLRPC_INTTAG : the xml tag for an integer data type is defined in two fashions <i4> |
| 40 |
and <int>, this option allows you to send the one you want, by default |
| 41 |
the lib sends <i4>, use XMLRPC_I4 for <i4> tags and XMLRPC_INT for <int> |
| 42 |
|
| 43 |
xmlrpc_generic_error : if you need to generate an error responce due to invalid information |
| 44 |
passed to your method you can call this function and it will generate |
| 45 |
a valid "fault" responce |
| 46 |
|
| 47 |
xmlrpc_process : pass the received socket data to this function so that it can process the |
| 48 |
data, and pass it to the method handler |
| 49 |
|
| 50 |
xmlrpc_getlast_error : should the code error out it will set the error code you can check this |
| 51 |
by calling on this function. |
| 52 |
|
| 53 |
xmlrpc_send : once your method call is done and you want to write data back to the client |
| 54 |
call on this function so that the formatting can be done. |
| 55 |
|
| 56 |
xmlrpc_char_encode : encode the string to be xml compliant, the xml-rpc spec only states that |
| 57 |
< and & need to converted but xml itself says anything else is invalid |
| 58 |
|
| 59 |
xmlrpc_array : formats an <array> responce |
| 60 |
|
| 61 |
xmlrpc_double : formats a <double> responce |
| 62 |
|
| 63 |
xmlrpc_base64 : formats a <base64> encoded responce |
| 64 |
|
| 65 |
xmlrpc_boolean : formats a <boolean> responce |
| 66 |
|
| 67 |
xmlrpc_string : formats a <string> responce |
| 68 |
|
| 69 |
xmlrpc_integer : formats a <i4> responce |
| 70 |
|
| 71 |
xmlrpc_time2date : formats a <dateTime.iso8601> responce |
| 72 |
|
| 73 |
xmlrpc_struct_begin : formats a <struct> response |
| 74 |
|
| 75 |
xmlrpc_struct_end : formats a </struct> response |
| 76 |
|
| 77 |
xmlrpc_decode64 : decoded a base64 string |
| 78 |
|
| 79 |
================================================================================= |
| 80 |
TODO |
| 81 |
1. xmlrpc_integer : to make sure it does not overflow |
| 82 |
2. xmlrpc_integer : to ensure that we are passed digits |
| 83 |
3. add struct class member |
| 84 |
4. add more error codes |
| 85 |
|
| 86 |
===================================================================================== |
| 87 |
Error Codes |
| 88 |
|
| 89 |
-1 : xmlrpc_process() was passed a NULL buffer |
| 90 |
-2 : xmlrpc_parse() returned NULL, likely not a XML document |
| 91 |
-3 : xmlrpc_method() returned NULL, likely XML document did not contain <methodname> |
| 92 |
-4 : findXMLRPCCommand() returned NULL, able to find the method |
| 93 |
-6 : method has no registered function |
| 94 |
-7 : function returned XMLRPC_STOP |
| 95 |
-8 : xmlrpc_set_buffer() was passed a NULL variable |
| 96 |
|
