API

API

API -- Class documentation of the package

XML_RPC_Client

This is the basic class used to represent a client of an XML-RPC server.

Methods

This class supports the following methods.

send()

This method takes the form:

Where $xmlrpc_message is an instance of XML_RPC_Message and $response is an instance of XML_RPC_Response (see XML_RPC_Response).

The $timeout is optional, and will be set to 0 (wait forever) if omitted. This timeout value is passed to fsockopen().

If the value of $response is 0 rather than an XML_RPC_Response object, then this signifies an I/O error has occured. You can find out what the I/O error was from the values $client->errno and $client->errstring.

In addition to low-level errors, the XML-RPC server you were querying may return an error in the XML_RPC_Response object. See XML_RPC_Response for details of how to handle these errors.

XML_RPC_Message

This class provides a representation for a request to an XML-RPC server. A client sends an XML_RPC_Message to a server, and receives back an XML_RPC_Response.

XML_RPC_Value

This is where a lot of the hard work gets done. This class enables the creation and encapsulation of values for XML-RPC.

Ensure you've read the XML-RPC spec at http://www.xmlrpc.com/stories/storyReader$7 before reading on as it will make things clearer.

The XML_RPC_Value class can store arbitrarily complicated values using the following types: i4, int, boolean, string, double, dateTime.iso8601, base64, array or struct. You should refer to the spec for more information on what each of these types mean.

Notes on types

int

The type i4 is accepted as a synonym for int. The value parsing code will always convert i4 to int: int is regarded by this implementation as the canonical name for this type.

base64

Base 64 encoding is performed transparently to the caller when using this type. Therefore you ought to consider it as a binary data type, for use when you want to pass none 7-bit clean data. Decoding is also transparent.

boolean

The values true and 1 map to true. All other values (including the empty string) are converted to false.

string

The characters <, >, " and & are converted to their entity equivalents &lt;, &gt;, &quot; and &amp; for transport through XML-RPC. The current XML-RPC spec recommends only encoding < and & but this implementation goes further, for reasons explained by the XML 1.0 recommendation.

TODO: &apos; entity is not yet supported

Methods

XML_RPC_Server

The current implementation of this class has been kept as simple as possible. The constructor for the server basically does all the work. Here's a minimal example:

function foo ($params) {
   ...
}

$s = new XML_RPC_Server(array("examples.myFunc" => array("function" => "foo")));

This performs everything you need to do with a server. The single argument is an associative array from method names to function names. The request is parsed and despatched to the relevant function, which is reponsible for returning a XML_RPC_Response object, which gets serialized back to the caller.

Here is a more detailed look at what the handler function foo() may do:

function foo ($params) {
    global $XML_RPC_erruser; // import user errcode value

    // $params is the received XML_RPC_Message object.
    if ($err) {
        // this is an error condition
        return new XML_RPC_Response(0, $XML_RPC_erruser+1, // user error 1
           "There's a problem, Captain");
    } else {
        // this is a successful value being returned
        return new XML_RPC_Response(new XML_RPC_Value("All's fine!", "string"));
    }
}

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:

1 Unknown method

Returned if the server was asked to dispatch a method it didn't know about

2 Invalid return payload

This error is actually generated by the client, not server, code, but signifies that a server returned something it couldn't understand.

3 Incorrect parameters

This error is generated when the server has signature(s) defined for a method, and the parameters passed by the client do not match any of signatures.

4 Can't introspect: method unknown

This error is generated by the builtin system.*() methods when any kind of introspection is attempted on a method undefined by the server.

5 Didn't receive 200 OK from remote server

This error is generated by the client when a remote server doesn't return HTTP/1.1 200 OK in response to a request. A more detailed error report is added onto the end of the phrase above.

100- XML parse errors

Returns 100 plus the XML parser error code for the fault that occurred. The faultString returned explains where the parse error was in the incoming XML stream.

XML_RPC_Dump

This class generates string representations of the data in XML_RPC_Value objects.

© Copyright 2003-2014 www.php-editors.com. The ultimate PHP Editor and PHP IDE site.