XML-RPC for PHP: version 1.0b9
Prev | Chapter 5. Class documentation | Next

# xmlrpc_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 xmlrpc_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 `xmlrpcresp` object, which gets serialized back to the caller. See server.php in this distribution for examples of how to do this.

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

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

            // $params is an Array of xmlrpcval objects

            if ($err) {
              // this is an error condition
              return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
               "There's a problem, Captain");
            } else {
              // this is a successful value being returned
              return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
            }
      }

## The dispatch map

The first argument to the `xmlrpc_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.

Look at the `server.php` example in the distribution to see what a dispatch map looks like.

## 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. For instance, the method

    string examples.getStateName(int)

has the signature

    array($xmlrpcString, $xmlrpcInt)

and, assuming that it the only possible signature for the method, might be used like this in server creation:

    $findstate_sig=array(array($xmlrpcString, $xmlrpcInt));

    $findstate_doc='When passed an integer between 1 and 51 returns the
    name of a US state, where the integer is the index of that state name
    in an alphabetic order.';

    $s=new xmlrpc_server( array( "examples.getStateName" =>
    						array("function" => "findstate",
    						"signature" => $findstate_sig,
    						"docstring" => $findstate_doc)));

For convenience the strings representing the XML-RPC types have been encoded as global variables:

    $xmlrpcI4="i4";
    $xmlrpcInt="int";
    $xmlrpcBoolean="boolean";
    $xmlrpcDouble="double";
    $xmlrpcString="string";
    $xmlrpcDateTime="dateTime.iso8601";
    $xmlrpcBase64="base64";
    $xmlrpcArray="array";
    $xmlrpcStruct="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 xmlrpc_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.

Prev | Home | Next
xmlrpcval | Up | Helper functions