diff options
| author | Karl 'vollmerk' Vollmer <vollmer@ampache.org> | 2005-06-09 16:34:40 +0000 |
|---|---|---|
| committer | Karl 'vollmerk' Vollmer <vollmer@ampache.org> | 2005-06-09 16:34:40 +0000 |
| commit | bcad40a05ab2dc2a341a3227e30b96668bce4500 (patch) | |
| tree | 6fca27588d53a1b24705bd2834e9e643bb729bd1 /modules/xmlrpc/doc/xmlrpc-server.html | |
| download | ampache-bcad40a05ab2dc2a341a3227e30b96668bce4500.tar.gz ampache-bcad40a05ab2dc2a341a3227e30b96668bce4500.tar.bz2 ampache-bcad40a05ab2dc2a341a3227e30b96668bce4500.zip | |
New Import
Diffstat (limited to 'modules/xmlrpc/doc/xmlrpc-server.html')
| -rw-r--r-- | modules/xmlrpc/doc/xmlrpc-server.html | 487 |
1 files changed, 487 insertions, 0 deletions
diff --git a/modules/xmlrpc/doc/xmlrpc-server.html b/modules/xmlrpc/doc/xmlrpc-server.html new file mode 100644 index 00000000..da18e0f7 --- /dev/null +++ b/modules/xmlrpc/doc/xmlrpc-server.html @@ -0,0 +1,487 @@ +<HTML +><HEAD +><TITLE +>xmlrpc_server</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.77+"><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 +SUMMARY="Header navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>XML-RPC for PHP: version 1.1</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="xmlrpcval.html" +ACCESSKEY="P" +>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" +ACCESSKEY="N" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECT1" +><H1 +CLASS="SECT1" +><A +NAME="XMLRPC-SERVER" +></A +>xmlrpc_server</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="AEN658" +></A +>The dispatch map</H2 +><P +>The first argument to the + <TT +CLASS="FUNCTION" +>xmlrpc_server</TT +> constructor is an array, + called the <SPAN +CLASS="emphasis" +><I +CLASS="EMPHASIS" +>dispatch map</I +></SPAN +>. 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" +></A +>Method signatures</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="AEN686" +></A +>Delaying the server response</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="AEN692" +></A +>Fault reporting</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" +><SPAN +CLASS="PHRASE" +>Unknown method</SPAN +></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" +><SPAN +CLASS="PHRASE" +>Invalid return payload</SPAN +></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" +><SPAN +CLASS="PHRASE" +>Incorrect parameters</SPAN +></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" +><SPAN +CLASS="PHRASE" +>Can't introspect: method unknown</SPAN +></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" +><SPAN +CLASS="PHRASE" +>Didn't receive 200 OK from remote server</SPAN +></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" +><SPAN +CLASS="PHRASE" +>XML parse errors</SPAN +></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 +SUMMARY="Footer navigation table" +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="xmlrpcval.html" +ACCESSKEY="P" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +ACCESSKEY="H" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="helpers.html" +ACCESSKEY="N" +>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" +ACCESSKEY="U" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Helper functions</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file |