| simplexmlrpc.h | |
| Features | Features of the xmlrpc implementation |
| Alternative transports | Simplexmlrpc supports using a transport mechanism other than http/https. |
| Security levels | Simplexmlrpc supports an extension to the xmlrpc protocol. |
| Nil type support | Simplexmlrpc supports the Nil datatype/value extension that many popular xmlrpc implementations also support |
| Introspection | Simplexmlrpc supports very basic introspection. |
| Missing Features | |
| Date/ | Simplexmlrpc does not support the xmlrpc date/time format |
| Base64/ | Simplexmlrpc does not support the xmlrpc base64 type to support binary data |
| Usage | |
| Memory Managment | simplexmlrpc_value objects are reference-counted. |
| Types | API Types |
| simplexmlrpc_value | Represents an xmlrpc value |
| simplexmlrpc_registry | A registry of server-side methods that can be called remotely |
| simplexmlrpc_context | Context information for a server-side xmlrpc call. |
| simplexmlrpc_method_cb | Callback function that gets called with an xmlrpc method is executed |
| Common functions | Functions that are used in both the server and the client |
| simplexmlrpc_setErrorString | Set the error string in the value |
| simplexmlrpc_setErrorCode | Set the error code in the value |
| simplexmlrpc_getErrorCode | Get the error code from a value |
| simplexmlrpc_getErrorString | Get the error string from the value |
| simplexmlrpc_isError | Check if a value is an error |
| simplexmlrpc_isInt | Check if the value is an integer type |
| simplexmlrpc_isDouble | Check if the value is a double type |
| simplexmlrpc_isString | Check if the value is a string type |
| simplexmlrpc_isBoolean | Check if the value is a boolean type |
| simplexmlrpc_isArray | Check if the value is a array type |
| simplexmlrpc_isStruct | Check if the value is a struct type |
| simplexmlrpc_getIntValue | Get the 32-bit integer from the value |
| simplexmlrpc_getDoubleValue | Get the double-precision floating point number from the value |
| simplexmlrpc_getStringValue | Get the string from the value and put it into the passed in pointer |
| simplexmlrpc_getStringValueDup | Get the string from the value |
| simplexmlrpc_getBooleanValue | Get the boolean value |
| simplexmlrpc_getArraySize | Get the size of the array |
| simplexmlrpc_getArrayItem | Get an item from the array |
| simplexmlrpc_getStructSize | Get the size of the struct |
| simplexmlrpc_hasStructKey | Check if a struct has a key |
| simplexmlrpc_getStructKey | Get the key in the struct at the given index |
| simplexmlrpc_getStructValue | Get the value from the struct with the given key |
| simplexmlrpc_getStructValueStringDup | Helper function for getting a string value from a struct at a given key |
| simplexmlrpc_getStructValueInt | Helper function for getting an integer value from a struct at a given key |
| simplexmlrpc_createNil | Create a nil value |
| simplexmlrpc_createInt | Create a 32-bit integer value |
| simplexmlrpc_createDouble | Create a double-precision floating point value |
| simplexmlrpc_createBoolean | Create a boolean value |
| simplexmlrpc_createString | Create a string value |
| simplexmlrpc_createArray | Create an array |
| simplexmlrpc_createStruct | Create a structure value |
| simplexmlrpc_appendArrayItem | Append an item to an array |
| simplexmlrpc_addStructItem | Add a value to the structure |
| simplexmlrpc_incRef | Increment the value’s reference counter |
| simplexmlrpc_decRef | |
| simplexmlrpc_free | wrapper around free() |
| simplexmlrpc_freeStr | wrapper around free() |
| Server functions | Functions that are part of the server api |
| simplexmlrpc_createRegistry | Create a new xmlrpc registry |
| simplexmlrpc_destroyRegistry | Destroy an xmlrpc registry |
| simplexmlrpc_context_create | Create a method call context |
| simplexmlrpc_context_destroy | Destroys an method call context |
| simplexmlrpc_context_setFuncName | Set the function name for the context |
| simplexmlrpc_context_getFuncName | Get the name of the function that is being executed |
| simplexmlrpc_context_setSecurityLevel | Set the method call security level. |
| simplexmlrpc_context_getSecurityLevel | Get the current security level |
| simplexmlrpc_createError | Create an error value |
| simplexmlrpc_addIntrospection | Add introspection xmlrpc methods |
| simplexmlrpc_registry_addMethod | Register a method with the xmlrpc server |
| simplexmlrpc_processMessageFree | Process an xmlrpc request xml and return an xmlrpc response xml |
| simplexmlrpc_mongoose_register | Register an xmlrpc register with the mongoose http daemon at the given uri |
| simplexmlrpc_mongoose_switchRegister | Switch which method registry will get used. |
| Client functions | Functions for the client api |
| simplexmlrpc_generateCall | Generate an xmlrpc request xml for the given method and parameters |
| simplexmlrpc_httpCall | Make an xmlrpc call using libcurl |
| simplexmlrpc_httpCallWithAuth | Make an xmlrpc call using libcurl |
Simplexmlrpc supports using a transport mechanism other than http/https. The simplexmlrpc_generateCall() function can be used to generate the xmlrpc method call xml. This xml can then be passed to an xmlrpc server using any transport mechanism that you want. Interesting transports could include unix domain sockets or using stdin/stdout for interprocess communication. Another interesting option is for internal-process communication. You can actually pass the output of the simplexmlrpc_generateCall() function to the simplexmlrpc_processMessageFree() function. This allows a developer to make an xmlrpc call directly to the xmlrpc registry in its own process.
Simplexmlrpc supports an extension to the xmlrpc protocol. Every method has an integer-based security level. When an incoming xmlrpc request comes into the xmlrpc server, a security level number is assigned to the request. The request can only see methods that have a security level that is lower than or equal to its own security level. The best example of this feature are methods that are either open to the public or are limited to authenticated users. If an unauthenticated user calls the system.listMethods() introspection call, then only the public xmlrpc methods are shown. If an authenticated user calls the system.listMethods() method, then that user will see all the methods
simplexmlrpc_value objects are reference-counted. Use the simplexmlrpc_incRef and simplexmlrpc_decRef functions to increase and decrease references to the value objects. When the reference counter goes to 0, the object will automatically be deleted.
int simplexmlrpc_getStringValue( simplexmlrpc_value val, char * ret, size_t max )
Get the string from the value and put it into the passed in pointer
| val | value to get the string from |
| ret | char array to put the string into |
| max | max number of characters to put into the character array |
number of bytes put into the character array
const char *simplexmlrpc_getStructValueStringDup( simplexmlrpc_value val, const char * key )
Helper function for getting a string value from a struct at a given key
| val | struct value |
| key | key to get the value from |
the string value at the given key (needs to be free’ed)
void simplexmlrpc_context_setSecurityLevel( simplexmlrpc_context ctx, int level )
Set the method call security level. This method should be called by the http server before calling simplexmlrpc_processMessageFree
| ctx | context to set the security level in |
| level | security level |
void simplexmlrpc_registry_addMethod( simplexmlrpc_registry reg, const char * method, int secure, simplexmlrpc_method_cb func, void * data )
Register a method with the xmlrpc server
| reg | xmlrpc method registry |
| method | name of the method |
| secure | security level |
| func | function pointer that gets executed |
| data | user data |
int simplexmlrpc_processMessageFree( simplexmlrpc_registry reg, simplexmlrpc_context ctx, const char * xmlIn, char ** xmlOut )
Process an xmlrpc request xml and return an xmlrpc response xml
| reg | method registry |
| ctx | method call context |
| xmlIn | request xml |
| xmlOut | pointer to a character array that will contain the xml response |
0 if the call succeeded, 1 if it failed
void* simplexmlrpc_mongoose_register( simplexmlrpc_registry reg, struct mg_context * ctx, const char * uri, void * data )
Register an xmlrpc register with the mongoose http daemon at the given uri
| reg | method registry |
| ctx | mongoose context |
| uri | uri that will process xmlrpc methods |
| data | user data |
simplexmlrpc_mongoose_t structure
void simplexmlrpc_mongoose_switchRegister( void * ctx, simplexmlrpc_registry reg )
Switch which method registry will get used. This is used as a thread-safe way to add more methods to a registry. Instead of modifying an existing registry, you create a new one and switch it out
| ctx | simplexmlrpc_mongoose_t structure |
| reg | new method registry |
simplexmlrpc_value simplexmlrpc_httpCallWithAuth( const char * url, const char * user, const char * pass, const char * method, simplexmlrpc_value val )
Make an xmlrpc call using libcurl
| url | url to call |
| user | username |
| pass | password |
| method | method to call |
| val | method parameters |
return value
Set the error string in the value
void simplexmlrpc_setErrorString( simplexmlrpc_value val, const char * str )
Set the error code in the value
void simplexmlrpc_setErrorCode( simplexmlrpc_value val, int code )
Get the error code from a value
int simplexmlrpc_getErrorCode( simplexmlrpc_value val )
Get the error string from the value
const char *simplexmlrpc_getErrorString( simplexmlrpc_value val )
Check if a value is an error
int simplexmlrpc_isError( simplexmlrpc_value val )
Check if the value is an integer type
int simplexmlrpc_isInt( simplexmlrpc_value val )
Check if the value is a double type
int simplexmlrpc_isDouble( simplexmlrpc_value val )
Check if the value is a string type
int simplexmlrpc_isString( simplexmlrpc_value val )
Check if the value is a boolean type
int simplexmlrpc_isBoolean( simplexmlrpc_value val )
Check if the value is a array type
int simplexmlrpc_isArray( simplexmlrpc_value val )
Check if the value is a struct type
int simplexmlrpc_isStruct( simplexmlrpc_value val )
Get the 32-bit integer from the value
int32_t simplexmlrpc_getIntValue( simplexmlrpc_value val )
Get the double-precision floating point number from the value
double simplexmlrpc_getDoubleValue( simplexmlrpc_value val )
Get the string from the value and put it into the passed in pointer
int simplexmlrpc_getStringValue( simplexmlrpc_value val, char * ret, size_t max )
Get the string from the value
const char *simplexmlrpc_getStringValueDup( simplexmlrpc_value val )
Get the boolean value
int simplexmlrpc_getBooleanValue( simplexmlrpc_value val )
Get the size of the array
size_t simplexmlrpc_getArraySize( simplexmlrpc_value val )
Get an item from the array
simplexmlrpc_value simplexmlrpc_getArrayItem( simplexmlrpc_value val, size_t index )
Get the size of the struct
size_t simplexmlrpc_getStructSize( simplexmlrpc_value val )
Check if a struct has a key
int simplexmlrpc_hasStructKey( simplexmlrpc_value val, const char * key )
Get the key in the struct at the given index
const char *simplexmlrpc_getStructKey( simplexmlrpc_value val, size_t index )
Get the value from the struct with the given key
simplexmlrpc_value simplexmlrpc_getStructValue( simplexmlrpc_value val, const char * key )
Helper function for getting a string value from a struct at a given key
const char *simplexmlrpc_getStructValueStringDup( simplexmlrpc_value val, const char * key )
Helper function for getting an integer value from a struct at a given key
int32_t simplexmlrpc_getStructValueInt( simplexmlrpc_value val, const char * key )
Create a nil value
simplexmlrpc_value simplexmlrpc_createNil()
Create a 32-bit integer value
simplexmlrpc_value simplexmlrpc_createInt( int32_t val )
Create a double-precision floating point value
simplexmlrpc_value simplexmlrpc_createDouble( double val )
Create a boolean value
simplexmlrpc_value simplexmlrpc_createBoolean( int val )
Create a string value
simplexmlrpc_value simplexmlrpc_createString( const char * val )
Create an array
simplexmlrpc_value simplexmlrpc_createArray()
Create a structure value
simplexmlrpc_value simplexmlrpc_createStruct()
Append an item to an array
int simplexmlrpc_appendArrayItem( simplexmlrpc_value val, simplexmlrpc_value v )
Add a value to the structure
int simplexmlrpc_addStructItem( simplexmlrpc_value val, const char * key, simplexmlrpc_value v )
Increment the value’s reference counter
void simplexmlrpc_incRef( simplexmlrpc_value val )
void simplexmlrpc_decRef( simplexmlrpc_value val )
wrapper around free()
void simplexmlrpc_free( void * ptr )
wrapper around free()
void simplexmlrpc_freeStr( const char * ptr )
Create a new xmlrpc registry
simplexmlrpc_registry simplexmlrpc_createRegistry()
Destroy an xmlrpc registry
void simplexmlrpc_destroyRegistry( simplexmlrpc_registry reg )
Create a method call context
simplexmlrpc_context simplexmlrpc_context_create()
Destroys an method call context
void simplexmlrpc_context_destroy( simplexmlrpc_context ctx )
Set the function name for the context
void simplexmlrpc_context_setFuncName( simplexmlrpc_context ctx, const char * funcName )
Get the name of the function that is being executed
const char *simplexmlrpc_context_getFuncName( simplexmlrpc_context ctx )
Set the method call security level.
void simplexmlrpc_context_setSecurityLevel( simplexmlrpc_context ctx, int level )
Get the current security level
int simplexmlrpc_context_getSecurityLevel( simplexmlrpc_context ctx )
Create an error value
simplexmlrpc_value simplexmlrpc_createError( int code, const char * msg )
Add introspection xmlrpc methods
void simplexmlrpc_addIntrospection( simplexmlrpc_registry reg )
Register a method with the xmlrpc server
void simplexmlrpc_registry_addMethod( simplexmlrpc_registry reg, const char * method, int secure, simplexmlrpc_method_cb func, void * data )
Process an xmlrpc request xml and return an xmlrpc response xml
int simplexmlrpc_processMessageFree( simplexmlrpc_registry reg, simplexmlrpc_context ctx, const char * xmlIn, char ** xmlOut )
Register an xmlrpc register with the mongoose http daemon at the given uri
void* simplexmlrpc_mongoose_register( simplexmlrpc_registry reg, struct mg_context * ctx, const char * uri, void * data )
Switch which method registry will get used.
void simplexmlrpc_mongoose_switchRegister( void * ctx, simplexmlrpc_registry reg )
Generate an xmlrpc request xml for the given method and parameters
const char *simplexmlrpc_generateCall( const char * method, simplexmlrpc_value val )
Make an xmlrpc call using libcurl
simplexmlrpc_value simplexmlrpc_httpCall( const char * url, const char * method, simplexmlrpc_value val )
Make an xmlrpc call using libcurl
simplexmlrpc_value simplexmlrpc_httpCallWithAuth( const char * url, const char * user, const char * pass, const char * method, simplexmlrpc_value val )