manpagez: man pages & more
html files: libsoup
Home | html | info | man

XMLRPC Support

XMLRPC Support — XML-RPC support

Types and Values

Object Hierarchy


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


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


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

 
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.