ch07s05.html.svn-base

来自「PHP 知识管理系统（基于树结构的知识管理系统）, 英文原版的PHP源码。」· SVN-BASE 代码 · 共 115 行 · 第 1/2 页

$echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));

$findstate_doc = 'Echoes back to the client the received value, regardless of its type';

$s = new xmlrpc_server( array(
  "echoBack" => array(
    "function" => "echoback",
    "signature" => $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
    "docstring" => $echoback_doc
  )));

</pre><p>Methods <code class="methodname">system.listMethods</code>, <code class="methodname">system.methodHelp</code>, <code class="methodname">system.methodSignature</code> and <code class="methodname">system.multicall</code> are already defined by the server, and should not be reimplemented (see Reserved Methods below).</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2508"></a>5.4.&nbsp;Delaying the server response</h3></div></div></div><p>You may want to construct the server, but for some reason not fulfill the request immediately (security verification, for instance). If you omit to pass to the constructor the dispatch map or pass it a second argument of <code class="literal">0</code> this will have the desired effect. You can then use the <code class="function">service()</code> method of the server class to service the request. For example:</p><pre class="programlisting">
$s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request

// ... some code that does other stuff here

$s-&gt;service();

</pre><p>Note that the <code class="methodname">service</code> method will print the complete result payload to screen and send appropriate HTTP headers back to the client, but also return the response object. This permits further manipulation of the response.</p><p>To prevent the server from sending HTTP headers back to the client, you can pass a second parameter with a value of <code class="literal">TRUE</code> to the <code class="methodname">service</code> method. In this case, the response payload will be returned instead of the response object.</p><p>Xmlrpc requests retrieved by other means than HTTP POST bodies can also be processed. For example:</p><pre class="programlisting">
$s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request

// ... some code that does other stuff here, including setting dispatch map into server object

$resp = $s-&gt;service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload

// ... some code that does other stuff with xml response $resp here

