XMLRPC Support: libsoup Reference Manual

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

## Functions

char * | soup_xmlrpc_build_request ()
SoupMessage * | soup_xmlrpc_message_new ()
GVariant * | soup_xmlrpc_parse_response ()
GVariant * | soup_xmlrpc_variant_new_datetime ()
SoupDate * | soup_xmlrpc_variant_get_datetime ()
void | soup_xmlrpc_params_free ()
GVariant * | soup_xmlrpc_params_parse ()
char * | soup_xmlrpc_parse_request ()
char * | soup_xmlrpc_build_response ()
char * | soup_xmlrpc_build_fault ()
gboolean | soup_xmlrpc_message_set_response ()
void | soup_xmlrpc_message_set_fault ()

## Types and Values

#define | SOUP_XMLRPC_ERROR
enum | SoupXMLRPCError
#define | SOUP_XMLRPC_FAULT
enum | SoupXMLRPCFault
| SoupXMLRPCParams

## Includes

    #include <libsoup/soup.h>

## Description

## Functions

### soup_xmlrpc_build_request ()

    char *
    soup_xmlrpc_build_request (const char *method_name,
                               GVariant *params,
                               GError **error);

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

`params` is a GVariant tuple representing the method parameters.

Serialization details:

- "a{s*}" and "{s*}" are serialized as <struct>

- "ay" is serialized as <base64>

- Other arrays and tuples are serialized as <array>

- booleans are serialized as <boolean>

- byte, int16, uint16 and int32 are serialized as <int>

- uint32 and int64 are serialized as the nonstandard <i8> type

- doubles are serialized as <double>

- Strings are serialized as <string>

- Variants (i.e. "v" type) are unwrapped and their child is serialized.

- GVariants created by `soup_xmlrpc_variant_new_datetime()` are serialized as <dateTime.iso8601>

- Other types are not supported and will return `NULL` and set `error` . This notably includes: object-paths, signatures, uint64, handles, maybes and dictionaries with non-string keys.

If `params` is floating, it is consumed.

#### Parameters

method_name | the name of the XML-RPC method |
params | a GVariant tuple |
error | a GError, or `NULL` |

#### Returns

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

Since: 2.52

### soup_xmlrpc_message_new ()

    SoupMessage *
    soup_xmlrpc_message_new (const char *uri,
                             const char *method_name,
                             GVariant *params,
                             GError **error);

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

See `soup_xmlrpc_build_request()` for serialization details.

If `params` is floating, it is consumed.

#### Parameters

uri | URI of the XML-RPC service |
method_name | the name of the XML-RPC method to invoke at `uri` |
params | a GVariant tuple |
error | a GError, or `NULL` |

#### Returns

a SoupMessage encoding the indicated XML-RPC request, or `NULL` on error.

[transfer full]

Since: 2.52

### soup_xmlrpc_parse_response ()

    GVariant *
    soup_xmlrpc_parse_response (const char *method_response,
                                int length,
                                const char *signature,
                                GError **error);

Parses `method_response` and returns the return value. If `method_response` is a fault, `NULL` is returned, and `error` will be set to an error in the `SOUP_XMLRPC_FAULT` domain, with the error code containing the fault code, and the error message containing the fault string. If `method_response` cannot be parsed, `NULL` is returned, and `error` will be set to an error in the `SOUP_XMLRPC_ERROR` domain.

See `soup_xmlrpc_params_parse()` for deserialization details.

#### Parameters

method_response | the XML-RPC methodResponse string |
length | the length of `method_response` , or -1 if it is NUL-terminated |
signature | A valid GVariant type string, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a new (non-floating) GVariant, or `NULL`.

[transfer full]

Since: 2.52

### soup_xmlrpc_variant_new_datetime ()

    GVariant *
    soup_xmlrpc_variant_new_datetime (SoupDate *date);

Construct a special GVariant used to serialize a <dateTime.iso8601> node. See `soup_xmlrpc_build_request()`.

The actual type of the returned GVariant is unspecified and "v" or "*" should be used in variant format strings. For example:

    1
    args = g_variant_new ("(v)", soup_xmlrpc_variant_new_datetime (date));

#### Parameters

date | a SoupDate |

#### Returns

a floating GVariant.

Since: 2.52

### soup_xmlrpc_variant_get_datetime ()

    SoupDate *
    soup_xmlrpc_variant_get_datetime (GVariant *variant,
                                      GError **error);

Get the SoupDate from special GVariant created by `soup_xmlrpc_variant_new_datetime()` or by parsing a <dateTime.iso8601> node. See `soup_xmlrpc_params_parse()`.

