API

Creation

The constructor has the following syntax:

Here's an example client set up to query Userland's XML-RPC server at betty.userland.com:

$client = new XML_RPC_Client('/RPC2', 'betty.userland.com');

Methods

This class supports the following methods.

Creation

The constructor takes the following form:

Where $methodName is a string indicating the name of the method you wish to invoke, and $parameterArray is a simple Array of XML_RPC_Value objects. Here's an example message to the US state name server:

require_once "XML/RPC.php";
$msg = new XML_RPC_Message("examples.getStateName", array(new XML_RPC_Value(23, "int")));

This example requests the name of state number 23. For more information on XML_RPC_Value objects, see XML_RPC_Value.

Methods

Creation

The first instance is used when execution has happened without difficulty: $xmlrpcval is an XML_RPC_Value value with the result of the method execution contained in it.

The second type of constructor is used in case of failure. $errcode and $errstring are used to provide indication of what has gone wrong. See XML_RPC_Server for more information on passing error codes.

Methods

Notes on types

Creation

The constructor is the normal way to create an XML_RPC_Value. The constructor can take these forms:

The first constructor creates an empty value, which must be altered using the methods addScalar(), addArray() or addStruct() before it can be used.

The second constructor creates a simple string value.

The third constructor is used to create a scalar value. The second parameter must be a name of an XML-RPC type. Examples:

$myInt = new XML_RPC_Value(1267, "int");
$myString= new XML_RPC_Value("Hello, World!", "string");
$myBool = new XML_RPC_Value(1, "boolean");

The fourth constructor form can be used to compose complex XML-RPC values. The first argument is either a simple array in the case of an XML-RPC array or an associative array in the case of a struct. The elements of the array must be XML_RPC_Value objects themselves. Examples:

$myArray = new XML_RPC_Value(array(
    new XML_RPC_Value("Tom"), new XML_RPC_Value("Dick"),
    new XML_RPC_Value("Harry")), "array");

$myStruct = new XML_RPC_Value(array(
    "name" => new XML_RPC_Value("Tom"),
    "age" => new XML_RPC_Value(34, "int"),
    "geek" => new XML_RPC_Value(1, "boolean")), "struct");

Methods

The dispatch map

The first argument to the XML_RPC_Server() constructor is an array, called the dispatch map. In this array is the information the server needs to service the XML-RPC methods you define.

The dispatch map takes the form of an associative array of associative arrays: the outer array has one entry for each method, the key being the method name. The corresponding value is another associative array, which can have the following members:

• function - this entry is mandatory. It must be a name of a function in the global scope which services the XML-RPC method.

• signature - this entry is an array containg the possible signatures (see Signatures) for the method. If this entry is present then the server will check that the correct number and type of parameters have been sent for this method before dispatching it.

• docstring - this entry is a string containing documentation for the method. The documentation may contain HTML markup.

Method signatures

A signature is a description of a method's return type and its parameter types. A method may have more than one signature.

Within a server's dispatch map, each method has an array of possible signatures. Each signature is an array of types. The first entry is the return type.

Let's run through an example. Imagine you wanted to write a regular PHP function like this:

function is_8($input, $strict = false) { if ($strict) { return ($input === 8); } else { return ($input == 8); } }

To get it to work in an XML_RPC server, you would have to write it like this:

function is_8($params) { // This parameter is required. $param = $params->getParam(0); if (!XML_RPC_Value::isValue($param)) { return $param; } $input = $param->scalarval(); // This parameter is optional. $param = $params->getParam(1); if (!XML_RPC_Value::isValue($param)) { $strict = false; } else { $strict = $param->scalarval(); } if ($strict) { $answer = ($input === 8); } else { $answer = ($input == 8); } $val = new XML_RPC_Value($answer, 'boolean'); return new XML_RPC_Response($val); }

Here is a signature covering all of the possible permutations:

array( array('boolean', 'int'), array('boolean', 'int', 'boolean'), array('boolean', 'string'), array('boolean', 'string', 'boolean'), )

The server could be instatiated like this:

$server = new XML_RPC_Server( array( 'isan8' => array( 'function' => 'is_8', 'signature' => array( array('boolean', 'int'), array('boolean', 'int', 'boolean'), array('boolean', 'string'), array('boolean', 'string', 'boolean'), ), 'docstring' => 'Is the value an 8?' ), ), 1, 0 );

The strings representing the XML-RPC types have been encoded as global variables for your convenience:

$XML_RPC_I4       = 'i4';
$XML_RPC_Int      = 'int';
$XML_RPC_Boolean  = 'boolean';
$XML_RPC_Double   = 'double';
$XML_RPC_String   = 'string';
$XML_RPC_DateTime = 'dateTime.iso8601';
$XML_RPC_Base64   = 'base64';
$XML_RPC_Array    = 'array';
$XML_RPC_Struct   = 'struct';

Delaying the server response

You may want to construct the server, but for some reason not fulfill the request immediately (security verification, for instance). If you pass the constructor a second argument of 0 this will have the desired effect. You can then use the service() method of the server class to service the request. For example:

$s = new XML_RPC_Server($myDispMap, 0);

// ... some code that does other stuff here

$s->service();

Fault reporting

Fault codes for your servers should start at the value indicated by the global $xmlrpcerruser + 1.

Standard errors returned by the server include:

XML_RPC_encode()

Takes native php types and encodes them into XML_RPC PHP object format.

XML_RPC_decode()

Takes a message in PHP XML_RPC object format and translates it into native PHP types.