request (de)serialization

• xmlrpc_encode_request
• xmlrpc_decode_request
• xmlrpc_encode
• xmlrpc_decode

server

• xmlrpc_server_create
• xmlrpc_server_destroy
• xmlrpc_server_register_method
• xmlrpc_server_call_method
• xmlrpc_server_set_method_description

introspection

• xmlrpc_server_register_introspection_callback
• xmlrpc_parse_method_descriptions
• xmlrpc_server_add_introspection_data

type manipulation

• xmlrpc_set_type
• xmlrpc_get_type

data structures

• xmlrpc_type
• output_options

request (de)serialization

these functions are used to convert between php native data types and the xml vocabulary in either direction. these, plus a network request function, are all that are required for a simple xmlrpc client

string xmlrpc_encode_request(string method, mixed params [, array output_options])

generate xml for a method call or response

returns: generated xml string or false on failure

args:

method: method to call on remote server. if null, generated xml is a response
params: argument data of any type. should match remote method signature
output_options: see output_options

string xmlrpc_decode_request(string method, string& method [, encoding])

decode xml into native php types. also returns methodname

returns: a single value of any type. usually an array.

args:

xml: raw xml to decode
method: variable to store method name in. (pass by ref). unchanged if not a method call
encoding: input encoding to translate to. defaults to iso-8859-1

string xmlrpc_encode(mixed value)

generate xml for a value, sans

returns: generated xml string or false on failure

args:

value: php value to be serialized

mixed xmlrpc_decode(string xml [,string encoding])

decode xml into native php types

returns: a single value of any type. usually an array.

args:

xml: raw xml to decode
encoding: input encoding to translate to. defaults to iso-8859-1

server

these functions are provided to enable easy creation of an xmlrpc server. basically, a server, once created, will register user methods and then process requests. the requests are in the form of raw xml data that can be passed directly to xmlrpc_server_call_method, which will call a previously registered user method and return the result.

handle xmlrpc_server_create()

create an xml server

returns: a handle to a newly created server or false on failure

void xmlrpc_server_destroy(handle server)

destroy server resources. it is good practice to call this function however if you do not, the server will be destroyed at the end of the request regardless.

returns: void

args:

handle: handle to a server created with xmlrpc_server_create

int xmlrpc_server_register_method(handle server, string method_name, string function)

register a php function to handle method matching method_name

returns: true, or false on failure

args:

handle: handle to a server created with xmlrpc_server_create
method_name: public (xmlrpc) method name
function: name of application (php) function that will implement the method

mixed xmlrpc_server_call_method(handle server, string xml, mixed user_data [, array output_options])

parse xml request and call method

returns: result of method call. this will either be a php value, or an xml encoded representation of that value, depending on output_options

args:

handle: handle to a server created with xmlrpc_server_create
xml: raw xml request string
user_data: any data the application needs to pass to the method handler function
output_options: see output_options

int xmlrpc_server_set_method_description(handle server, string method, struct description)

set method description for a method

returns: 1 if success. 0 otherwise

args:

handle: handle to a server created with xmlrpc_server_create
method: name of method being described
description: a method description, as defined by the system.describeMethods spec

introspection

it is important to have good documentation for any public API. the introspection functions enable server developers to generate highly descriptive documentation describing methods and their parameter types using a simple XML vocabulary. further, a callback mechanism is provided because documentation generation can be expensive and thus should only be done on demand, particularly in php's interpreted per request environment.

int xmlrpc_server_register_introspection_callback(handle server, string function)

register a php function to generate documentation when it is requested (lazy evaluation). this is more efficient and should be used in preference to the parse/add methods. the user function simply needs to return xml conforming to the introspection spec, and it will automatically be parsed, registered with the server and returned to the client as appropriate

returns: true, or false on failure

args:

handle: handle to a server created with xmlrpc_server_create
function: name of application (php) function that will implement the method. function signature is:
string func(mixed user_data)

array xmlrpc_parse_method_descriptions(string xml)

parse xml into a method description. See the introspection spec for a description of the xml vocabulary

returns: an array suitable for use with xmlrpc_server_add_introspection_data, or null if failure

args:

xml: xml conforming to introspection spec

bool xmlrpc_server_add_introspection_data(handle server, array desc)

adds introspection data to a server for future use

returns: bool. true if successful

args:

handle: handle to a server created with xmlrpc_server_create
desc: a description created with xmlrpc_parse_method_description

type manipulation

these functions are provided because of the unique implementation of the base64 and datetime data types. neither of these types are native to php, so it is necessary to store and retrieve that meta information somehow. This second implementation achievesthis by converting the value to a php object and storing type information in a member

bool xmlrpc_set_type(string &value, string type)

set xmlrpc type, base64 or datetime, for a php string value. if successful, the string will be converted to an object. the object will have a member 'xmlrpc_type', which contains the new type, and a member 'scalar', which contains the actual value

returns: true, or false on failure

args:

value: a reference to a string. typically containing either base64 or an iso 8601 conforming date.
type: a string. one of the allowed types

string xmlrpc_get_type(mixed value)

get xmlrpc type for a php value. especially useful for base64 and datetime strings which do not have php type equivalents.

returns: a string indicating the value's xmlrpc type. see types

args:

value: value to determine type of

data structures

xmlrpc_type

type: defines

values:

none: not a value

empty: value created but not set, or null.

base64: base64 encoded string, usually for sending binary data

boolean: true or false

datetime: iso 8601 encoded date/time string

double: floating point value

int: integer

string: a string

array: an array

struct: a struct

output_options

type: hashed array
sets xml generation options. any values not set will use defaults

values:

output_type: return data as either php native data types or xml encoded. ifphp is used, then the other values are ignored. default = xml

verbosity: determine compactness of generated xml. options are no_white_space, newlines_only, and pretty. default = pretty

escaping: determine how/whether to escape certain characters. 1 or more values are allowed. If multiple, they need to be specified as a sub-array. options are: cdata, non-ascii, non-print, and markup.default = non-ascii, non-print, markup

version: version of xml vocabulary to use. currently, three are supported: xmlrpc, soap 1.1, and simple. The keyword auto is also recognized to mean respond in whichever version the request came in. default = auto (when applicable), xmlrpc

encoding: the encoding that the data is in. Since PHP defaults to iso-8859-1 you will usually want to use that. Change it if you know what you are doing. default=iso-8859-1

example usage

$output_options = array( "output_type" => "xml", "verbosity" => "pretty", "escaping" => array("markup", "non-ascii", "non-print"), "version" => "xmlrpc", "encoding" => "utf-8" ); or $output_options = array("output_type" => "php");