XMLRPC Support

## XMLRPC Support XMLRPC Support — XML-RPC support |

## Synopsis

    #include <libsoup/soup.h>

    char *              soup_xmlrpc_build_method_call       (const char *method_name,
                                                             GValue *params,
                                                             int n_params);
    SoupMessage *       soup_xmlrpc_request_new             (const char *uri,
                                                             const char *method_name,
                                                             ...);
    gboolean            soup_xmlrpc_parse_method_response   (const char *method_response,
                                                             int length,
                                                             GValue *value,
                                                             GError **error);
    gboolean            soup_xmlrpc_extract_method_response (const char *method_response,
                                                             int length,
                                                             GError **error,
                                                             GType type,
                                                             ...);

    gboolean            soup_xmlrpc_parse_method_call       (const char *method_call,
                                                             int length,
                                                             char **method_name,
                                                             GValueArray **params);
    gboolean            soup_xmlrpc_extract_method_call     (const char *method_call,
                                                             int length,
                                                             char **method_name,
                                                             ...);
    char *              soup_xmlrpc_build_method_response   (GValue *value);
    char *              soup_xmlrpc_build_fault             (int fault_code,
                                                             const char *fault_format,
                                                             ...);
    void                soup_xmlrpc_set_response            (SoupMessage *msg,
                                                             GType type,
                                                             ...);
    void                soup_xmlrpc_set_fault               (SoupMessage *msg,
                                                             int fault_code,
                                                             const char *fault_format,
                                                             ...);

    #define             SOUP_XMLRPC_FAULT
    enum                SoupXMLRPCFault;

## Description

## Details

### soup_xmlrpc_build_method_call ()

    char *              soup_xmlrpc_build_method_call       (const char *method_name,
                                                             GValue *params,
                                                             int n_params);

This creates an XML-RPC methodCall and returns it as a string. This is the low-level method that `soup_xmlrpc_request_new()` is built on.

`params` is an array of GValue representing the parameters to `method`. (It is *not* a GValueArray, although if you have a GValueArray, you can just pass its `values`f and `n_values` fields.)

The correspondence between glib types and XML-RPC types is:

int: int (`G_TYPE_INT`) boolean: gboolean (`G_TYPE_BOOLEAN`) string: char* (`G_TYPE_STRING`) double: double (`G_TYPE_DOUBLE`) datetime.iso8601: SoupDate (`SOUP_TYPE_DATE`) base64: GByteArray (`SOUP_TYPE_BYTE_ARRAY`) struct: GHashTable (`G_TYPE_HASH_TABLE`) array: GValueArray (`G_TYPE_VALUE_ARRAY`)

For structs, use a GHashTable that maps strings to GValue; `soup_value_hash_new()` and related methods can help with this.

`method_name` : | the name of the XML-RPC method
`params` : | arguments to `method`. [array length=n_params]
`n_params` : | length of `params`
Returns : | the text of the methodCall, or `NULL` on error

### soup_xmlrpc_request_new ()

    SoupMessage *       soup_xmlrpc_request_new             (const char *uri,
                                                             const char *method_name,
                                                             ...);

Creates an XML-RPC methodCall and returns a SoupMessage, ready to send, for that method call.

The parameters are passed as type/value pairs; ie, first a GType, and then a value of the appropriate type, finally terminated by `G_TYPE_INVALID`.

`uri` : | URI of the XML-RPC service
`method_name` : | the name of the XML-RPC method to invoke at `uri`
`...` : | parameters for `method`
Returns : | a SoupMessage encoding the indicated XML-RPC request. [transfer full]

### soup_xmlrpc_parse_method_response ()

    gboolean            soup_xmlrpc_parse_method_response   (const char *method_response,
                                                             int length,
                                                             GValue *value,
                                                             GError **error);

Parses `method_response` and returns the return value in `value`. If `method_response` is a fault, `value` will be unchanged, and `error` will be set to an error of type `SOUP_XMLRPC_FAULT`, with the error code containing the fault code, and the error message containing the fault string. (If `method_response` cannot be parsed at all, `soup_xmlrpc_parse_method_response()` will return `FALSE`, but `error` will be unset.)

`method_response` : | the XML-RPC methodResponse string
`length` : | the length of `method_response`, or -1 if it is NUL-terminated
`value` : | on return, the return value from `method_call`. [out]
`error` : | error return value
Returns : | `TRUE` if a return value was parsed, `FALSE` if the response could not be parsed, or contained a fault.

### soup_xmlrpc_extract_method_response ()

    gboolean            soup_xmlrpc_extract_method_response (const char *method_response,
                                                             int length,
                                                             GError **error,
                                                             GType type,
                                                             ...);

Parses `method_response` and extracts the return value into a variable of the correct type.

If `method_response` is a fault, the return value will be unset, and `error` will be set to an error of type `SOUP_XMLRPC_FAULT`, with the error code containing the fault code, and the error message containing the fault string. (If `method_response` cannot be parsed at all, `soup_xmlrpc_extract_method_response()` will return `FALSE`, but `error` will be unset.)

`method_response` : | the XML-RPC methodResponse string
`length` : | the length of `method_response`, or -1 if it is NUL-terminated
`error` : | error return value
`type` : | the expected type of the return value
`...` : | location for return value
Returns : | `TRUE` if a return value was parsed, `FALSE` if the response was of the wrong type, or contained a fault.

### soup_xmlrpc_parse_method_call ()

    gboolean            soup_xmlrpc_parse_method_call       (const char *method_call,
                                                             int length,
                                                             char **method_name,
                                                             GValueArray **params);

