XML-RPC for PHP: version 1.1
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