Manual Index

Advanced Server Construction

IXR_IntrospectionServer is an extension to IXR_Server which implements probably the most useful extension to the XML-RPC specification: Introspection. With introspection enabled web service clients can call methods on your server to find out more about the server - they can retrieve a list of required paramaters for various method calls and even retrieve documentation on methods directly from the server itself.

As with the basic server class, an IntrospectionServer can be implemented both using function callbacks or by writing a full web service class.

Using Function Callbacks

function getDate($args) {
    return date('js F Y');
}
function sayHelloTo($name) {
    return "Hello, $name";
}

$server = new IXR_IntrospectionServer();
// Now add the callbacks along with their introspection details
$server->addCallback(
    'test.getDate',  // XML-RPC method name
    'getDate',       // function to calback
    array('string'), // Array specifying the method signature
    'Returns the current date as a string'  // Documentation string
);
$server->addCallback(
    'test.sayHelloTo',
    'sayHelloTo',
    array('string', 'string'),
    'Returns the current date as a string'
);
// And serve the request
$server->serve();

Method Signatures

The method signature array describes both the type returned by the XML-RPC method and the types of the required arguments for that function. The first element in the array is the return type - it is compulsary. Any elements after that describe method paramaters. The IXR_IntrospectionServer will enforce these paramater types (unlike the basic IXR_Server which will pass any paramaters on to the methods without checking them) - if a method call is made to the server with an incorrect number of paramaters (or incorrect paramater types) the server will return an error message to the client.

When specifying the method signature array, use an array containing strings from the following list: 'date', 'base64', 'string', 'int', 'float', 'boolean', 'array', 'struct'

Building a web service class

Here is a sample web service class, implemented as an extension of the IXR_IntrospectionServer class:

class MyServer extends IXR_IntrospectionServer {
    function MyServer() {
        $this->IXR_IntrospectionServer();
        $this->addCallback(
            'test.getDate',
            'this:getDate',
            array('string'),
            'Returns the current date'
        );
        $this->addCallback(
            'test.getTime',
            'this:getTime',
            array('string'),
            'Returns the current time'
        );
        $this->addCallback(
            'test.helloWorld',
            'this:helloWorld',
            array('string'),
            'Returns "Hello World"'
        );
        $this->addCallback(
            'test.error',
            'this:ooh',
            array('struct'),
            'Triggers an error response'
        );
        $this->addCallback(
            'test.multiplied',
            'this:times10',
            array('int', 'struct'),
            'Returns X*10, X*100, X*1000'
        );
        $this->serve();
    }
    function getDate($args) {
        return date('r');
    }
    function getTime($args) {
        return date('H:i:s');
    }
    function helloWorld($args) {
        return 'Hello, World!';
    }
    function ooh($args) {
        return new IXR_Error(4000, 'ha ha ha');
    }
    function times10($value) {
        return array(
            'times10' => (int)$value * 10,
            'times100' => (int)$value * 10,
            'times1000' => (int)$value * 10,
        );
    }
}

// Run the server, serve the request
$s = new MyServer();