"Fossies" - the Fresh Open Source Software Archive

Member "phpgroupware-0.9.16.017/xmlrpc/doc/xmlrpc-server.html" (7 Aug 2001, 8858 Bytes) of package /linux/www/old/phpgroupware-0.9.16.017.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <HTML
    2 ><HEAD
    3 ><TITLE
    4 >xmlrpc_server</TITLE
    5 ><META
    6 NAME="GENERATOR"
    7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64
    8 "><LINK
    9 REV="MADE"
   10 HREF="edd@usefulinc.com"><LINK
   11 REL="HOME"
   12 TITLE="XML-RPC for PHP"
   13 HREF="index.html"><LINK
   14 REL="UP"
   15 TITLE="Class documentation"
   16 HREF="apidocs.html"><LINK
   17 REL="PREVIOUS"
   18 TITLE="xmlrpcval"
   19 HREF="xmlrpcval.html"><LINK
   20 REL="NEXT"
   21 TITLE="Helper functions"
   22 HREF="helpers.html"></HEAD
   23 ><BODY
   24 CLASS="SECT1"
   25 BGCOLOR="#FFFFFF"
   26 TEXT="#000000"
   27 LINK="#0000FF"
   28 VLINK="#840084"
   29 ALINK="#0000FF"
   30 ><DIV
   31 CLASS="NAVHEADER"
   32 ><TABLE
   33 WIDTH="100%"
   34 BORDER="0"
   35 CELLPADDING="0"
   36 CELLSPACING="0"
   37 ><TR
   38 ><TH
   39 COLSPAN="3"
   40 ALIGN="center"
   41 >XML-RPC for PHP: version 1.0b9</TH
   42 ></TR
   43 ><TR
   44 ><TD
   45 WIDTH="10%"
   46 ALIGN="left"
   47 VALIGN="bottom"
   48 ><A
   49 HREF="xmlrpcval.html"
   50 >Prev</A
   51 ></TD
   52 ><TD
   53 WIDTH="80%"
   54 ALIGN="center"
   55 VALIGN="bottom"
   56 >Chapter 5. Class documentation</TD
   57 ><TD
   58 WIDTH="10%"
   59 ALIGN="right"
   60 VALIGN="bottom"
   61 ><A
   62 HREF="helpers.html"
   63 >Next</A
   64 ></TD
   65 ></TR
   66 ></TABLE
   67 ><HR
   68 ALIGN="LEFT"
   69 WIDTH="100%"></DIV
   70 ><DIV
   71 CLASS="SECT1"
   72 ><H1
   73 CLASS="SECT1"
   74 ><A
   75 NAME="XMLRPC-SERVER"
   76 >xmlrpc_server</A
   77 ></H1
   78 ><P
   79 >The current implementation of this class has been
   80         kept as simple as possible. The constructor for the server
   81         basically does all the work. Here's a minimal example:</P
   82 ><PRE
   83 CLASS="PROGRAMLISTING"
   84 >  function foo ($params) {
   85      ...
   86   }
   87 
   88   $s=new xmlrpc_server( array("examples.myFunc" =&#62;
   89                 array("function" =&#62; "foo")));
   90       </PRE
   91 ><P
   92 >       This performs everything you need to do with a server.  The single
   93         argument is an associative array from method names to function
   94         names. The request is parsed and despatched to the relevant function,
   95         which is reponsible for returning a
   96         <TT
   97 CLASS="CLASSNAME"
   98 >xmlrpcresp</TT
   99 >
  100         object, which gets
  101         serialized back to the caller.  See server.php in this distribution for
  102         examples of how to do this.
  103       </P
  104 ><P
  105 >Here is a more detailed look at what the handler function
  106         <TT
  107 CLASS="FUNCTION"
  108 >foo</TT
  109 > may do:</P
  110 ><PRE
  111 CLASS="PROGRAMLISTING"
  112 >&#13;  function foo ($params) {
  113         global $xmlrpcerruser; // import user errcode value
  114 
  115         // $params is an Array of xmlrpcval objects
  116 
  117         if ($err) {
  118           // this is an error condition
  119           return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
  120            "There's a problem, Captain");
  121         } else {
  122           // this is a successful value being returned
  123           return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
  124         }
  125   }
  126         </PRE
  127 ><DIV
  128 CLASS="SECT2"
  129 ><H2
  130 CLASS="SECT2"
  131 ><A
  132 NAME="AEN607"
  133 >The dispatch map</A
  134 ></H2
  135 ><P
  136 >The first argument to the
  137                     <TT
  138 CLASS="FUNCTION"
  139 >xmlrpc_server</TT
  140 > constructor is an array,
  141                     called the <I
  142 CLASS="EMPHASIS"
  143 >dispatch map</I
  144 >.  In this array is the
  145                     information the server needs to service the XML-RPC methods
  146                     you define.</P
  147 ><P
  148 >                   The dispatch map takes the form of an associative array of
  149                     associative arrays: the outer array has one entry for each
  150                     method, the key being the method name. The corresponding value 
  151                     is another associative array, which can have the following members:
  152                 </P
  153 ><P
  154 ></P
  155 ><UL
  156 ><LI
  157 ><P
  158 ><TT
  159 CLASS="FUNCTION"
  160 >function</TT
  161 > - this entry is
  162                                     mandatory. It must be a name of a function in the
  163                                     global scope which services the XML-RPC method.</P
  164 ></LI
  165 ><LI
  166 ><P
  167 ><TT
  168 CLASS="FUNCTION"
  169 >signature</TT
  170 > - this entry is an
  171                             array containg the possible signatures (see <A
  172 HREF="xmlrpc-server.html#SIGNATURES"
  173 >Signatures</A
  174 >) for the method. If
  175                             this entry is present then the server will check that the
  176                             correct number and type of parameters have been sent for
  177                             this method before dispatching it.
  178                         </P
  179 ></LI
  180 ><LI
  181 ><P
  182 >                           <TT
  183 CLASS="FUNCTION"
  184 >docstring</TT
  185 > - this entry is a string
  186                             containing documentation for the method.  The
  187                             documentation may contain HTML markup.
  188                             </P
  189 ></LI
  190 ></UL
  191 ><P
  192 >Look at the <TT
  193 CLASS="FILENAME"
  194 >server.php</TT
  195 > example in the 
  196                     distribution to see what a dispatch map looks like.</P
  197 ></DIV
  198 ><DIV
  199 CLASS="SECT2"
  200 ><H2
  201 CLASS="SECT2"
  202 ><A
  203 NAME="SIGNATURES"
  204 >Method signatures</A
  205 ></H2
  206 ><P
  207 >A signature is a description of a method's return type and 
  208                     its parameter types.  A method may have more than one
  209                     signature.</P
  210 ><P
  211 >Within a server's dispatch map, each method has an array
  212                     of possible signatures. Each signature is an array of
  213                     types. The first entry is the return type. For instance, the
  214                     method <PRE
  215 CLASS="PROGRAMLISTING"
  216 >string examples.getStateName(int)</PRE
  217 > has the signature 
  218 <PRE
  219 CLASS="PROGRAMLISTING"
  220 >array($xmlrpcString, $xmlrpcInt)</PRE
  221 > and, assuming that it the only possible signature for
  222                     the method, might be used like this in server creation:
  223 <PRE
  224 CLASS="PROGRAMLISTING"
  225 >$findstate_sig=array(array($xmlrpcString, $xmlrpcInt));
  226 
  227 $findstate_doc='When passed an integer between 1 and 51 returns the
  228 name of a US state, where the integer is the index of that state name
  229 in an alphabetic order.';
  230 
  231 $s=new xmlrpc_server( array( "examples.getStateName" =&gt; 
  232                         array("function" =&gt; "findstate",
  233                         "signature" =&gt; $findstate_sig,
  234                         "docstring" =&gt; $findstate_doc)));</PRE
  235 >
  236 
  237                 </P
  238 ><P
  239 >For convenience the strings representing the XML-RPC types 
  240                     have been encoded as global variables:<PRE
  241 CLASS="PROGRAMLISTING"
  242 >$xmlrpcI4="i4";
  243 $xmlrpcInt="int";
  244 $xmlrpcBoolean="boolean";
  245 $xmlrpcDouble="double";
  246 $xmlrpcString="string";
  247 $xmlrpcDateTime="dateTime.iso8601";
  248 $xmlrpcBase64="base64";
  249 $xmlrpcArray="array";
  250 $xmlrpcStruct="struct";</PRE
  251 ></P
  252 ></DIV
  253 ><DIV
  254 CLASS="SECT2"
  255 ><H2
  256 CLASS="SECT2"
  257 ><A
  258 NAME="AEN635"
  259 >Delaying the server response</A
  260 ></H2
  261 ><P
  262 >You may want to construct the server, but for some reason
  263                     not fulfill the request immediately (security verification, for 
  264                 instance). If you pass the constructor a second argument of
  265                     <TT
  266 CLASS="LITERAL"
  267 >0</TT
  268 > this will have the desired effect. You
  269                     can then use the <TT
  270 CLASS="FUNCTION"
  271 >service()</TT
  272 > method of the
  273                     server class to service the request. For example:</P
  274 ><PRE
  275 CLASS="PROGRAMLISTING"
  276 >$s=new xmlrpc_server($myDispMap, 0);
  277 
  278 // ... some code that does other stuff here
  279 
  280 $s-&#62;service();</PRE
  281 ></DIV
  282 ><DIV
  283 CLASS="SECT2"
  284 ><H2
  285 CLASS="SECT2"
  286 ><A
  287 NAME="AEN641"
  288 >Fault reporting</A
  289 ></H2
  290 ><P
  291 >Fault codes for your servers should start at the
  292           value indicated by
  293           the global <TT
  294 CLASS="LITERAL"
  295 >$xmlrpcerruser</TT
  296 > + 1.</P
  297 ><P
  298 >Standard errors returned by the server include:</P
  299 ><P
  300 ></P
  301 ><DIV
  302 CLASS="VARIABLELIST"
  303 ><DL
  304 ><DT
  305 ><TT
  306 CLASS="LITERAL"
  307 >1</TT
  308 > <SPAN
  309 CLASS="PHRASE"
  310 >Unknown method</SPAN
  311 ></DT
  312 ><DD
  313 ><P
  314 >Returned if the server was asked to dispatch a
  315                 method it didn't know about</P
  316 ></DD
  317 ><DT
  318 ><TT
  319 CLASS="LITERAL"
  320 >2</TT
  321 > <SPAN
  322 CLASS="PHRASE"
  323 >Invalid return payload</SPAN
  324 ></DT
  325 ><DD
  326 ><P
  327 >This error is actually generated by the client, not
  328                 server, code, but signifies that a server returned
  329                 something it couldn't understand.</P
  330 ></DD
  331 ><DT
  332 ><TT
  333 CLASS="LITERAL"
  334 >3</TT
  335 > <SPAN
  336 CLASS="PHRASE"
  337 >Incorrect parameters</SPAN
  338 ></DT
  339 ><DD
  340 ><P
  341 >This error is generated when the server has signature(s)
  342                                 defined for a method, and the parameters passed by the
  343                                 client do not match any of signatures.</P
  344 ></DD
  345 ><DT
  346 ><TT
  347 CLASS="LITERAL"
  348 >4</TT
  349 > <SPAN
  350 CLASS="PHRASE"
  351 >Can't introspect: method unknown</SPAN
  352 ></DT
  353 ><DD
  354 ><P
  355 >This error is generated by the builtin
  356                                 <TT
  357 CLASS="FUNCTION"
  358 >system.*</TT
  359 > methods when any kind of
  360                                 introspection is attempted on a method undefined by the
  361                                 server.</P
  362 ></DD
  363 ><DT
  364 ><TT
  365 CLASS="LITERAL"
  366 >5</TT
  367 > <SPAN
  368 CLASS="PHRASE"
  369 >Didn't receive 200 OK from remote server</SPAN
  370 ></DT
  371 ><DD
  372 ><P
  373 >This error is generated by the client when a remote server
  374                                 doesn't return HTTP/1.1 200 OK in response to a
  375                                 request. A more detailed error report is added onto the
  376                                 end of the phrase above.</P
  377 ></DD
  378 ><DT
  379 ><TT
  380 CLASS="LITERAL"
  381 >100-</TT
  382 > <SPAN
  383 CLASS="PHRASE"
  384 >XML parse errors</SPAN
  385 ></DT
  386 ><DD
  387 ><P
  388 >Returns 100 plus the XML parser error code for the
  389                 fault that occurred.  The
  390                 <TT
  391 CLASS="FUNCTION"
  392 >faultString</TT
  393 > returned explains where 
  394               the parse error was in the incoming XML stream.</P
  395 ></DD
  396 ></DL
  397 ></DIV
  398 ></DIV
  399 ></DIV
  400 ><DIV
  401 CLASS="NAVFOOTER"
  402 ><HR
  403 ALIGN="LEFT"
  404 WIDTH="100%"><TABLE
  405 WIDTH="100%"
  406 BORDER="0"
  407 CELLPADDING="0"
  408 CELLSPACING="0"
  409 ><TR
  410 ><TD
  411 WIDTH="33%"
  412 ALIGN="left"
  413 VALIGN="top"
  414 ><A
  415 HREF="xmlrpcval.html"
  416 >Prev</A
  417 ></TD
  418 ><TD
  419 WIDTH="34%"
  420 ALIGN="center"
  421 VALIGN="top"
  422 ><A
  423 HREF="index.html"
  424 >Home</A
  425 ></TD
  426 ><TD
  427 WIDTH="33%"
  428 ALIGN="right"
  429 VALIGN="top"
  430 ><A
  431 HREF="helpers.html"
  432 >Next</A
  433 ></TD
  434 ></TR
  435 ><TR
  436 ><TD
  437 WIDTH="33%"
  438 ALIGN="left"
  439 VALIGN="top"
  440 >xmlrpcval</TD
  441 ><TD
  442 WIDTH="34%"
  443 ALIGN="center"
  444 VALIGN="top"
  445 ><A
  446 HREF="apidocs.html"
  447 >Up</A
  448 ></TD
  449 ><TD
  450 WIDTH="33%"
  451 ALIGN="right"
  452 VALIGN="top"
  453 >Helper functions</TD
  454 ></TR
  455 ></TABLE
  456 ></DIV
  457 ></BODY
  458 ></HTML
  459 >