</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2538"></a>5.5.&nbsp;Modifying the server behaviour</h3></div></div></div><p>A couple of methods / class variables are available to modify the behaviour of the server. The only way to take advantage of their existence is by usage of a delayed server response (see above)</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2543"></a>5.5.1.&nbsp;setDebug()</h4></div></div></div><p>This function controls weather the server is going to echo debugging messages back to the client as comments in response body. Valid values: 0,1,2,3, with 1 being the default. At level 0, no debug info is returned to the client. At level 2, the complete client request is added to the response, as part of the xml comments. At level 3, a new PHP error handler is set when executing user functions exposed as server methods, and all non-fatal errors are trapped and added as comments into the response.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2548"></a>5.5.2.&nbsp;allow_system_funcs</h4></div></div></div><p>Default_value: TRUE. When set to FALSE, disables support for <code class="methodname">System.xxx</code> functions in the server. It might be useful e.g. if you do not wish the server to respond to requests to <code class="methodname">System.ListMethods</code>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2559"></a>5.5.3.&nbsp;compress_response</h4></div></div></div><p>When set to TRUE, enables the server to take advantage of HTTP compression, otherwise disables it. Responses will be transparently compressed, but only when an xmlrpc-client declares its support for compression in the HTTP headers of the request.</p><p>Note that the ZLIB php extension must be installed for this to work. If it is, <code class="varname">compress_response</code> will default to TRUE.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="d0e2569"></a>5.5.4.&nbsp;response_charset_encoding</h4></div></div></div><p>Charset encoding to be used for response (only affects string values).</p><p>If it can, the server will convert the generated response from internal_encoding to the intended one.</p><p>Valid values are: a supported xml encoding (only UTF-8 and ISO-8859-1 at present, unless mbstring is enabled), null (leave charset unspecified in response and convert output stream to US_ASCII), 'default' (use xmlrpc library default as specified in xmlrpc.inc, convert output stream if needed), or 'auto' (use client-specified charset encoding or same as request if request headers do not specify it (unless request is US-ASCII: then use library default anyway).</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2578"></a>5.6.&nbsp;Fault reporting</h3></div></div></div><p>Fault codes for your servers should start at the value indicated by the global <code class="literal">$xmlrpcerruser</code> + 1.</p><p>Standard errors returned by the server include:</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">1</code> <span>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><span class="term"><code class="literal">2</code> <span>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. A more detailed error report is sometimes added onto the end of the phrase above.</p></dd><dt><span class="term"><code class="literal">3</code> <span>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><span class="term"><code class="literal">4</code> <span>Can't introspect: method unknown</span></span></dt><dd><p>This error is generated by the builtin <code class="function">system.*</code> methods when any kind of introspection is attempted on a method undefined by the server.</p></dd><dt><span class="term"><code class="literal">5</code> <span>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><span class="term"><code class="literal">6</code> <span>No data received from server</span></span></dt><dd><p>This error is generated by the client when a remote server returns HTTP/1.1 200 OK in response to a request, but no response body follows the HTTP headers.</p></dd><dt><span class="term"><code class="literal">7</code> <span>No SSL support compiled in</span></span></dt><dd><p>This error is generated by the client when trying to send a request with HTTPS and the CURL extension is not available to PHP.</p></dd><dt><span class="term"><code class="literal">8</code> <span>CURL error</span></span></dt><dd><p>This error is generated by the client when trying to send a request with HTTPS and the HTTPS communication fails.</p></dd><dt><span class="term"><code class="literal">9-14</code> <span>multicall errors</span></span></dt><dd><p>These errors are generated by the server when something fails inside a system.multicall request.</p></dd><dt><span class="term"><code class="literal">100-</code> <span>XML parse errors</span></span></dt><dd><p>Returns 100 plus the XML parser error code for the fault that occurred. The <code class="function">faultString</code> returned explains where the parse error was in the incoming XML stream.</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="d0e2695"></a>5.7.&nbsp;'New style' servers</h3></div></div></div><p>In the same spirit of simplification that inspired the <code class="varname">xmlrpc_client::return_type</code> class variable, a new class variable has been added to the server class: <code class="varname">functions_parameters_type</code>. When set to 'phpvals', the functions registered in the server dispatch map will be called with plain php values as parameters, instead of a single xmlrpcmsg instance parameter. The return value of those functions is expected to be a plain php value, too. An example is worth a thousand words:</p><pre class="programlisting">
  function foo($usr_id, $out_lang='en') {
    global $xmlrpcerruser;

    ...

    if ($someErrorCondition)
      return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
    else
      return array(
        'name' =&gt; 'Joe',
        'age' =&gt; 27,
        'picture' =&gt; new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
      );
  }

  $s = new xmlrpc_server(
    array(
      "examples.myFunc" =&gt; array(
        "function" =&gt; "bar::foobar",
        "signature" =&gt; array(
          array($xmlrpcString, $xmlrpcInt),
          array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
        )
      )
    ), false);
  $s-&gt;functions_parameters_type = 'phpvals';
  $s-&gt;service();

</pre><p>There are a few things to keep in mind when using this simplified syntax:</p><p>to return an xmlrpc error, the method handler function must return an instance of xmlrpcresp. There is no other way for the server to know when an error response should be served to the client;</p><p>to return a base64 value, the method handler function must encode it on its own, creating an instance of an xmlrpcval object;</p><p>the method handler function cannot determine the name of the xmlrpc method it is serving, unlike standard handler functions that can retrieve it from the message object;</p><p>when receiving nested parameters, the method handler function has no way to distinguish a php string that was sent as base64 value from one that was sent as a string value;</p><p>this has a direct consequence on the support of system.multicall: a method whose signature contains datetime or base64 values will not be available to multicall calls;</p><p>last but not least, the direct parsing of xml to php values is much faster than using xmlrpcvals, and allows the library to handle much bigger messages without allocating all available server memory or smashing PHP recursive call stack.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch07s04.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch07.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4.&nbsp;xmlrpcresp&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;8.&nbsp;Global variables</td></tr></table></div></body></html>