Parses `method_call` to get the name and parameters, and returns the parameter values in a GValueArray; see also `soup_xmlrpc_extract_method_call()`, which is more convenient if you know in advance what the types of the parameters will be.

`method_call` : | the XML-RPC methodCall string
`length` : | the length of `method_call`, or -1 if it is NUL-terminated
`method_name` : | on return, the methodName from `method_call`. [out]
`params` : | on return, the parameters from `method_call`. [out]
Returns : | success or failure.

### soup_xmlrpc_extract_method_call ()

    gboolean            soup_xmlrpc_extract_method_call     (const char *method_call,
                                                             int length,
                                                             char **method_name,
                                                             ...);

Parses `method_call` to get the name and parameters, and puts the parameters into variables of the appropriate types.

The parameters are handled similarly to `soup_xmlrpc_build_method_call`, with pairs of types and values, terminated by `G_TYPE_INVALID`, except that values are pointers to variables of the indicated type, rather than values of the type.

See also `soup_xmlrpc_parse_method_call()`, which can be used if you don't know the types of the parameters.

`method_call` : | the XML-RPC methodCall string
`length` : | the length of `method_call`, or -1 if it is NUL-terminated
`method_name` : | on return, the methodName from `method_call`. [out]
`...` : | return types and locations for parameters
Returns : | success or failure.

### soup_xmlrpc_build_method_response ()

    char *              soup_xmlrpc_build_method_response   (GValue *value);

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use `soup_xmlrpc_build_fault()`.

The glib type to XML-RPC type mapping is as with `soup_xmlrpc_build_method_call()`, qv.

`value` : | the return value
Returns : | the text of the methodResponse, or `NULL` on error

### soup_xmlrpc_build_fault ()

    char *              soup_xmlrpc_build_fault             (int fault_code,
                                                             const char *fault_format,
                                                             ...);

This creates an XML-RPC fault response and returns it as a string. (To create a successful response, use `soup_xmlrpc_build_method_response()`.)

`fault_code` : | the fault code
`fault_format` : | a `printf()`-style format string
`...` : | the parameters to `fault_format`
Returns : | the text of the fault

### soup_xmlrpc_set_response ()

    void                soup_xmlrpc_set_response            (SoupMessage *msg,
                                                             GType type,
                                                             ...);

Sets the status code and response body of `msg` to indicate a successful XML-RPC call, with a return value given by `type` and the following varargs argument, of the type indicated by `type`.

`msg` : | an XML-RPC request
`type` : | the type of the response value
`...` : | the response value

### soup_xmlrpc_set_fault ()

    void                soup_xmlrpc_set_fault               (SoupMessage *msg,
                                                             int fault_code,
                                                             const char *fault_format,
                                                             ...);

Sets the status code and response body of `msg` to indicate an unsuccessful XML-RPC call, with the error described by `fault_code` and `fault_format`.

`msg` : | an XML-RPC request
`fault_code` : | the fault code
`fault_format` : | a `printf()`-style format string
`...` : | the parameters to `fault_format`

### SOUP_XMLRPC_FAULT

    #define SOUP_XMLRPC_FAULT soup_xmlrpc_fault_quark()

A GError domain representing an XML-RPC fault code. Used with SoupXMLRPCFault (although servers may also return fault codes not in that enumeration).

### enum SoupXMLRPCFault

    typedef enum {
    	SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED = -32700,
    	SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING = -32701,
    	SOUP_XMLRPC_FAULT_PARSE_ERROR_INVALID_CHARACTER_FOR_ENCODING = -32702,
    	SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_XML_RPC = -32600,
    	SOUP_XMLRPC_FAULT_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND = -32601,
    	SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_METHOD_PARAMETERS = -32602,
    	SOUP_XMLRPC_FAULT_SERVER_ERROR_INTERNAL_XML_RPC_ERROR = -32603,
    	SOUP_XMLRPC_FAULT_APPLICATION_ERROR = -32500,
    	SOUP_XMLRPC_FAULT_SYSTEM_ERROR = -32400,
    	SOUP_XMLRPC_FAULT_TRANSPORT_ERROR = -32300
    } SoupXMLRPCFault;

Pre-defined XML-RPC fault codes from http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php. These are an extension, not part of the XML-RPC spec; you can't assume servers will use them.

`SOUP_XMLRPC_FAULT_PARSE_ERROR_NOT_WELL_FORMED` | request was not well-formed
`SOUP_XMLRPC_FAULT_PARSE_ERROR_UNSUPPORTED_ENCODING` | request was in an unsupported encoding
`SOUP_XMLRPC_FAULT_PARSE_ERROR_INVALID_CHARACTER_FOR_ENCODING` | request contained an invalid character
`SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_XML_RPC` | request was not valid XML-RPC
`SOUP_XMLRPC_FAULT_SERVER_ERROR_REQUESTED_METHOD_NOT_FOUND` | method not found
`SOUP_XMLRPC_FAULT_SERVER_ERROR_INVALID_METHOD_PARAMETERS` | invalid parameters
`SOUP_XMLRPC_FAULT_SERVER_ERROR_INTERNAL_XML_RPC_ERROR` | internal error
`SOUP_XMLRPC_FAULT_APPLICATION_ERROR` | start of reserved range for application error codes
`SOUP_XMLRPC_FAULT_SYSTEM_ERROR` | start of reserved range for system error codes
`SOUP_XMLRPC_FAULT_TRANSPORT_ERROR` | start of reserved range for transport error codes