mirror of
https://github.com/Yetangitu/ampache
synced 2025-10-04 18:29:40 +02:00
487 lines
No EOL
9 KiB
HTML
487 lines
No EOL
9 KiB
HTML
<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
|
|
> |