If `variant` does not contain a datetime it will return an error but it is not considered a programmer error because it generally means parameters received are not in the expected type.

#### Parameters

variant | a GVariant |
error | a GError, or `NULL` |

#### Returns

a new SoupDate, or `NULL` on error.

Since: 2.52

### soup_xmlrpc_params_free ()

    void
    soup_xmlrpc_params_free (SoupXMLRPCParams *self);

Free a SoupXMLRPCParams returned by `soup_xmlrpc_parse_request()`.

#### Parameters

self | a SoupXMLRPCParams |

Since: 2.52

### soup_xmlrpc_params_parse ()

    GVariant *
    soup_xmlrpc_params_parse (SoupXMLRPCParams *self,
                              const char *signature,
                              GError **error);

Parse method parameters returned by `soup_xmlrpc_parse_request()`.

Deserialization details:

- If `signature` is provided, <int> and <i4> can be deserialized to byte, int16, uint16, int32, uint32, int64 or uint64. Otherwise it will be deserialized to int32. If the value is out of range for the target type it will return an error.

- <struct> will be deserialized to "a{sv}". `signature` could define another value type (e.g. "a{ss}").

- <array> will be deserialized to "av". `signature` could define another element type (e.g. "as") or could be a tuple (e.g. "(ss)").

- <base64> will be deserialized to "ay".

- <string> will be deserialized to "s".

- <dateTime.iso8601> will be deserialized to an unspecified variant type. If `signature` is provided it must have the generic "v" type, which means there is no guarantee that it's actually a datetime that has been received. `soup_xmlrpc_variant_get_datetime()` must be used to parse and type check this special variant.

- `signature` must not have maybes, otherwise an error is returned.

- Dictionaries must have string keys, otherwise an error is returned.

#### Parameters

self | A SoupXMLRPCParams |
signature | A valid GVariant type string, or `NULL`. | [allow-none]
error | a GError, or `NULL` |

#### Returns

a new (non-floating) GVariant, or `NULL`.

[transfer full]

Since: 2.52

### soup_xmlrpc_parse_request ()

    char *
    soup_xmlrpc_parse_request (const char *method_call,
                               int length,
                               SoupXMLRPCParams **params,
                               GError **error);

Parses `method_call` and return the method name. Method parameters can be parsed later using `soup_xmlrpc_params_parse()`.

#### Parameters

method_call | the XML-RPC methodCall string |
length | the length of `method_call` , or -1 if it is NUL-terminated |
params | on success, a new SoupXMLRPCParams. | [out]
error | a GError, or `NULL` |

#### Returns

method's name, or `NULL` on error.

[transfer full]

Since: 2.52

### soup_xmlrpc_build_response ()

    char *
    soup_xmlrpc_build_response (GVariant *value,
                                GError **error);

This creates a (successful) XML-RPC methodResponse and returns it as a string. To create a fault response, use `soup_xmlrpc_build_fault()`. This is the low-level method that `soup_xmlrpc_message_set_response()` is built on.

See `soup_xmlrpc_build_request()` for serialization details, but note that since a method can only have a single return value, `value` should not be a tuple here (unless the return value is an array).

If `value` is floating, it is consumed.

#### Parameters

value | the return value |
error | a GError, or `NULL` |

#### Returns

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

Since: 2.52

### 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_message_set_response ()

    gboolean
    soup_xmlrpc_message_set_response (SoupMessage *msg,
                                      GVariant *value,
                                      GError **error);

Sets the status code and response body of `msg` to indicate a successful XML-RPC call, with a return value given by `value` . To set a fault response, use `soup_xmlrpc_message_set_fault()`.

See `soup_xmlrpc_build_request()` for serialization details.

If `value` is floating, it is consumed.

#### Parameters

msg | an XML-RPC request |
value | a GVariant |
error | a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` otherwise.

Since: 2.52

### soup_xmlrpc_message_set_fault ()

    void
    soup_xmlrpc_message_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` |

Since: 2.52

## Types and Values

### SOUP_XMLRPC_ERROR

    #define SOUP_XMLRPC_ERROR soup_xmlrpc_error_quark()

### enum SoupXMLRPCError

#### Members

SOUP_XMLRPC_ERROR_ARGUMENTS |  |
SOUP_XMLRPC_ERROR_RETVAL |  |

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

### SoupXMLRPCParams

    typedef struct _SoupXMLRPCParams SoupXMLRPCParams;

Opaque structure containing XML-RPC methodCall parameter values. Can be parsed using `soup_xmlrpc_params_parse()` and freed with `soup_xmlrpc_params_free()`.

Since: 2.52