XMLRPC Support

XMLRPC Support — XML-RPC support

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:

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