libsoup Reference Manual: XMLRPC Support

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

## Functions

char * | soup_xmlrpc_build_method_call ()
SoupMessage * | soup_xmlrpc_request_new ()
gboolean | soup_xmlrpc_parse_method_response ()
gboolean | soup_xmlrpc_extract_method_response ()
gboolean | soup_xmlrpc_parse_method_call ()
gboolean | soup_xmlrpc_extract_method_call ()
char * | soup_xmlrpc_build_method_response ()
char * | soup_xmlrpc_build_fault ()
void | soup_xmlrpc_set_response ()
void | soup_xmlrpc_set_fault ()

## Types and Values

#define | SOUP_XMLRPC_FAULT
enum | SoupXMLRPCFault

## Includes

    #include <libsoup/soup.h>

## Description

## Functions

### 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.

#### Parameters

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.

[nullable]

### 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`.

#### Parameters

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.)

#### Parameters

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.)

#### Parameters

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.

#### 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]
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.

#### 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.

#### Parameters

value | the return value |

#### Returns

the text of the methodResponse, or `NULL` on error.

[nullable]

### 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()`.)

#### Parameters

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` .

#### Parameters

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` .

#### Parameters

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

## Types and Values

### 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

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.

#### Members

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 |