<HTML
><HEAD
><TITLE
>xmlrpc_server</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
REV="MADE"
HREF="edd@usefulinc.com"><LINK
REL="HOME"
TITLE="XML-RPC for PHP"
HREF="index.html"><LINK
REL="UP"
TITLE="Class documentation"
HREF="apidocs.html"><LINK
REL="PREVIOUS"
TITLE="xmlrpcval"
HREF="xmlrpcval.html"><LINK
REL="NEXT"
TITLE="Helper functions"
HREF="helpers.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>XML-RPC for PHP: version 1.0b9</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="xmlrpcval.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 5. Class documentation</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="helpers.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="XMLRPC-SERVER"
>xmlrpc_server</A
></H1
><P
>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:</P
><PRE
CLASS="PROGRAMLISTING"
> function foo ($params) {
...
}
$s=new xmlrpc_server( array("examples.myFunc" =>
array("function" => "foo")));
</PRE
><P
> 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
<TT
CLASS="CLASSNAME"
>xmlrpcresp</TT
>
object, which gets
serialized back to the caller. See server.php in this distribution for
examples of how to do this.
</P
><P
>Here is a more detailed look at what the handler function
<TT
CLASS="FUNCTION"
>foo</TT
> may do:</P
><PRE
CLASS="PROGRAMLISTING"
> 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"));
}
}
</PRE
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN607"
>The dispatch map</A
></H2
><P
>The first argument to the
<TT
CLASS="FUNCTION"
>xmlrpc_server</TT
> constructor is an array,
called the <I
CLASS="EMPHASIS"
>dispatch map</I
>. In this array is the
information the server needs to service the XML-RPC methods
you define.</P
><P
> 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:
</P
><P
></P
><UL
><LI
><P
><TT
CLASS="FUNCTION"
>function</TT
> - this entry is
mandatory. It must be a name of a function in the
global scope which services the XML-RPC method.</P
></LI
><LI
><P
><TT
CLASS="FUNCTION"
>signature</TT
> - this entry is an
array containg the possible signatures (see <A
HREF="xmlrpc-server.html#SIGNATURES"
>Signatures</A
>) 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.
</P
></LI
><LI
><P
> <TT
CLASS="FUNCTION"
>docstring</TT
> - this entry is a string
containing documentation for the method. The
documentation may contain HTML markup.
</P
></LI
></UL
><P
>Look at the <TT
CLASS="FILENAME"
>server.php</TT
> example in the
distribution to see what a dispatch map looks like.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="SIGNATURES"
>Method signatures</A
></H2
><P
>A signature is a description of a method's return type and
its parameter types. A method may have more than one
signature.</P
><P
>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 <PRE
CLASS="PROGRAMLISTING"
>string examples.getStateName(int)</PRE
> has the signature
<PRE
CLASS="PROGRAMLISTING"
>array($xmlrpcString, $xmlrpcInt)</PRE
> and, assuming that it the only possible signature for
the method, might be used like this in server creation:
<PRE
CLASS="PROGRAMLISTING"
>$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)));</PRE
>
</P
><P
>For convenience the strings representing the XML-RPC types
have been encoded as global variables:<PRE
CLASS="PROGRAMLISTING"
>$xmlrpcI4="i4";
$xmlrpcInt="int";
$xmlrpcBoolean="boolean";
$xmlrpcDouble="double";
$xmlrpcString="string";
$xmlrpcDateTime="dateTime.iso8601";
$xmlrpcBase64="base64";
$xmlrpcArray="array";
$xmlrpcStruct="struct";</PRE
></P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN635"
>Delaying the server response</A
></H2
><P
>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
<TT
CLASS="LITERAL"
>0</TT
> this will have the desired effect. You
can then use the <TT
CLASS="FUNCTION"
>service()</TT
> method of the
server class to service the request. For example:</P
><PRE
CLASS="PROGRAMLISTING"
>$s=new xmlrpc_server($myDispMap, 0);
// ... some code that does other stuff here
$s->service();</PRE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN641"
>Fault reporting</A
></H2
><P
>Fault codes for your servers should start at the
value indicated by
the global <TT
CLASS="LITERAL"
>$xmlrpcerruser</TT
> + 1.</P
><P
>Standard errors returned by the server include:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>1</TT
> <SPAN
CLASS="PHRASE"
>Unknown method</SPAN
></DT
><DD
><P
>Returned if the server was asked to dispatch a
method it didn't know about</P
></DD
><DT
><TT
CLASS="LITERAL"
>2</TT
> <SPAN
CLASS="PHRASE"
>Invalid return payload</SPAN
></DT
><DD
><P
>This error is actually generated by the client, not
server, code, but signifies that a server returned
something it couldn't understand.</P
></DD
><DT
><TT
CLASS="LITERAL"
>3</TT
> <SPAN
CLASS="PHRASE"
>Incorrect parameters</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><TT
CLASS="LITERAL"
>4</TT
> <SPAN
CLASS="PHRASE"
>Can't introspect: method unknown</SPAN
></DT
><DD
><P
>This error is generated by the builtin
<TT
CLASS="FUNCTION"
>system.*</TT
> methods when any kind of
introspection is attempted on a method undefined by the
server.</P
></DD
><DT
><TT
CLASS="LITERAL"
>5</TT
> <SPAN
CLASS="PHRASE"
>Didn't receive 200 OK from remote server</SPAN
></DT
><DD
><P
>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.</P
></DD
><DT
><TT
CLASS="LITERAL"
>100-</TT
> <SPAN
CLASS="PHRASE"
>XML parse errors</SPAN
></DT
><DD
><P
>Returns 100 plus the XML parser error code for the
fault that occurred. The
<TT
CLASS="FUNCTION"
>faultString</TT
> returned explains where
the parse error was in the incoming XML stream.</P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="xmlrpcval.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="helpers.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>xmlrpcval</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="apidocs.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Helper functions</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
0fb4c97bcdb0c3dace8e002a53d52c57
>
files
>
19
