Peter M. Groen / knowledgetree

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!--
PHP-XMLRPC User manual
$Id: xmlrpc_php.xml,v 1.24 2007/03/01 21:21:04 ggiunta Exp $
-->
<book>
  <title>XML-RPC for PHP</title>

  <subtitle>version 2.2</subtitle>

  <bookinfo>
    <date>February 25, 2007</date>

    <authorgroup>
      <author>
        <firstname>Edd</firstname>

        <surname>Dumbill</surname>
      </author>

      <author>
        <firstname>Gaetano</firstname>

        <surname>Giunta</surname>
      </author>

      <author>
        <firstname>Miles</firstname>

        <surname>Lott</surname>
      </author>

      <author>
        <firstname>Justin R.</firstname>

        <surname>Miller</surname>
      </author>

      <author>
        <firstname>Andres</firstname>

        <surname>Salomon</surname>
      </author>
    </authorgroup>

    <copyright>
      <year>1999,2000,2001</year>

      <holder>Edd Dumbill, Useful Information Company</holder>
    </copyright>

    <legalnotice>
      <para>All rights reserved.</para>

      <para>Redistribution and use in source and binary forms, with or without
      modification, are permitted provided that the following conditions are
      met:</para>

      <para><itemizedlist>
          <listitem>
            <para>Redistributions of source code must retain the above copyright
            notice, this list of conditions and the following disclaimer.</para>
          </listitem>

          <listitem>
            <para>Redistributions in binary form must reproduce the above
            copyright notice, this list of conditions and the following
            disclaimer in the documentation and/or other materials provided with
            the distribution.</para>
          </listitem>

          <listitem>
            <para>Neither the name of the "XML-RPC for PHP" nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.</para>
          </listitem>
        </itemizedlist></para>

      <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
      "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
      TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
      PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
      LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
      CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
      SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
      INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
      CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
      ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.</para>
    </legalnotice>
  </bookinfo>

  <chapter id="introduction">
    <title>Introduction</title>

    <para>XML-RPC is a format devised by <ulink
    url="http://www.userland.com/">Userland Software</ulink> for achieving
    remote procedure call via XML using HTTP as the transport. XML-RPC has its
    own web site, <ulink
    url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>

    <para>This collection of PHP classes provides a framework for writing
    XML-RPC clients and servers in PHP.</para>

    <para>Main goals of the project are ease of use, flexibility and
    completeness.</para>

    <para>The original author is Edd Dumbill of <ulink
    url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
    1.0 stable release, the project has been opened to wider involvement and
    moved to <ulink
    url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>.</para>

    <para>A list of XML-RPC implementations for other languages such as Perl and
    Python can be found on the <ulink
    url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>

    <sect1>
      <title>Acknowledgements</title>

      <para>Daniel E. Baumann</para>

      <para>James Bercegay</para>

      <para>Leon Blackwell</para>

      <para>Stephane Bortzmeyer</para>

      <para>Daniel Convissor</para>

      <para>Geoffrey T. Dairiki</para>

      <para>Stefan Esser</para>

      <para>James Flemer</para>

      <para>Ernst de Haan</para>

      <para>Tom Knight</para>

      <para>Axel Kollmorgen</para>

      <para>Peter Kocks</para>

      <para>Daniel Krippner</para>

      <para>S. Kuip</para>

      <para>A. Lambert</para>

      <para>Dan Libby</para>

      <para>Arnaud Limbourg</para>

      <para>Ernest MacDougal Campbell III</para>

      <para>Lukasz Mach</para>

      <para>Kjartan Mannes</para>

      <para>Ben Margolin</para>

      <para>Nicolay Mausz</para>

      <para>Justin Miller</para>

      <para>Jan Pfeifer</para>

      <para>Giancarlo Pinerolo</para>

      <para>Peter Russel</para>

      <para>Viliam Simko</para>

      <para>Douglas Squirrel</para>

      <para>Idan Sofer</para>

      <para>Anatoly Techtonik</para>

      <para>Eric van der Vlist</para>

      <para>Christian Wenz</para>

      <para>Jim Winstead</para>

      <para>Przemyslaw Wroblewski</para>
    </sect1>
  </chapter>

  <chapter id="news">
    <title>What's new</title>

    <para><emphasis>Note:</emphasis> not all items the following list have (yet)
    been fully documented, and some might not be present in any other chapter in
    the manual. To find a more detailed description of new functions and methods
    please take a look at the source code of the library, which is quite
    thoroughly commented in javadoc-like form.</para>

    <sect1>
      <title>2.2</title>

      <itemizedlist>
        <listitem>
          <para>fixed: debugger errors on php installs with magic_quotes_gpc
          on</para>
        </listitem>

        <listitem>
          <para>fixed: support for https connections via proxy</para>
        </listitem>

        <listitem>
          <para>fixed: wrap_xmlrpc_method() generated code failed to properly
          encode php objects</para>
        </listitem>

        <listitem>
          <para>improved: slightly faster encoding of data which is internally
          UTF-8</para>
        </listitem>

        <listitem>
          <para>improved: debugger always generates a 'null' id for jsonrpc if
          user omits it</para>
        </listitem>

        <listitem>
          <para>new: debugger can take advantage of a graphical value builder
          (it has to be downloaded separately, as part of jsxmlrpc package. See
          Appendix D for more details)</para>
        </listitem>

        <listitem>
          <para>new: support for the &lt;NIL/&gt; xmlrpc extension. see from
          more details</para>
        </listitem>

        <listitem>
          <para>new: server support for the system.getCapabilities xmlrpc
          extension</para>
        </listitem>

        <listitem>
          <para>new: <function><link
          linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
          accepts two new options: debug and return_on_fault</para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1>
      <title>2.1</title>

      <para><itemizedlist>
          <listitem>
            <para>The <function>wrap_php_function</function> and
            <function>wrap_xmlrpc_method</function> functions have been moved
            out of the base library file <filename>xmlrpc.inc</filename> into a
            file of their own: <filename>xmlrpc_wrappers.inc</filename>. You
            will have to include() / require() it in your scripts if you have
            been using those functions. For increased security, the automatic
            rebuilding of php object instances out of received xmlrpc structs in
            <function>wrap_xmlrpc_method()</function> has been disabled (but it
            can be optionally re-enabled). Both
            <function>wrap_php_function()</function> and
            <function>wrap_xmlrpc_method()</function> functions accept many more
            options to fine tune their behaviour, including one to return the
            php code to be saved and later used as standalone php script</para>
          </listitem>

          <listitem>
            <para>The constructor of xmlrpcval() values has seen some internal
            changes, and it will not throw a php warning anymore when invoked
            using an unknown xmlrpc type: the error will only be written to php
            error log. Also <code>new xmlrpcval('true', 'boolean')</code> is not
            supported anymore</para>
          </listitem>

          <listitem>
            <para>The new function <function>php_xmlrpc_decode_xml()</function>
            will take the xml representation of either an xmlrpc request,
            response or single value and return the corresponding php-xmlrpc
            object instance</para>
          </listitem>

          <listitem>
            <para>A new function <function>wrap_xmlrpc_server()</function>has
            been added, to wrap all (or some) of the methods exposed by a remote
            xmlrpc server into a php class</para>
          </listitem>

          <listitem>
            <para>A new file has been added:
            <filename>verify_compat.php</filename>, to help users diagnose the
            level of compliance of their php installation with the
            library</para>
          </listitem>

          <listitem>
            <para>Restored compatibility with php 4.0.5 (for those poor souls
            still stuck on it)</para>
          </listitem>

          <listitem>
            <para>Method <methodname>xmlrpc_server-&gt;service()</methodname>
            now returns a value: either the response payload or xmlrpcresp
            object instance</para>
          </listitem>

          <listitem>
            <para>Method <methodname>xmlrpc_server-&gt;add_to_map()</methodname>
            now accepts xmlrpc methods with no param definitions</para>
          </listitem>

          <listitem>
            <para>Documentation for single parameters of exposed methods can be
            added to the dispatch map (and turned into html docs in conjunction
            with a future release of the 'extras' package)</para>
          </listitem>

          <listitem>
            <para>Full response payload is saved into xmlrpcresp object for
            further debugging</para>
          </listitem>

          <listitem>
            <para>The debugger can now generate code that wraps a remote method
            into a php function (works for jsonrpc, too); it also has better
            support for being activated via a single GET call (e.g. for
            integration into other tools)</para>
          </listitem>

          <listitem>
            <para>Stricter parsing of incoming xmlrpc messages: two more invalid
            cases are now detected (double <literal>data</literal> element
            inside <literal>array</literal> and
            <literal>struct</literal>/<literal>array</literal> after scalar
            inside <literal>value</literal> element)</para>
          </listitem>

          <listitem>
            <para>More logging of errors in a lot of situations</para>
          </listitem>

          <listitem>
            <para>Javadoc documentation of lib files (almost) complete</para>
          </listitem>

          <listitem>
            <para>Many performance tweaks and code cleanups, plus the usual crop
            of bugs fixed (see NEWS file for complete list of bugs)</para>
          </listitem>

          <listitem>
            <para>Lib internals have been modified to provide better support for
            grafting extra functionality on top of it. Stay tuned for future
            releases of the EXTRAS package (or go read Appendix B)...</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>2.0 final</title>

      <para><itemizedlist>
          <listitem>
            <para>Added to the client class the possibility to use Digest and
            NTLM authentication methods (when using the CURL library) for
            connecting to servers and NTLM for connecting to proxies</para>
          </listitem>

          <listitem>
            <para>Added to the client class the possibility to specify alternate
            certificate files/directories for authenticating the peer with when
            using HTTPS communication</para>
          </listitem>

          <listitem>
            <para>Reviewed all examples and added a new demo file, containing a
            proxy to forward xmlrpc requests to other servers (useful e.g. for
            ajax coding)</para>
          </listitem>

          <listitem>
            <para>The debugger has been upgraded to reflect the new client
            capabilities</para>
          </listitem>

          <listitem>
            <para>All known bugs have been squashed, and the lib is more
            tolerant than ever of commonly-found mistakes</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>2.0 Release candidate 3</title>

      <para><itemizedlist>
          <listitem>
            <para>Added to server class the property
            <property>functions_parameters_type</property>, that allows the
            server to register plain php functions as xmlrpc methods (i.e.
            functions that do not take an xmlrpcmsg object as unique
            param)</para>
          </listitem>

          <listitem>
            <para>let server and client objects serialize calls using a
            specified character set encoding for the produced xml instead of
            US-ASCII (ISO-8859-1 and UTF-8 supported)</para>
          </listitem>

          <listitem>
            <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
            input</para>
          </listitem>

          <listitem>
            <para>'class::method' syntax is now accepted in the server dispatch
            map</para>
          </listitem>

          <listitem>
            <para><function>xmlrpc_clent::SetDebug()</function> accepts integer
            values instead of a boolean value, with debugging level 2 adding to
            the information printed to screen the complete client request</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>2.0 Release candidate 2</title>

      <para><itemizedlist>
          <listitem>
            <para>Added a new property of the client object:
            <code>xmlrpc_client-&gt;return_type</code>, indicating whether calls
            to the send() method will return xmlrpcresp objects whose value() is
            an xmlrpcval object, a php value (automatically decoded) or the raw
            xml received from the server.</para>
          </listitem>

          <listitem>
            <para>Added in the extras dir. two new library file:
            <filename>jsonrpc.inc</filename> and
            <filename>jsonrpcs.inc</filename> containing new classes that
            implement support for the json-rpc protocol (alpha quality
            code)</para>
          </listitem>

          <listitem>
            <para>Added a new client method: <code>setKey($key, $keypass)</code>
            to be used in HTTPS connections</para>
          </listitem>

          <listitem>
            <para>Added a new file containing some benchmarks in the testsuite
            directory</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>2.0 Release candidate 1</title>

      <itemizedlist>
        <listitem>
          <para>Support for HTTP proxies (new method:
          <code>xmlrpc_client::setProxy()</code>)</para>
        </listitem>

        <listitem>
          <para>Support HTTP compression of both requests and responses. Clients
          can specify what kind of compression they accept for responses between
          deflate/gzip/any, and whether to compress the requests. Servers by
          default compress responses to clients that explicitly declare support
          for compression (new methods:
          <code>xmlrpc_client::setAcceptedCompression()</code>,
          <code>xmlrpc_client::setRequestCompression()</code>). Note that the
          ZLIB php extension needs to be enabled in PHP to support
          compression.</para>
        </listitem>

        <listitem>
          <para>Implement HTTP 1.1 connections, but only if CURL is enabled
          (added an extra parameter to <code>xmlrpc_client::xmlrpc_client</code>
          to set the desired HTTP protocol at creation time and a new supported
          value for the last parameter of <code>xmlrpc_client::send</code>,
          which now can be safely omitted if it has been specified at creation
          time)</para>

          <para>With PHP versions greater than 4.3.8 keep-alives are enabled by
          default for HTTP 1.1 connections. This should yield faster execution
          times when making multiple calls in sequence to the same xml-rpc
          server from a single client.</para>
        </listitem>

        <listitem>
          <para>Introduce support for cookies. Cookies to be sent to the server
          with a request can be set using
          <code>xmlrpc_client::setCookie()</code>, while cookies received from
          the server are found in <code>xmlrpcresp::cookies()</code>. It is left
          to the user to check for validity of received cookies and decide
          whether they apply to successive calls or not.</para>
        </listitem>

        <listitem>
          <para>Better support for detecting different character set encodings
          of xml-rpc requests and responses: both client and server objects will
          correctly detect the charset encoding of received xml, and use an
          appropriate xml parser.</para>

          <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
        </listitem>

        <listitem>
          <para>Added one new xmlrpcmsg constructor syntax, allowing usage of a
          single string with the complete URL of the target server</para>
        </listitem>

        <listitem>
          <para>Convert xml-rpc boolean values into native php values instead of
          0 and 1</para>
        </listitem>

        <listitem>
          <para>Force the <code>php_xmlrpc_encode</code> function to properly
          encode numerically indexed php arrays into xml-rpc arrays (numerically
          indexed php arrays always start with a key of 0 and increment keys by
          values of 1)</para>
        </listitem>

        <listitem>
          <para>Prevent the <code>php_xmlrpc_encode</code> function from further
          re-encoding any objects of class <code>xmlrpcval</code> that are
          passed to it. This allows to call the function with arguments
          consisting of mixed php values / xmlrpcval objects.</para>
        </listitem>

        <listitem>
          <para>Allow a server to NOT respond to system.* method calls (setting
          the <code>$server-&gt;allow_system_funcs</code> property).</para>
        </listitem>

        <listitem>
          <para>Implement a new xmlrpcval method to determine if a value of type
          struct has a member of a given name without having to loop trough all
          members: <code>xmlrpcval::structMemExists()</code></para>
        </listitem>

        <listitem>
          <para>Expand methods <code>xmlrpcval::addArray</code>,
          <code>addScalar</code> and <code>addStruct</code> allowing extra php
          values to be added to xmlrpcval objects already formed.</para>
        </listitem>

        <listitem>
          <para>Let the <code>xmlrpc_client::send</code> method accept an XML
          string for sending instead of an xmlrpcmsg object, to facilitate
          debugging and integration with the php native xmlrpc extension</para>
        </listitem>

        <listitem>
          <para>Extend the <code>php_xmlrpc_encode</code> and
          <code>php_xmlrpc_decode</code> functions to allow serialization and
          rebuilding of PHP objects. To successfully rebuild a serialized
          object, the object class must be defined in the deserializing end of
          the transfer. Note that object members of type resource will be
          deserialized as NULL values.</para>

          <para>Note that his has been implemented adding a "php_class"
          attribute to xml representation of xmlrpcval of STRUCT type, which,
          strictly speaking, breaks the xml-rpc spec. Other xmlrpc
          implementations are supposed to ignore such an attribute (unless they
          implement a brain-dead custom xml parser...), so it should be safe
          enabling it in heterogeneous environments. The activation of this
          feature is done by usage of an option passed as second parameter to
          both <code>php_xmlrpc_encode</code> and
          <code>php_xmlrpc_decode</code>.</para>
        </listitem>

        <listitem>
          <para>Extend the <code>php_xmlrpc_encode</code> function to allow
          automatic serialization of is08601-conforming php strings as
          datetime.iso8601 xmlrpcvals, by usage of an optional parameter</para>
        </listitem>

        <listitem>
          <para>Added an automatic stub code generator for converting xmlrpc
          methods to php functions and vice-versa.</para>

          <para>This is done via two new functions:
          <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
          and has many caveats, with php being a typeless language and
          all...</para>

          <para>With PHP versions lesser than 5.0.3 wrapping of php functions
          into xmlrpc methods is not supported yet.</para>
        </listitem>

        <listitem>
          <para>Allow object methods to be used in server dispatch map</para>
        </listitem>

        <listitem>
          <para>Added a complete debugger solution, in the
          <filename>debugger</filename> folder</para>
        </listitem>

        <listitem>
          <para>Added configurable server-side debug messages, controlled by the
          new method <code>xmlrpc_server::SetDebug()</code>. At level 0, no
          debug messages are sent to the client; level 1 is the same as the old
          behaviour; at level 2 a lot more info is echoed back to the client,
          regarding the received call; at level 3 all warnings raised during
          server processing are trapped (this prevents breaking the xml to be
          echoed back to the client) and added to the debug info sent back to
          the client</para>
        </listitem>

        <listitem>
          <para>New XML parsing code, yields smaller memory footprint and faster
          execution times, not to mention complete elimination of the dreaded
          <filename>eval()</filename> construct, so prone to code injection
          exploits</para>
        </listitem>

        <listitem>
          <para>Rewritten most of the error messages, making text more
          explicative</para>
        </listitem>
      </itemizedlist>
    </sect1>
  </chapter>

  <chapter id="requirements">
    <title>System Requirements</title>

    <para>The library has been designed with goals of scalability and backward
    compatibility. As such, it supports a wide range of PHP installs. Note that
    not all features of the lib are available in every configuration.</para>

    <para>The <emphasis>minimum supported</emphasis> PHP version is 4.2.</para>

    <para>A compatibility layer is provided that allows the code to run on PHP
    4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest you
    upgrade as soon as possible.</para>

    <para>Automatic generation of xml-rpc methods from php functions is only
    supported with PHP version 5.0.3 and later (note that the lib will generate
    some warnings with PHP 5 in strict error reporting mode).</para>

    <para>If you wish to use SSL or HTTP 1.1 to communicate with remote servers,
    you need the "curl" extension compiled into your PHP installation. This is
    available in PHP 4.0.2 and greater, although 4.0.6 has a bug preventing SSL
    working, and versions prior to 4.3.8 do not support streamlining multiple
    requests using HTTP Keep-Alive.</para>

    <para>The "xmlrpc" native extension is not required to be compiled into your
    PHP installation, but if it is, there will be no interference with the
    operation of this library.</para>
  </chapter>

  <chapter id="manifest">
    <title>Files in the distribution</title>

    <glosslist>
      <glossentry>
        <glossterm>lib/xmlrpc.inc</glossterm>

        <glossdef>
          <para>the XML-RPC classes. <function>include()</function> this in your
          PHP files to use the classes.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>lib/xmlrpcs.inc</glossterm>

        <glossdef>
          <para>the XML-RPC server class. <function>include()</function> this in
          addition to xmlrpc.inc to get server functionality</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>lib/xmlrpc_wrappers.inc</glossterm>

        <glossdef>
          <para>helper functions to "automagically" convert plain php functions
          to xmlrpc services and vice versa</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>lib/compat/array_key_exists.php, lib/compat/is_a.php,
        lib/compat/is_scalar.php, lib/compat/var_export.php,
        lib/compat/vesrions_compare.php</glossterm>

        <glossdef>
          <para>compatibility functions: these files implement the compatibility
          layer needed to run the library with PHP versions 4.0 and 4.1</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/server/proxy.php</glossterm>

        <glossdef>
          <para>a sample server implementing xmlrpc proxy functionality.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/server/server.php</glossterm>

        <glossdef>
          <para>a sample server hosting various demo functions, as well as a
          full suite of functions used for interoperability testing. It is used
          by testsuite.php (see below) for unit testing the library, and is not
          to be copied literally into your production servers</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/client/client.php, demo/client/agesort.php,
        demo/client/which.php</glossterm>

        <glossdef>
          <para>client code to exercise some of the functions in server.php,
          including the <function>interopEchoTests.whichToolkit</function>
          method.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/client/wrap.php</glossterm>

        <glossdef>
          <para>client code to illustrate 'wrapping' of remote methods into php
          functions.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/client/introspect.php</glossterm>

        <glossdef>
          <para>client code to illustrate usage of introspection capabilities
          offered by server.php.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/client/mail.php</glossterm>

        <glossdef>
          <para>client code to illustrate usage of an xmlrpc-to-email gateway
          using Dave Winer's XML-RPC server at userland.com.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/client/zopetest.php</glossterm>

        <glossdef>
          <para>example client code that queries an xmlrpc server built in
          Zope.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/vardemo.php</glossterm>

        <glossdef>
          <para>examples of how to construct xmlrpcval types</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>

        <glossdef>
          <para>XML-RPC responses captured in a file for testing purposes (you
          can use these to test the
          <function>xmlrpcmsg-&gt;parseResponse()</function> method).</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>demo/server/discuss.php, demo/client/comment.php</glossterm>

        <glossdef>
          <para>Software used in the PHP chapter of <xref linkend="jellyfish" />
          to provide a comment server and allow the attachment of comments to
          stories from Meerkat's data store.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>test/testsuite.php, test/parse_args.php</glossterm>

        <glossdef>
          <para>A unit test suite for this software package. If you do
          development on this software, please consider submitting tests for
          this suite.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>test/benchmark.php</glossterm>

        <glossdef>
          <para>A (very limited) benchmarking suite for this software package.
          If you do development on this software, please consider submitting
          benchmarks for this suite.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>

        <glossdef>
          <para>An (incomplete) version PEAR's unit test framework for PHP. The
          complete package can be found at <ulink
          url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>test/verify_compat.php</glossterm>

        <glossdef>
          <para>Script designed to help the user to verify the level of
          compatibility of the library with the current php install</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>extras/test.pl, extras/test.py</glossterm>

        <glossdef>
          <para>Perl and Python programs to exercise server.php to test that
          some of the methods work.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>extras/workspace.testPhpServer.fttb</glossterm>

        <glossdef>
          <para>Frontier scripts to exercise the demo server. Thanks to Dave
          Winer for permission to include these. See <ulink
          url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's announcement
          of these.</ulink></para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>extras/rsakey.pem</glossterm>

        <glossdef>
          <para>A test certificate key for the SSL support, which can be used to
          generate dummy certificates. It has the passphrase "test."</para>
        </glossdef>
      </glossentry>
    </glosslist>
  </chapter>

  <chapter id="bugs">
    <title>Known bugs and limitations</title>

    <para>This started out as a bare framework. Many "nice" bits haven't been
    put in yet. Specifically, very little type validation or coercion has been
    put in. PHP being a loosely-typed language, this is going to have to be done
    explicitly (in other words: you can call a lot of library functions passing
    them arguments of the wrong type and receive an error message only much
    further down the code, where it will be difficult to understand).</para>

    <para>dateTime.iso8601 is supported opaquely. It can't be done natively as
    the XML-RPC specification explicitly forbids passing of timezone specifiers
    in ISO8601 format dates. You can, however, use the <xref
    linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions to
    do the encoding and decoding for you.</para>

    <para>Very little HTTP response checking is performed (e.g. HTTP redirects
    are not followed and the Content-Length HTTP header, mandated by the xml-rpc
    spec, is not validated); cookie support still involves quite a bit of coding
    on the part of the user.</para>

    <para>If a specific character set encoding other than US-ASCII, ISO-8859-1
    or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
    or response messages then it will be ignored for the moment, and the content
    will be parsed as if it had been encoded using the charset defined by <xref
    linkend="xmlrpc-defencoding" /></para>

    <para>Very large floating point numbers are serialized using exponential
    notation, even though the spec explicitly forbids this behaviour. This will
    not be a problem if this library is used on both ends of the communication,
    but might cause problems with other implementations.</para>

    <para>Support for receiving from servers version 1 cookies (i.e. conforming
    to RFC 2965) is quite incomplete, and might cause unforeseen errors.</para>

    <para>A PHP warning will be generated in many places when using
    <filename>xmlrpc.inc</filename> and <filename>xmlrpcs.inc</filename> with
    PHP 5 in strict error reporting mode. The simplest workaround to this
    problem is to lower the <parameter>error_reporting</parameter> level in
    php.ini.</para>
  </chapter>

  <chapter id="support">
    <title>Support</title>

    <sect1>
      <title>Online Support</title>

      <para>XML-RPC for PHP is offered "as-is" without any warranty or
      commitment to support. However, informal advice and help is available via
      the XML-RPC for PHP website and mailing list and from XML-RPC.com.</para>

      <itemizedlist>
        <listitem>
          <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
          on <ulink
          url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.
          Bugs, feature requests and patches can be posted to the <ulink
          url="http://sourceforge.net/projects/phpxmlrpc">project's
          website</ulink>.</para>
        </listitem>

        <listitem>
          <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
          run by the author. More details <ulink
          url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
          found here</ulink>.</para>
        </listitem>

        <listitem>
          <para>For more general XML-RPC questions, there is a Yahoo! Groups
          <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
          list</ulink>.</para>
        </listitem>

        <listitem>
          <para>The <ulink
          url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
          group is a useful place to get help with using XML-RPC. This group is
          also gatewayed into the Yahoo! Groups mailing list.</para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
      <title>The Jellyfish Book</title>

      <para><graphic align="right" depth="190"
      fileref="http://www.oreilly.com/catalog/covers/progxmlrpc.s.gif"
      format="GIF" width="145" />Together with Simon St.Laurent and Joe
      Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and Associates
      on XML-RPC. It features a rather fetching jellyfish on the cover.</para>

      <para>Complete details of the book are <ulink
      url="http://www.oreilly.com/catalog/progxmlrpc/">available from O'Reilly's
      web site.</ulink></para>

      <para>Edd is responsible for the chapter on PHP, which includes a worked
      example of creating a forum server, and hooking it up the O'Reilly's
      <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
      order to allow commenting on news stories from around the Web.</para>

      <para>If you've benefited from the effort that has been put into writing
      this software, then please consider buying the book!</para>
    </sect1>
  </chapter>

  <chapter id="apidocs">
    <title>Class documentation</title>

    <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
      <title>xmlrpcval</title>

      <para>This is where a lot of the hard work gets done. This class enables
      the creation and encapsulation of values for XML-RPC.</para>

      <para>Ensure you've read the XML-RPC spec at <ulink
      url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
      before reading on as it will make things clearer.</para>

      <para>The <classname>xmlrpcval</classname> class can store arbitrarily
      complicated values using the following types: <literal>i4 int boolean
      string double dateTime.iso8601 base64 array struct</literal>. You should
      refer to the <ulink url="http://www.xmlrpc.com/spec">spec</ulink> for more
      information on what each of these types mean.</para>

      <sect2>
        <title>Notes on types</title>

        <sect3>
          <title>int</title>

          <para>The type <classname>i4</classname> is accepted as a synonym for
          <classname>int</classname> when creating xmlrpcval objects. The xml
          parsing code will always convert <classname>i4</classname> to
          <classname>int</classname>: <classname>int</classname> is regarded by
          this implementation as the canonical name for this type.</para>
        </sect3>

        <sect3>
          <title>base64</title>

          <para>Base 64 encoding is performed transparently to the caller when
          using this type. Decoding is also transparent. Therefore you ought to
          consider it as a "binary" data type, for use when you want to pass
          data that is not 7-bit clean.</para>
        </sect3>

        <sect3>
          <title>boolean</title>

          <para>The php values <literal>true</literal> and <literal>1</literal>
          map to <literal>true</literal>. All other values (including the empty
          string) are converted to <literal>false</literal>.</para>
        </sect3>

        <sect3>
          <title>string</title>

          <para>Characters &lt;, &gt;, ', ", &amp;, are encoded using their
          entity reference as &amp;lt; &amp;gt; &amp;apos; &amp;quot; and
          &amp;amp; All other characters outside of the ASCII range are encoded
          using their character reference representation (e.g. &amp;#200 for é).
          The XML-RPC spec recommends only encoding <literal>&lt;
          &amp;</literal> but this implementation goes further, for reasons
          explained by <ulink url="http://www.w3.org/TR/REC-xml#syntax">the XML
          1.0 recommendation</ulink>. In particular, using character reference
          representation has the advantage of producing XML that is valid
          independently of the charset encoding assumed.</para>
        </sect3>
      </sect2>

      <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
        <title>Creation</title>

        <para>The constructor is the normal way to create an
        <classname>xmlrpcval</classname>. The constructor can take these
        forms:</para>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$myVal = new <function>xmlrpcval</function></funcdef>

            <void />
          </funcprototype>

          <funcprototype>
            <funcdef>$myVal = new <function>xmlrpcval</function></funcdef>

            <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$myVal = new <function>xmlrpcval</function></funcdef>

            <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>

            <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$myVal = new <function>xmlrpcval</function></funcdef>

            <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>

            <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>The first constructor creates an empty value, which must be
        altered using the methods <function>addScalar</function>,
        <function>addArray</function> or <function>addStruct</function> before
        it can be used.</para>

        <para>The second constructor creates a simple string value.</para>

        <para>The third constructor is used to create a scalar value. The second
        parameter must be a name of an XML-RPC type. Valid types are:
        "<literal>int</literal>", "<literal>boolean</literal>",
        "<literal>string</literal>", "<literal>double</literal>",
        "<literal>dateTime.iso8601</literal>",
        "<literal>base64</literal>".</para>

        <para>Examples:</para>

        <programlisting>
$myInt = new xmlrpcvalue(1267, "int");
$myString = new xmlrpcvalue("Hello, World!", "string");
$myBool = new xmlrpcvalue(1, "boolean");
$myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string

</programlisting>

        <para>The fourth constructor form can be used to compose complex XML-RPC
        values. The first argument is either a simple array in the case of an
        XML-RPC <classname>array</classname> or an associative array in the case
        of a <classname>struct</classname>. The elements of the array
        <emphasis>must be <classname>xmlrpcval</classname> objects
        themselves</emphasis>.</para>

        <para>The second parameter must be either "<literal>array</literal>" or
        "<literal>struct</literal>".</para>

        <para>Examples:</para>

        <programlisting>
$myArray = new xmlrpcval(
  array(
    new xmlrpcval("Tom"),
    new xmlrpcval("Dick"),
    new xmlrpcval("Harry")
  ),
  "array");

// recursive struct
$myStruct = new xmlrpcval(
  array(
    "name" =&gt; new xmlrpcval("Tom", "string"),
    "age" =&gt; new xmlrpcval(34, "int"),
    "address" =&gt; new xmlrpcval(
      array(
        "street" =&gt; new xmlrpcval("Fifht Ave", "string"),
        "city" =&gt; new xmlrpcval("NY", "string")
      ), 
      "struct")
  ), 
  "struct");

</programlisting>

        <para>See the file <literal>vardemo.php</literal> in this distribution
        for more examples.</para>
      </sect2>

      <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
        <title>Methods</title>

        <sect3>
          <title>addScalar</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$ok = $val-&gt;<function>addScalar</function></funcdef>

              <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
            </funcprototype>

            <funcprototype>
              <funcdef>$ok = $val-&gt;<function>addScalar</function></funcdef>

              <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>

              <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>If <parameter>$val</parameter> is an empty
          <classname>xmlrpcval</classname> this method makes it a scalar value,
          and sets that value.</para>

          <para>If <parameter>$val</parameter> is already a scalar value, then
          no more scalars can be added and <literal>0</literal> is
          returned.</para>

          <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
          the php value <parameter>$scalarval</parameter> is added as its last
          element.</para>

          <para>If all went OK, <literal>1</literal> is returned, otherwise
          <literal>0</literal>.</para>
        </sect3>

        <sect3>
          <title>addArray</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$ok = $val-&gt;<function>addArray</function></funcdef>

              <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>The argument is a simple (numerically indexed) array. The
          elements of the array <emphasis>must be
          <classname>xmlrpcval</classname> objects themselves</emphasis>.</para>

          <para>Turns an empty <classname>xmlrpcval</classname> into an
          <classname>array</classname> with contents as specified by
          <parameter>$arrayVal</parameter>.</para>

          <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
          the elements of <parameter>$arrayVal</parameter> are appended to the
          existing ones.</para>

          <para>See the fourth constructor form for more information.</para>

          <para>If all went OK, <literal>1</literal> is returned, otherwise
          <literal>0</literal>.</para>
        </sect3>

        <sect3>
          <title>addStruct</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$ok = $val-&gt;<function>addStruct</function></funcdef>

              <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>The argument is an associative array. The elements of the array
          <emphasis>must be <classname>xmlrpcval</classname> objects
          themselves</emphasis>.</para>

          <para>Turns an empty <classname>xmlrpcval</classname> into a
          <classname>struct</classname> with contents as specified by
          <parameter>$assocArrayVal</parameter>.</para>

          <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
          the elements of <parameter>$arrayVal</parameter> are merged with the
          existing ones.</para>

          <para>See the fourth constructor form for more information.</para>

          <para>If all went OK, <literal>1</literal> is returned, otherwise
          <literal>0</literal>.</para>
        </sect3>

        <sect3>
          <title>kindOf</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$kind = $val-&gt;<function>kindOf</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns a string containing "struct", "array" or "scalar"
          describing the base type of the value. If it returns "undef" it means
          that the value hasn't been initialised.</para>
        </sect3>

        <sect3>
          <title>serialize</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$outString =
              $val-&gt;<function>serialize</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns a string containing the XML-RPC representation of this
          value.</para>
        </sect3>

        <sect3>
          <title>scalarVal</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$scalarVal =
              $val-&gt;<function>scalarVal</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
          method returns the actual PHP-language value of the scalar (base 64
          decoding is automatically handled here).</para>
        </sect3>

        <sect3>
          <title>scalarTyp</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$typeName =
              $val-&gt;<function>scalarTyp</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
          method returns a string denoting the type of the scalar. As mentioned
          before, <literal>i4</literal> is always coerced to
          <literal>int</literal>.</para>
        </sect3>

        <sect3>
          <title>arrayMem</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$xmlrpcVal =
              $val-&gt;<function>arrayMem</function></funcdef>

              <paramdef><type>int</type><parameter>$n</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>If <function>$val-&gt;kindOf() == "array"</function>, returns
          the <parameter>$n</parameter>th element in the array represented by
          the value <parameter>$val</parameter>. The value returned is an
          <classname>xmlrpcval</classname> object.</para>

          <para><programlisting>
// iterating over values of an array object
for ($i = 0; $i &lt; $val-&gt;arraySize(); $i++)
{
  $v = $val-&gt;arrayMem($i);
  echo "Element $i of the array is of type ".$v-&gt;kindOf();
}

</programlisting></para>
        </sect3>

        <sect3>
          <title>arraySize</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$len = $val-&gt;<function>arraySize</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>If <parameter>$val</parameter> is an
          <classname>array</classname>, returns the number of elements in that
          array.</para>
        </sect3>

        <sect3>
          <title>structMem</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$xmlrpcVal =
              $val-&gt;<function>structMem</function></funcdef>

              <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>If <function>$val-&gt;kindOf() == "struct"</function>, returns
          the element called <parameter>$memberName</parameter> from the struct
          represented by the value <parameter>$val</parameter>. The value
          returned is an <classname>xmlrpcval</classname> object.</para>
        </sect3>

        <sect3>
          <title>structEach</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>list($key, $value) =
              $val-&gt;<function>structEach</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns the next (key, value) pair from the struct, when
          <parameter>$val</parameter> is a struct. <parameter>$value</parameter>
          is an xmlrpcval itself. See also <xref
          linkend="structreset" />.</para>

          <para><programlisting>
// iterating over all values of a struct object
$val-&gt;structreset();
while (list($key, $v) = $val-&gt;structEach())
{
  echo "Element $key of the struct is of type ".$v-&gt;kindOf();
}

</programlisting></para>
        </sect3>

        <sect3 id="structreset" xreflabel="structreset()">
          <title>structReset</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$val-&gt;<function>structReset</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Resets the internal pointer for
          <function>structEach()</function> to the beginning of the struct,
          where <parameter>$val</parameter> is a struct.</para>
        </sect3>

        <sect3 id="structmemexists" xreflabel="structmemexists()">
          <title>structMemExists</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$exists =
              $val-&gt;<function>structMemExsists</function></funcdef>

              <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Returns <constant>TRUE</constant> or <constant>FALSE</constant>
          depending on whether a member of the given name exists in the
          struct.</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
      <title>xmlrpcmsg</title>

      <para>This class provides a representation for a request to an XML-RPC
      server. A client sends an <classname>xmlrpcmsg</classname> to a server,
      and receives back an <classname>xmlrpcresp</classname> (see <xref
      linkend="xmlrpc-client-send" />).</para>

      <sect2>
        <title>Creation</title>

        <para>The constructor takes the following forms:</para>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$msg = new <function>xmlrpcmsg</function></funcdef>

            <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>

            <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Where <parameter>methodName</parameter> is a string indicating the
        name of the method you wish to invoke, and
        <parameter>parameterArray</parameter> is a simple php
        <classname>Array</classname> of <classname>xmlrpcval</classname>
        objects. Here's an example message to the <emphasis>US state
        name</emphasis> server:</para>

        <programlisting>
$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));

</programlisting>

        <para>This example requests the name of state number 23. For more
        information on <classname>xmlrpcval</classname> objects, see <xref
        linkend="xmlrpcval" />.</para>

        <para>Note that the <parameter>parameterArray</parameter> parameter is
        optional and can be omitted for methods that take no input parameters or
        if you plan to add parameters one by one.</para>
      </sect2>

      <sect2>
        <title>Methods</title>

        <sect3>
          <title>addParam</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$ok = $msg-&gt;<function>addParam</function></funcdef>

              <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Adds the <classname>xmlrpcval</classname>
          <parameter>xmlrpcVal</parameter> to the parameter list for this method
          call. Returns TRUE or FALSE on error.</para>
        </sect3>

        <sect3>
          <title>getNumParams</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$n = $msg-&gt;<function>getNumParams</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns the number of parameters attached to this
          message.</para>
        </sect3>

        <sect3>
          <title>getParam</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$xmlrpcVal =
              $msg-&gt;<function>getParam</function></funcdef>

              <paramdef><type>int</type><parameter>$n</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Gets the <parameter>n</parameter>th parameter in the message
          (with the index zero-based). Use this method in server implementations
          to retrieve the values sent by the client.</para>
        </sect3>

        <sect3>
          <title>method</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$methName =
              $msg-&gt;<function>method</function></funcdef>

              <void />
            </funcprototype>

            <funcprototype>
              <funcdef>$msg-&gt;method</funcdef>

              <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Gets or sets the method contained in the XML-RPC message.</para>
        </sect3>

        <sect3>
          <title>parseResponse</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$response =
              $msg-&gt;<function>parseResponse</function></funcdef>

              <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Given an incoming XML-RPC server response contained in the
          string <parameter>$xmlString</parameter>, this method constructs an
          <classname>xmlrpcresp</classname> response object and returns it,
          setting error codes as appropriate (see <xref
          linkend="xmlrpc-client-send" />).</para>

          <para>This method processes any HTTP/MIME headers it finds.</para>
        </sect3>

        <sect3>
          <title>parseResponseFile</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$response =
              $msg-&gt;<function>parseResponseFile</function></funcdef>

              <paramdef><type>file handle
              resource</type><parameter>$fileHandle</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Given an incoming XML-RPC server response on the open file
          handle <parameter>fileHandle</parameter>, this method reads all the
          data it finds and passes it to
          <function>parseResponse.</function></para>

          <para>This method is useful to construct responses from pre-prepared
          files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal> in
          this distribution). It processes any HTTP headers it finds, and does
          not close the file handle.</para>
        </sect3>

        <sect3>
          <title>serialize</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$outString =
              $msg-&gt;<function>serialize</function></funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns the an XML string representing the XML-RPC
          message.</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
      <title>xmlrpc_client</title>

      <para>This is the basic class used to represent a client of an XML-RPC
      server.</para>

      <sect2>
        <title>Creation</title>

        <para>The constructor accepts one of two possible syntaxes:</para>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$client = new <function>xmlrpc_client</function></funcdef>

            <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$client = new <function>xmlrpc_client</function></funcdef>

            <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>

            <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>

            <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>

            <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Here are a couple of usage examples of the first form:</para>

        <programlisting>
$client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php);
$another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/xmlrpcserver?agent=007");

</programlisting>

        <para>The second syntax does not allow to express a username and
        password to be used for basic HTTP authorization as in the second
        example above, but instead it allows to choose whether xmlrpc calls will
        be made using the HTTP 1.0 or 1.1 protocol.</para>

        <para>Here's another example client set up to query Userland's XML-RPC
        server at <emphasis>betty.userland.com</emphasis>:</para>

        <programlisting>
$client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);

</programlisting>

        <para>The <parameter>server_port</parameter> parameter is optional, and
        if omitted will default to 80 when using HTTP and 443 when using HTTPS
        (see the <xref linkend="xmlrpc-client-send" /> method below).</para>

        <para>The <parameter>transport</parameter> parameter is optional, and if
        omitted will default to 'http'. Allowed values are either
        '<symbol>http'</symbol>, '<symbol>https</symbol>' or
        '<symbol>http11'</symbol>. Its value can be overridden with every call
        to the <methodname>send</methodname> method. See the
        <methodname>send</methodname> method below for more details about the
        meaning of the different values.</para>
      </sect2>

      <sect2>
        <title>Methods</title>

        <para>This class supports the following methods.</para>

        <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client-&gt;send">
          <title>send</title>

          <para>This method takes the forms:</para>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$response =
              $client-&gt;<function>send</function></funcdef>

              <paramdef><type>xmlrpc_msg</type><parameter>$xmlrpc_message</parameter></paramdef>

              <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>

              <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
            </funcprototype>

            <funcprototype>
              <funcdef>$responses =
              $client-&gt;<function>send</function></funcdef>

              <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>

              <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>

              <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
            </funcprototype>

            <funcprototype>
              <funcdef>$response =
              $client-&gt;<function>send</function></funcdef>

              <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>

              <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>

              <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>Where <parameter>xmlrpc_message</parameter> is an instance of
          <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
          and <parameter>response</parameter> is an instance of
          <classname>xmlrpcresp</classname> (see <xref
          linkend="xmlrpcresp" />).</para>

          <para><parameter>If xmlrpc_messages</parameter> is an array of message
          instances, <code>responses</code> will be an array of response
          instances. The client will try to make use of a single
          <code>system.multicall</code> xml-rpc method call to forward to the
          server all the messages in a single HTTP round trip, unless
          <code>$client-&gt;no_multicall</code> has been previously set to
          <code>TRUE</code> (see the multicall method below), in which case many
          consecutive xmlrpc requests will be sent.</para>

          <para>The third syntax allows to build by hand (or any other means) a
          complete xmlrpc request message, and send it to the server.
          <parameter>xml_payload</parameter> should be a string containing the
          complete xml representation of the request. It is e.g. useful when,
          for maximal speed of execution, the request is serialized into a
          string using the native php xmlrpc functions (see <ulink
          url="http://www.php.net/xmlrpc">the php manual on
          xmlrpc</ulink>).</para>

          <para>The <parameter>timeout</parameter> is optional, and will be set
          to <literal>0</literal> (wait for platform-specific predefined
          timeout) if omitted. This timeout value is passed to
          <function>fsockopen()</function>. It is also used for detecting server
          timeouts during communication (i.e. if the server does not send
          anything to the client for <parameter>timeout</parameter> seconds, the
          connection will be closed).</para>

          <para>The <parameter>transport</parameter> parameter is optional, and
          if omitted will default to the transport set using instance creator or
          'http' if omitted. The only other valid values are 'https', which will
          use an SSL HTTP connection to connect to the remote server, and
          'http11'. Note that your PHP must have the "curl" extension compiled
          in order to use both these features. Note that when using SSL you
          should normally set your port number to 443, unless the SSL server you
          are contacting runs at any other port.</para>

          <warning>
            <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
          </warning>

          <para>In addition to low-level errors, the XML-RPC server you were
          querying may return an error in the <classname>xmlrpcresp</classname>
          object. See <xref linkend="xmlrpcresp" /> for details of how to handle
          these errors.</para>
        </sect3>

        <sect3 id="multicall" xreflabel="xmlrpc_client-&gt;multicall">
          <title>multicall</title>

          <para>This method takes the form:</para>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$responses = $client-&gt;multicall</funcdef>

              <paramdef><type>array</type><parameter>$messages</parameter></paramdef>

              <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>

              <paramdef><type>string</type><parameter>$transport</parameter></paramdef>

              <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method is used to boxcar many method calls in a single
          xml-rpc request. It will try first to make use of the
          <code>system.multicall</code> xml-rpc method call, and fall back to
          executing many separate requests if the server returns any
          error.</para>

          <para><parameter>msgs</parameter> is an array of
          <classname>xmlrpcmsg</classname> objects (see <xref
          linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
          array of <classname>xmlrpcresp</classname> objects (see <xref
          linkend="xmlrpcresp" />).</para>

          <para>The <parameter>timeout</parameter> and
          <parameter>transport</parameter> parameters are optional, and behave
          as in the <methodname>send</methodname> method above.</para>

          <para>The <parameter>fallback</parameter> parameter is optional, and
          defaults to <constant>TRUE</constant>. When set to
          <constant>FALSE</constant> it will prevent the client to try using
          many single method calls in case of failure of the first multicall
          request. It should be set only when the server is known to support the
          multicall extension.</para>
        </sect3>

        <sect3>
          <title>setAcceptedCompression</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setAcceptedCompression</funcdef>

              <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method defines whether the client will accept compressed
          xml payload forming the bodies of the xmlrpc responses received from
          servers. Note that enabling reception of compressed responses merely
          adds some standard http headers to xmlrpc requests. It is up to the
          xmlrpc server to return compressed responses when receiving such
          requests. Allowed values for <parameter>compressionmethod</parameter>
          are: 'gzip', 'deflate', 'any' or null (with any meaning either gzip or
          deflate).</para>

          <para>This requires the "zlib" extension to be enabled in your php
          install. If it is, by default <classname>xmlrpc_client</classname>
          instances will enable reception of compressed content.</para>
        </sect3>

        <sect3>
          <title>setCaCertificate</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setCaCertificate</funcdef>

              <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>

              <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method sets an optional certificate to be used in
          SSL-enabled communication to validate a remote server with (when the
          <parameter>server_method</parameter> is set to 'https' in the client's
          construction or in the send method and
          <methodname>SetSSLVerifypeer</methodname> has been set to
          <constant>TRUE</constant>).</para>

          <para>The <parameter>certificate</parameter> parameter must be the
          filename of a PEM formatted certificate, or a directory containing
          multiple certificate files. The <parameter>is_dir</parameter>
          parameter defaults to <constant>FALSE</constant>, set it to
          <constant>TRUE</constant> to specify that
          <parameter>certificate</parameter> indicates a directory instead of a
          single file.</para>

          <para>This requires the "curl" extension to be compiled into your
          installation of PHP. For more details see the man page for the
          <function>curl_setopt</function> function.</para>
        </sect3>

        <sect3>
          <title>setCertificate</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setCertificate</funcdef>

              <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>

              <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method sets the optional certificate and passphrase used in
          SSL-enabled communication with a remote server (when the
          <parameter>server_method</parameter> is set to 'https' in the client's
          construction or in the send method).</para>

          <para>The <parameter>certificate</parameter> parameter must be the
          filename of a PEM formatted certificate. The
          <parameter>passphrase</parameter> parameter must contain the password
          required to use the certificate.</para>

          <para>This requires the "curl" extension to be compiled into your
          installation of PHP. For more details see the man page for the
          <function>curl_setopt</function> function.</para>

          <para>Note: to retrieve information about the client certificate on
          the server side, you will need to look into the environment variables
          which are set up by the webserver. Different webservers will typically
          set up different variables.</para>
        </sect3>

        <sect3>
          <title>setCookie</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setCookie</funcdef>

              <paramdef><type>string</type><parameter>$name</parameter></paramdef>

              <paramdef><type>string</type><parameter>$value</parameter></paramdef>

              <paramdef><type>string</type><parameter>$path</parameter></paramdef>

              <paramdef><type>string</type><parameter>$domain</parameter></paramdef>

              <paramdef><type>int</type><parameter>$port</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method sets a cookie that will be sent to the xmlrpc server
          along with every further request (useful e.g. for keeping session info
          outside of the xml-rpc payload).</para>

          <para><parameter>$value</parameter> is optional, and defaults to
          null.</para>

          <para><parameter>$path, $domain and $port</parameter> are optional,
          and will be omitted from the cookie header if unspecified. Note that
          setting any of these values will turn the cookie into a 'version 1'
          cookie, that might not be fully supported by the server (see RFC2965
          for more details).</para>
        </sect3>

        <sect3>
          <title>setCredentials</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setCredentials</funcdef>

              <paramdef><type>string</type><parameter>$username</parameter></paramdef>

              <paramdef><type>string</type><parameter>$password</parameter></paramdef>

              <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method sets the username and password for authorizing the
          client to a server. With the default (HTTP) transport, this
          information is used for HTTP Basic authorization. Note that username
          and password can also be set using the class constructor. With HTTP
          1.1 and HTTPS transport, NTLM and Digest authentication protocols are
          also supported. To enable them use the constants
          <constant>CURLAUTH_DIGEST</constant> and
          <constant>CURLAUTH_NTLM</constant> as values for the authtype
          parameter.</para>
        </sect3>

        <sect3>
          <title>setDebug</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setDebug</funcdef>

              <paramdef><parameter><type>int</type>$debugLvl</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para><parameter>debugLvl</parameter> is either <literal>0,
          1</literal> or 2 depending on whether you require the client to print
          debugging information to the browser. The default is not to output
          this information (0).</para>

          <para>The debugging information at level 1includes the raw data
          returned from the XML-RPC server it was querying (including bot HTTP
          headers and the full XML payload), and the PHP value the client
          attempts to create to represent the value returned by the server. At
          level2, the complete payload of the xmlrpc request is also printed,
          before being sent t the server.</para>

          <para>This option can be very useful when debugging servers as it
          allows you to see exactly what the client sends and the server
          returns.</para>
        </sect3>

        <sect3>
          <title>setKey</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setKey</funcdef>

              <paramdef><type>int</type><parameter>$key</parameter></paramdef>

              <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method sets the optional certificate key and passphrase
          used in SSL-enabled communication with a remote server (when the
          <parameter>transport</parameter> is set to 'https' in the client's
          construction or in the send method).</para>

          <para>This requires the "curl" extension to be compiled into your
          installation of PHP. For more details see the man page for the
          <function>curl_setopt</function> function.</para>
        </sect3>

        <sect3>
          <title>setProxy</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setProxy</funcdef>

              <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>

              <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>

              <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>

              <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>

              <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method enables calling servers via an HTTP proxy. The
          <parameter>proxyusername</parameter>,<parameter>
          proxypassword</parameter> and <parameter>authtype</parameter>
          parameters are optional. <parameter>Authtype</parameter> defaults to
          <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
          the only other valid value is the constant
          <constant>CURLAUTH_NTLM</constant>, and has effect only when the
          client uses the HTTP 1.1 protocol.</para>

          <para>NB: CURL versions before 7.11.10 cannot use a proxy to
          communicate with https servers.</para>
        </sect3>

        <sect3>
          <title>setRequestCompression</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setRequestCompression</funcdef>

              <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method defines whether the xml payload forming the request
          body will be sent to the server in compressed format, as per the HTTP
          specification. This is particularly useful for large request
          parameters and over slow network connections. Allowed values for
          <parameter>compressionmethod</parameter> are: 'gzip', 'deflate', 'any'
          or null (with any meaning either gzip or deflate). Note that there is
          no automatic fallback mechanism in place for errors due to servers not
          supporting receiving compressed request bodies, so make sure that the
          particular server you are querying does accept compressed requests
          before turning it on.</para>

          <para>This requires the "zlib" extension to be enabled in your php
          install.</para>
        </sect3>

        <sect3>
          <title>setSSLVerifyHost</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setSSLVerifyHost</funcdef>

              <paramdef><type>int</type><parameter>$i</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method defines whether connections made to XML-RPC backends
          via HTTPS should verify the remote host's SSL certificate's common
          name (CN). By default, only the existence of a CN is checked.
          <parameter><parameter>$i</parameter></parameter> should be an integer
          value; 0 to not check the CN at all, 1 to merely check for its
          existence, and 2 to check that the CN on the certificate matches the
          hostname that is being connected to.</para>
        </sect3>

        <sect3>
          <title>setSSLVerifyPeer</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$client-&gt;setSSLVerifyPeer</funcdef>

              <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
            </funcprototype>
          </funcsynopsis>

          <para>This method defines whether connections made to XML-RPC backends
          via HTTPS should verify the remote host's SSL certificate, and cause
          the connection to fail if the cert verification fails.
          <parameter><parameter>$i</parameter></parameter> should be a boolean
          value. Default value: <constant>TRUE</constant>. To specify custom SSL
          certificates to validate the server with, use the
          <methodname>setCaCertificate</methodname> method.</para>
        </sect3>
      </sect2>

      <sect2>
        <title>Variables</title>

        <para>NB: direct manipulation of these variables is only recommended for
        advanced users.</para>

        <sect3>
          <title>no_multicall</title>

          <para>This member variable determines whether the multicall() method
          will try to take advantage of the system.multicall xmlrpc method to
          dispatch to the server an array of requests in a single http roundtrip
          or simply execute many consecutive http calls. Defaults to FALSE, but
          it will be enabled automatically on the first failure of execution of
          system.multicall.</para>
        </sect3>

        <sect3>
          <title>request_charset_encoding</title>

          <para>This is the charset encoding that will be used for serializing
          request sent by the client.</para>

          <para>If defaults to NULL, which means using US-ASCII and encoding all
          characters outside of the ASCII range using their xml character entity
          representation (this has the benefit that line end characters will not
          be mangled in the transfer, a CR-LF will be preserved as well as a
          singe LF).</para>

          <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
        </sect3>

        <sect3 id="return-type" xreflabel="return_type">
          <title>return_type</title>

          <para>This member variable determines whether the value returned
          inside an xmlrpcresp object as results of calls to the send() and
          multicall() methods will be an xmlrpcval object, a plain php value or
          a raw xml string. Allowed values are 'xmlrpcvals' (the default),
          'phpvals' and 'xml'. To allow the user to differentiate between a
          correct and a faulty response, fault responses will be returned as
          xmlrpcresp objects in any case. Note that the 'phpvals' setting will
          yield faster execution times, but some of the information from the
          original response will be lost. It will be e.g. impossible to tell
          whether a particular php string value was sent by the server as an
          xmlrpc string or base64 value.</para>

          <para>Example usage:</para>

          <programlisting>
$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");
$client-&gt;return_type = 'phpvals';
$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
$resp = $client-&gt;send($message);
if ($resp-&gt;faultCode()) echo 'KO. Error: '.$resp-&gt;faultString(); else echo 'OK: got '.$resp-&gt;value();

</programlisting>

          <para>For more details about usage of the 'xml' value, see Appendix
          A.</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
      <title>xmlrpcresp</title>

      <para>This class is used to contain responses to XML-RPC requests. A
      server method handler will construct an <classname>xmlrpcresp</classname>
      and pass it as a return value. This same value will be returned by the
      result of an invocation of the <function>send</function> method of the
      <classname>xmlrpc_client</classname> class.</para>

      <sect2>
        <title>Creation</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$resp = new xmlrpcresp</funcdef>

            <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$resp = new xmlrpcresp</funcdef>

            <paramdef><parameter>0</parameter></paramdef>

            <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>

            <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>The first syntax is used when execution has happened without
        difficulty: <parameter>$xmlrpcval</parameter> is an
        <classname>xmlrpcval</classname> value with the result of the method
        execution contained in it. Alternatively it can be a string containing
        the xml serialization of the single xml-rpc value result of method
        execution.</para>

        <para>The second type of constructor is used in case of failure.
        <parameter>errcode</parameter> and <parameter>err_string</parameter> are
        used to provide indication of what has gone wrong. See <xref
        linkend="xmlrpc-server" /> for more information on passing error
        codes.</para>
      </sect2>

      <sect2>
        <title>Methods</title>

        <sect3>
          <title>faultCode</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$fn = $resp-&gt;faultCode</funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns the integer fault code return from the XML-RPC response.
          A zero value indicates success, any other value indicates a failure
          response.</para>
        </sect3>

        <sect3>
          <title>faultString</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$fs = $resp-&gt;faultString</funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns the human readable explanation of the fault indicated by
          <function>$resp-&gt;faultCode</function>().</para>
        </sect3>

        <sect3>
          <title>value</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$xmlrpcVal = $resp-&gt;value</funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns an <classname>xmlrpcval</classname> object containing
          the return value sent by the server. If the response's
          <function>faultCode</function> is non-zero then the value returned by
          this method should not be used (it may not even be an object).</para>

          <para>Note: if the xmlrpcresp instance in question has been created by
          an <classname>xmlrpc_client</classname> object whose
          <varname>return_type</varname> was set to 'phpvals', then a plain php
          value will be returned instead of an <classname>xmlrpcval</classname>
          object. If the <varname>return_type</varname> was set to 'xml', an xml
          string will be returned (see the return_type var above for more
          details).</para>
        </sect3>

        <sect3>
          <title>serialize</title>

          <funcsynopsis>
            <funcprototype>
              <funcdef>$outString = $resp-&gt;serialize</funcdef>

              <void />
            </funcprototype>
          </funcsynopsis>

          <para>Returns an XML string representation of the response (xml
          prologue not included).</para>
        </sect3>
      </sect2>
    </sect1>

    <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
      <title>xmlrpc_server</title>

      <para>The implementation of this class has been kept as simple to use as
      possible. The constructor for the server basically does all the work.
      Here's a minimal example:</para>

      <programlisting>
  function foo ($xmlrpcmsg) {
    ...
    return new xmlrpcresp($some_xmlrpc_val);
  }

  class bar {
    function foobar($xmlrpcmsg) {
      ...
      return new xmlrpcresp($some_xmlrpc_val);
    }
  }

  $s = new xmlrpc_server(
    array(
      "examples.myFunc1" =&gt; array("function" =&gt; "foo"),
      "examples.myFunc2" =&gt; array("function" =&gt; "bar::foobar"),
    ));

</programlisting>

      <para>This performs everything you need to do with a server. The single
      constructor argument is an associative array from xmlrpc method names to
      php function names. The incoming request is parsed and dispatched to the
      relevant php function, which is responsible for returning a
      <classname>xmlrpcresp</classname> object, that will be serialized back to
      the caller.</para>

      <sect2>
        <title>Method handler functions</title>

        <para>Both php functions and class methods can be registered as xmlrpc
        method handlers.</para>

        <para>The synopsis of a method handler function is:</para>

        <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>

        <para>No text should be echoed 'to screen' by the handler function, or
        it will break the xml response sent back to the client. This applies
        also to error and warning messages that PHP prints to screen unless the
        appropriate parameters have been set in the php.in file. Another way to
        prevent echoing of errors inside the response and facilitate debugging
        is to use the server SetDebug method with debug level 3 (see
        below).</para>

        <para>Note that if you implement a method with a name prefixed by
        <code>system.</code> the handler function will be invoked by the server
        with two parameters, the first being the server itself and the second
        being the <classname>xmlrpcmsg</classname> object.</para>

        <para>The same php function can be registered as handler of multiple
        xmlrpc methods.</para>

        <para>Here is a more detailed example of what the handler function
        <function>foo</function> may do:</para>

        <programlisting>
  function foo ($xmlrpcmsg) {
    global $xmlrpcerruser; // import user errcode base value

    $meth = $xmlrpcmsg-&gt;method(); // retrieve method name
    $par = $xmlrpcmsg-&gt;getParam(0); // retrieve value of first parameter - assumes at least one param received
    $val = $par-&gt;scalarval(); // decode value of first parameter - assumes it is a scalar value

    ...

    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"));
    }
  }

</programlisting>

        <para>See <filename>server.php</filename> in this distribution for more
        examples of how to do this.</para>

        <para>Since release 2.0RC3 there is a new, even simpler way of
        registering php functions with the server. See section 5.7 below</para>
      </sect2>

      <sect2>
        <title>The dispatch map</title>

        <para>The first argument to the <function>xmlrpc_server</function>
        constructor is an array, called the <emphasis>dispatch map</emphasis>.
        In this array is the information the server needs to service the XML-RPC
        methods you define.</para>

        <para>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:</para>

        <itemizedlist>
          <listitem>
            <para><function><literal>function</literal></function> - this entry
            is mandatory. It must be either a name of a function in the global
            scope which services the XML-RPC method, or an array containing an
            instance of an object and a static method name (for static class
            methods the 'class::method' syntax is also supported).</para>
          </listitem>

          <listitem>
            <para><function><literal>signature</literal></function> - this entry
            is an array containing the possible signatures (see <xref
            linkend="signatures" />) 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.</para>
          </listitem>

          <listitem>
            <para><function><literal>docstring</literal></function> - this entry
            is a string containing documentation for the method. The
            documentation may contain HTML markup.</para>
          </listitem>

          <listitem>
            <para><literal>signature_docs</literal> - this entry can be used to
            provide documentation for the single parameters. It must match in
            structure the 'signature' member. By default, only the
            <classname>documenting_xmlrpc_server</classname> class in the extras
            package will take advantage of this, since the "system.methodHelp"
            protocol does not support documenting method parameters
            individually.</para>
          </listitem>
        </itemizedlist>

        <para>Look at the <filename>server.php</filename> example in the
        distribution to see what a dispatch map looks like.</para>
      </sect2>

      <sect2 id="signatures" xreflabel="Signatures">
        <title>Method signatures</title>

        <para>A signature is a description of a method's return type and its
        parameter types. A method may have more than one signature.</para>

        <para>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 <programlisting>string examples.getStateName(int)
</programlisting> has the signature <programlisting>array($xmlrpcString, $xmlrpcInt)
</programlisting> and, assuming that it is the only possible signature for the
        method, it might be used like this in server creation: <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" =&gt; array(
    "function" =&gt; "findstate",
    "signature" =&gt; $findstate_sig,
    "docstring" =&gt; $findstate_doc
  )));

</programlisting></para>

        <para>Note that method signatures do not allow to check nested
        parameters, e.g. the number, names and types of the members of a struct
        param cannot be validated.</para>

        <para>If a method that you want to expose has a definite number of
        parameters, but each of those parameters could reasonably be of multiple
        types, the array of acceptable signatures will easily grow into a
        combinatorial explosion. To avoid such a situation, the lib defines the
        global var <varname>$xmlrpcValue</varname>, which can be used in method
        signatures as a placeholder for 'any xmlrpc type':</para>

        <para><programlisting>
$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" =&gt; array(
    "function" =&gt; "echoback",
    "signature" =&gt; $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
    "docstring" =&gt; $echoback_doc
  )));

</programlisting></para>

        <para>Methods <methodname>system.listMethods</methodname>,
        <methodname>system.methodHelp</methodname>,
        <methodname>system.methodSignature</methodname> and
        <methodname>system.multicall</methodname> are already defined by the
        server, and should not be reimplemented (see Reserved Methods
        below).</para>
      </sect2>

      <sect2>
        <title>Delaying the server response</title>

        <para>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 <literal>0</literal> this will have the desired
        effect. You can then use the <function>service()</function> method of
        the server class to service the request. For example:</para>

        <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();

</programlisting>

        <para>Note that the <methodname>service</methodname> 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.</para>

        <para>To prevent the server from sending HTTP headers back to the
        client, you can pass a second parameter with a value of
        <literal>TRUE</literal> to the <methodname>service</methodname> method.
        In this case, the response payload will be returned instead of the
        response object.</para>

        <para>Xmlrpc requests retrieved by other means than HTTP POST bodies can
        also be processed. For example:</para>

        <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

</programlisting>
      </sect2>

      <sect2>
        <title>Modifying the server behaviour</title>

        <para>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)</para>

        <sect3>
          <title>setDebug()</title>

          <para>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.</para>
        </sect3>

        <sect3>
          <title>allow_system_funcs</title>

          <para>Default_value: TRUE. When set to FALSE, disables support for
          <methodname>System.xxx</methodname> functions in the server. It might
          be useful e.g. if you do not wish the server to respond to requests to
          <methodname>System.ListMethods</methodname>.</para>
        </sect3>

        <sect3>
          <title>compress_response</title>

          <para>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.</para>

          <para>Note that the ZLIB php extension must be installed for this to
          work. If it is, <varname>compress_response</varname> will default to
          TRUE.</para>
        </sect3>

        <sect3>
          <title>response_charset_encoding</title>

          <para>Charset encoding to be used for response (only affects string
          values).</para>

          <para>If it can, the server will convert the generated response from
          internal_encoding to the intended one.</para>

          <para>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).</para>
        </sect3>
      </sect2>

      <sect2>
        <title>Fault reporting</title>

        <para>Fault codes for your servers should start at the value indicated
        by the global <literal>$xmlrpcerruser</literal> + 1.</para>

        <para>Standard errors returned by the server include:</para>

        <variablelist>
          <varlistentry>
            <term><literal>1</literal> <phrase>Unknown method</phrase></term>

            <listitem>
              <para>Returned if the server was asked to dispatch a method it
              didn't know about</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>2</literal> <phrase>Invalid return
            payload</phrase></term>

            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>3</literal> <phrase>Incorrect
            parameters</phrase></term>

            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>4</literal> <phrase>Can't introspect: method
            unknown</phrase></term>

            <listitem>
              <para>This error is generated by the builtin
              <function>system.*</function> methods when any kind of
              introspection is attempted on a method undefined by the
              server.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>5</literal> <phrase>Didn't receive 200 OK from remote
            server</phrase></term>

            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>6</literal> <phrase>No data received from
            server</phrase></term>

            <listitem>
              <para>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.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>7</literal> <phrase>No SSL support compiled
            in</phrase></term>

            <listitem>
              <para>This error is generated by the client when trying to send a
              request with HTTPS and the CURL extension is not available to
              PHP.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>8</literal> <phrase>CURL error</phrase></term>

            <listitem>
              <para>This error is generated by the client when trying to send a
              request with HTTPS and the HTTPS communication fails.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>9-14</literal> <phrase>multicall
            errors</phrase></term>

            <listitem>
              <para>These errors are generated by the server when something
              fails inside a system.multicall request.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>100-</literal> <phrase>XML parse
            errors</phrase></term>

            <listitem>
              <para>Returns 100 plus the XML parser error code for the fault
              that occurred. The <function>faultString</function> returned
              explains where the parse error was in the incoming XML
              stream.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </sect2>

      <sect2>
        <title>'New style' servers</title>

        <para>In the same spirit of simplification that inspired the
        <varname>xmlrpc_client::return_type</varname> class variable, a new
        class variable has been added to the server class:
        <varname>functions_parameters_type</varname>. 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:<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();

</programlisting>There are a few things to keep in mind when using this
        simplified syntax:</para>

        <para>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;</para>

        <para>to return a base64 value, the method handler function must encode
        it on its own, creating an instance of an xmlrpcval object;</para>

        <para>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;</para>

        <para>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;</para>

        <para>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;</para>

        <para>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.</para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="globalvars">
    <title>Global variables</title>

    <para>Many global variables are defined in the xmlrpc.inc file. Some of
    those are meant to be used as constants (and modifying their value might
    cause unpredictable behaviour), while some others can be modified in your
    php scripts to alter the behaviour of the xml-rpc client and server.</para>

    <sect1>
      <title>"Constant" variables</title>

      <sect2>
        <title>$xmlrpcerruser</title>

        <para><fieldsynopsis>
            <varname>$xmlrpcerruser</varname>

            <initializer>800</initializer>
          </fieldsynopsis>The minimum value for errors reported by user
        implemented XML-RPC servers. Error numbers lower than that are reserved
        for library usage.</para>
      </sect2>

      <sect2>
        <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
        $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64 , $xmlrpcArray,
        $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>

        <para>For convenience the strings representing the XML-RPC types have
        been encoded as global variables:<programlisting>
$xmlrpcI4="i4";
$xmlrpcInt="int";
$xmlrpcBoolean="boolean";
$xmlrpcDouble="double";
$xmlrpcString="string";
$xmlrpcDateTime="dateTime.iso8601";
$xmlrpcBase64="base64";
$xmlrpcArray="array";
$xmlrpcStruct="struct";
$xmlrpcValue="undefined";
$xmlrpcNull="null";

</programlisting></para>
      </sect2>

      <sect2>
        <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
        $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
        $xmlEntities, $xmlrpcs_capabilities</title>

        <para>Reserved for internal usage.</para>
      </sect2>
    </sect1>

    <sect1>
      <title>Variables whose value can be modified</title>

      <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
        <title xreflabel="">xmlrpc_defencoding</title>

        <fieldsynopsis>
          <varname>$xmlrpc_defencoding</varname>

          <initializer>"UTF8"</initializer>
        </fieldsynopsis>

        <para>This variable defines the character set encoding that will be used
        by the xml-rpc client and server to decode the received messages, when a
        specific charset declaration is not found (in the messages sent
        non-ascii chars are always encoded using character references, so that
        the produced xml is valid regardless of the charset encoding
        assumed).</para>

        <para>Allowed values: <literal>"UTF8"</literal>,
        <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>

        <para>Note that the appropriate RFC actually mandates that XML received
        over HTTP without indication of charset encoding be treated as US-ASCII,
        but many servers and clients 'in the wild' violate the standard, and
        assume the default encoding is UTF-8.</para>
      </sect2>

      <sect2>
        <title>xmlrpc_internalencoding</title>

        <para><fieldsynopsis>
            <varname>$xmlrpc_internalencoding</varname>

            <initializer>"ISO-8859-1"</initializer>
          </fieldsynopsis>This variable defines the character set encoding that
        the library uses to transparently encode into valid XML the xml-rpc
        values created by the user and to re-encode the received xml-rpc values
        when it passes them to the PHP application. It only affects xml-rpc
        values of string type. It is a separate value from xmlrpc_defencoding,
        allowing e.g. to send/receive xml messages encoded on-the-wire in
        US-ASCII and process them as UTF-8. It defaults to the character set
        used internally by PHP (unless you are running an MBString-enabled
        installation), so you should change it only in special situations, if
        e.g. the string values exchanged in the xml-rpc messages are directly
        inserted into / fetched from a database configured to return UTF8
        encoded strings to PHP. Example usage:</para>

        <para><programlisting>
&lt;?php

include('xmlrpc.inc');
$xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
$v = new xmlrpcval('κόσμε'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'

</programlisting></para>
      </sect2>

      <sect2>
        <title>xmlrpcName</title>

        <para><fieldsynopsis>
            <varname>$xmlrpcName</varname>

            <initializer>"XML-RPC for PHP"</initializer>
          </fieldsynopsis>The string representation of the name of the XML-RPC
        for PHP library. It is used by the client for building the User-Agent
        HTTP header that is sent with every request to the server. You can
        change its value if you need to customize the User-Agent string.</para>
      </sect2>

      <sect2>
        <title>xmlrpcVersion</title>

        <para><fieldsynopsis>
            <varname>$xmlrpcVersion</varname>

            <initializer>"2.2"</initializer>
          </fieldsynopsis>The string representation of the version number of the
        XML-RPC for PHP library in use. It is used by the client for building
        the User-Agent HTTP header that is sent with every request to the
        server. You can change its value if you need to customize the User-Agent
        string.</para>
      </sect2>

      <sect2>
        <title>xmlrpc_null_extension</title>

        <para>When set to <constant>TRUE</constant>, the lib will enable support
        for the &lt;NIL/&gt; xmlrpc value, as per the extension to the standard
        proposed here. This means that &lt;NIL/&gt; tags will be parsed as valid
        xmlrpc, and the corresponding xmlrpcvals will return "null" for
        <methodname>scalarTyp()</methodname>.</para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="helpers">
    <title>Helper functions</title>

    <para>XML-RPC for PHP contains some helper functions which you can use to
    make processing of XML-RPC requests easier.</para>

    <sect1>
      <title>Date functions</title>

      <para>The XML-RPC specification has this to say on dates:</para>

      <blockquote>
        <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
        specified by the server in its documentation what assumptions it makes
        about timezones.</para>
      </blockquote>

      <para>Unfortunately, this means that date processing isn't
      straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
      use the timezone specifier.</para>

      <para>We strongly recommend that in every case where you pass dates in
      XML-RPC calls, you use UTC (GMT) as your timezone. Most computer languages
      include routines for handling GMT times natively, and you won't have to
      translate between timezones.</para>

      <para>For more information about dates, see <ulink
      url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right Format
      for Dates</ulink>, which has a handy link to a PDF of the ISO 8601
      specification. Note that XML-RPC uses exactly one of the available
      representations: CCYYMMDDTHH:MM:SS.</para>

      <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
        <title>iso8601_encode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$isoString = iso8601_encode</funcdef>

            <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>

            <paramdef><type>int</type><parameter>$utc=0</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Returns an ISO 8601 formatted date generated from the UNIX
        timestamp <parameter>$time_t</parameter>, as returned by the PHP
        function <function>time()</function>.</para>

        <para>The argument <parameter>$utc</parameter> can be omitted, in which
        case it defaults to <literal>0</literal>. If it is set to
        <literal>1</literal>, then the function corrects the time passed in for
        UTC. Example: if you're in the GMT-6:00 timezone and set
        <parameter>$utc</parameter>, you will receive a date representation six
        hours ahead of your local time.</para>

        <para>The included demo program <filename>vardemo.php</filename>
        includes a demonstration of this function.</para>
      </sect2>

      <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
        <title>iso8601_decode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$time_t = iso8601_decode</funcdef>

            <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>

            <paramdef><type>int</type><parameter>$utc=0</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
        string passed in. If <parameter>$utc</parameter> is <literal>1</literal>
        then <parameter>$isoString</parameter> is assumed to be in the UTC
        timezone, and thus the <parameter>$time_t</parameter> result is also
        UTC: otherwise, the timezone is assumed to be your local timezone and
        you receive a local timestamp.</para>
      </sect2>
    </sect1>

    <sect1 id="arrayuse">
      <title>Easy use with nested PHP values</title>

      <para>Dan Libby was kind enough to contribute two helper functions that
      make it easier to translate to and from PHP values. This makes it easier
      to deal with complex structures. At the moment support is limited to
      <type>int</type>, <type>double</type>, <type>string</type>,
      <type>array</type>, <type>datetime</type> and <type>struct</type>
      datatypes; note also that all PHP arrays are encoded as structs, except
      arrays whose keys are integer numbers starting with 0 and incremented by
      1.</para>

      <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>

      <sect2 id="phpxmlrpcdecode">
        <title>php_xmlrpc_decode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$phpval = php_xmlrpc_decode</funcdef>

            <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>

            <paramdef><type>array</type><parameter>$options</parameter></paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$phpvals = php_xmlrpc_decode</funcdef>

            <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>

            <paramdef><type>string</type><parameter>$options</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Returns a native PHP value corresponding to the values found in
        the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
        translated into PHP types. Base-64 and datetime values are automatically
        decoded to strings.</para>

        <para>In the second form, returns an array containing the parameters of
        the given <parameter><classname>xmlrpcmsg</classname>_val</parameter>,
        decoded to php types.</para>

        <para>The <parameter>options</parameter> parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        decoding process. At the moment the only valid option is
        <symbol>decode_php_objs</symbol>. When it is set, php objects that have
        been converted to xml-rpc structs using the
        <function>php_xmlrpc_encode</function> function and a corresponding
        encoding option will be converted back into object values instead of
        arrays (provided that the class definition is available at
        reconstruction time).</para>

        <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
        extreme care before enabling the <symbol>decode_php_objs</symbol>
        option: when php objects are rebuilt from the received xml, their
        constructor function will be silently invoked. This means that you are
        allowing the remote end to trigger execution of uncontrolled PHP code on
        your server, opening the door to code injection exploits. Only enable
        this option when you have complete trust of the remote
        server/client.</para>

        <para>Example:<programlisting>
// wrapper to expose an existing php function as xmlrpc method handler
function foo_wrapper($m)
{
  $params = php_xmlrpc_decode($m);
  $retval = call_user_func_array('foo', $params);
  return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
}

$s = new xmlrpc_server(array(
   "examples.myFunc1" =&gt; array(
     "function" =&gt; "foo_wrapper",
     "signatures" =&gt; ...
  )));

</programlisting></para>
      </sect2>

      <sect2 id="phpxmlrpcencode">
        <title>php_xmlrpc_encode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$xmlrpc_val = php_xmlrpc_encode</funcdef>

            <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>

            <paramdef><type>array</type><parameter>$options</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Returns an <type>xmlrpcval</type> object populated with the PHP
        values in <parameter>$phpval</parameter>. Works recursively on arrays
        and objects, encoding numerically indexed php arrays into array-type
        xmlrpcval objects and non numerically indexed php arrays into
        struct-type xmlrpcval objects. Php objects are encoded into struct-type
        xmlrpcvals, excepted for php values that are already instances of the
        xmlrpcval class or descendants thereof, which will not be further
        encoded. Note that there's no support for encoding php values into
        base-64 values. Encoding of date-times is optionally carried on on php
        strings with the correct format.</para>

        <para>The <parameter>options</parameter> parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        encoding process. At the moment the only valid options are
        <symbol>encode_php_objs</symbol> and <symbol>auto_dates</symbol>.</para>

        <para>The first will enable the creation of 'particular' xmlrpcval
        objects out of php objects, that add a "php_class" xml attribute to
        their serialized representation. This attribute allows the function
        php_xmlrpc_decode to rebuild the native php objects (provided that the
        same class definition exists on both sides of the communication)</para>

        <para>Example:<programlisting>
// the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
$val = php_xmlrpc_encode(array(
  'first struct_element: an int' =&gt; 666,
  'second: an array' =&gt; array ('apple', 'orange', 'banana'),
  'third: a base64 element' =&gt; new xmlrpcval('hello world', 'base64'),
  'fourth: a datetime' =&gt; '20060107T01:53:00'
  ), array('auto_dates'));

</programlisting></para>
      </sect2>

      <sect2>
        <title>php_xmlrpc_decode_xml</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$xmlrpc_obj = php_xmlrpc_encode_xml</funcdef>

            <paramdef><type>string</type><parameter>$xml</parameter></paramdef>

            <paramdef><type>array</type><parameter>$options</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Decodes the xml representation of either an xmlrpc request,
        response or single value, returning the corresponding php-xmlrpc object,
        or <literal>FALSE</literal> in case of an error.</para>

        <para>The <parameter>options</parameter> parameter is optional. If
        specified, it must consist of an array of options to be enabled in the
        decoding process. At the moment, no option is supported.</para>

        <para>Example:<programlisting>
$text = '&lt;value&gt;&lt;array&gt;&lt;data&gt;&lt;value&gt;Hello world&lt;/value&gt;&lt;/data&gt;&lt;/array&gt;&lt;/value&gt;';
$val = php_xmlrpc_decode_xml($text);
if ($val) echo 'Found a value of type '.$val-&gt;kindOf(); else echo 'Found invalid xml';

</programlisting></para>
      </sect2>
    </sect1>

    <sect1>
      <title>Automatic conversion of php functions into xmlrpc methods (and vice
      versa)</title>

      <para>For the extremely lazy coder, helper functions have been added that
      allow to convert a php function into an xmlrpc method, and a remotely
      exposed xmlrpc method into a local php function - or a set of methods into
      a php class. Note that these comes with many caveat.</para>

      <sect2>
        <title>wrap_xmlrpc_method</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$new_php_function_name = wrap_xmlrpc_method</funcdef>

            <paramdef>$client</paramdef>

            <paramdef>$methodname</paramdef>

            <paramdef>$extra_options</paramdef>
          </funcprototype>

          <funcprototype>
            <funcdef>$new_php_function_name = wrap_xmlrpc_method</funcdef>

            <paramdef>$client</paramdef>

            <paramdef>$methodname</paramdef>

            <paramdef>$signum</paramdef>

            <paramdef>$timeout</paramdef>

            <paramdef>$protocol</paramdef>

            <paramdef>$funcname</paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Given an xmlrpc server and a method name, creates a php wrapper
        function that will call the remote method and return results using
        native php types for both params and results. The generated php function
        will return an xmlrpcresp object for failed xmlrpc calls.</para>

        <para>The second syntax is deprecated, and is listed here only for
        backward compatibility.</para>

        <para>The server must support the
        <methodname>system.methodSignature</methodname> xmlrpc method call for
        this function to work.</para>

        <para>The <parameter>client</parameter> param must be a valid
        xmlrpc_client object, previously created with the address of the target
        xmlrpc server, and to which the preferred communication options have
        been set.</para>

        <para>The optional parameters can be passed as array key,value pairs in
        the <parameter>extra_options</parameter> param.</para>

        <para>The <parameter>signum</parameter> optional param has the purpose
        of indicating which method signature to use, if the given server method
        has multiple signatures (defaults to 0).</para>

        <para>The <parameter>timeout</parameter> and
        <parameter>protocol</parameter> optional params are the same as in the
        <methodname>xmlrpc_client::send()</methodname> method.</para>

        <para>If set, the optional <parameter>new_function_name</parameter>
        parameter indicates which name should be used for the generated
        function. In case it is not set the function name will be
        auto-generated.</para>

        <para>If the <literal>return_source</literal> optional parameter is set,
        the function will return the php source code to build the wrapper
        function, instead of evaluating it (useful to save the code and use it
        later as stand-alone xmlrpc client).</para>

        <para>If the <literal>encode_php_objs</literal> optional parameter is
        set, instances of php objects later passed as parameters to the newly
        created function will receive a 'special' treatment that allows the
        server to rebuild them as php objects instead of simple arrays. Note
        that this entails using a "slightly augmented" version of the xmlrpc
        protocol (ie. using element attributes), which might not be understood
        by xmlrpc servers implemented using other libraries.</para>

        <para>If the <literal>decode_php_objs</literal> optional parameter is
        set, instances of php objects that have been appropriately encoded by
        the server using a coordinate option will be deserialized as php objects
        instead of simple arrays (the same class definition should be present
        server side and client side).</para>

        <para><emphasis>Note that this might pose a security risk</emphasis>,
        since in order to rebuild the object instances their constructor method
        has to be invoked, and this means that the remote server can trigger
        execution of unforeseen php code on the client: not really a code
        injection, but almost. Please enable this option only when you trust the
        remote server.</para>

        <para>In case of an error during generation of the wrapper function,
        FALSE is returned, otherwise the name (or source code) of the new
        function.</para>

        <para>Known limitations: server must support
        <methodname>system.methodsignature</methodname> for the wanted xmlrpc
        method; for methods that expose multiple signatures, only one can be
        picked; for remote calls with nested xmlrpc params, the caller of the
        generated php function has to encode on its own the params passed to the
        php function if these are structs or arrays whose (sub)members include
        values of type base64.</para>

        <para>Note: calling the generated php function 'might' be slow: a new
        xmlrpc client is created on every invocation and an xmlrpc-connection
        opened+closed. An extra 'debug' param is appended to the parameter list
        of the generated php function, useful for debugging purposes.</para>

        <para>Example usage:</para>

        <programlisting>
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');

$function = wrap_xmlrpc_method($client, 'examples.getStateName');

if (!$function)
  die('Cannot introspect remote method');
else {
  $stateno = 15;
  $statename = $function($a);
  if (is_a($statename, 'xmlrpcresp')) // call failed
  {
    echo 'Call failed: '.$statename-&gt;faultCode().'. Calling again with debug on';
    $function($a, true);
  }
  else
    echo "OK, state nr. $stateno is $statename";
}

</programlisting>
      </sect2>

      <sect2 id="wrap_php_function">
        <title>wrap_php_function</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$dispatch_map_definition = wrap_php_function</funcdef>

            <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>

            <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>

            <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Given a user-defined PHP function, create a PHP 'wrapper' function
        that can be exposed as xmlrpc method from an xmlrpc_server object and
        called from remote clients, and return the appropriate definition to be
        added to a server's dispatch map.</para>

        <para>The optional <parameter>$wrapper_function_name</parameter>
        specifies the name that will be used for the auto-generated
        function.</para>

        <para>Since php is a typeless language, to infer types of input and
        output parameters, it relies on parsing the javadoc-style comment block
        associated with the given function. Usage of xmlrpc native types (such
        as datetime.dateTime.iso8601 and base64) in the docblock @param tag is
        also allowed, if you need the php function to receive/send data in that
        particular format (note that base64 encoding/decoding is transparently
        carried out by the lib, while datetime vals are passed around as
        strings).</para>

        <para>Known limitations: requires PHP 5.0.3 +; only works for
        user-defined functions, not for PHP internal functions (reflection does
        not support retrieving number/type of params for those); the wrapped php
        function will not be able to programmatically return an xmlrpc error
        response.</para>

        <para>If the <literal>return_source</literal> optional parameter is set,
        the function will return the php source code to build the wrapper
        function, instead of evaluating it (useful to save the code and use it
        later in a stand-alone xmlrpc server). It will be in the stored in the
        <literal>source</literal> member of the returned array.</para>

        <para>If the <literal>suppress_warnings</literal> optional parameter is
        set, any runtime warning generated while processing the user-defined php
        function will be catched and not be printed in the generated xml
        response.</para>

        <para>If the <parameter>extra_options</parameter> array contains the
        <literal>encode_php_objs</literal> value, wrapped functions returning
        php objects will generate "special" xmlrpc responses: when the xmlrpc
        decoding of those responses is carried out by this same lib, using the
        appropriate param in php_xmlrpc_decode(), the objects will be
        rebuilt.</para>

        <para>In short: php objects can be serialized, too (except for their
        resource members), using this function. Other libs might choke on the
        very same xml that will be generated in this case (i.e. it has a
        nonstandard attribute on struct element tags)</para>

        <para>If the <literal>decode_php_objs</literal> optional parameter is
        set, instances of php objects that have been appropriately encoded by
        the client using a coordinate option will be deserialized and passed to
        the user function as php objects instead of simple arrays (the same
        class definition should be present server side and client side).</para>

        <para><emphasis>Note that this might pose a security risk</emphasis>,
        since in order to rebuild the object instances their constructor method
        has to be invoked, and this means that the remote client can trigger
        execution of unforeseen php code on the server: not really a code
        injection, but almost. Please enable this option only when you trust the
        remote clients.</para>

        <para>Example usage:</para>

        <para><programlisting>/**
* State name from state number decoder. NB: do NOT remove this comment block.
* @param integer $stateno the state number
* @return string the name of the state (or error description)
*/
function findstate($stateno)
{
  global $stateNames;
  if (isset($stateNames[$stateno-1]))
  {
    return $stateNames[$stateno-1];
  }
  else
  {
    return "I don't have a state for the index '" . $stateno . "'";
  }
}

// wrap php function, build xmlrpc server
$methods = array();
$findstate_sig = wrap_php_function('findstate');
if ($findstate_sig)
  $methods['examples.getStateName'] = $findstate_sig;
$srv = new xmlrpc_server($methods);

</programlisting></para>
      </sect2>
    </sect1>

    <sect1 id="deprecated">
      <title>Functions removed from the library</title>

      <para>The following two functions have been deprecated in version 1.1 of
      the library, and removed in version 2, in order to avoid conflicts with
      the EPI xml-rpc library, which also defines two functions with the same
      names.</para>

      <para>To ease the transition to the new naming scheme and avoid breaking
      existing implementations, the following scheme has been adopted:
      <itemizedlist>
          <listitem>
            <para>If EPI-XMLRPC is not active in the current PHP installation,
            the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
            <literal>'0'</literal></para>
          </listitem>

          <listitem>
            <para>If EPI-XMLRPC is active in the current PHP installation, the
            constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
            <literal>'1'</literal></para>
          </listitem>
        </itemizedlist></para>

      <para>The following documentation is kept for historical reference:</para>

      <sect2 id="xmlrpcdecode">
        <title>xmlrpc_decode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$phpval = xmlrpc_decode</funcdef>

            <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Alias for php_xmlrpc_decode.</para>
      </sect2>

      <sect2 id="xmlrpcencode">
        <title>xmlrpc_encode</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>$xmlrpc_val = xmlrpc_encode</funcdef>

            <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Alias for php_xmlrpc_encode.</para>
      </sect2>
    </sect1>

    <sect1 id="debugging">
      <title>Debugging aids</title>

      <sect2>
        <title>xmlrpc_debugmsg</title>

        <funcsynopsis>
          <funcprototype>
            <funcdef>xmlrpc_debugmsg</funcdef>

            <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>

        <para>Sends the contents of <parameter>$debugstring</parameter> in XML
        comments in the server return payload. If a PHP client has debugging
        turned on, the user will be able to see server debug information.</para>

        <para>Use this function in your methods so you can pass back diagnostic
        information. It is only available from
        <filename>xmlrpcs.inc</filename>.</para>
      </sect2>
    </sect1>
  </chapter>

  <chapter id="reserved" xreflabel="Reserved methods">
    <title>Reserved methods</title>

    <para>In order to extend the functionality offered by XML-RPC servers
    without impacting on the protocol, reserved methods are supported in this
    release.</para>

    <para>All methods starting with <function>system.</function> are considered
    reserved by the server. PHP for XML-RPC itself provides four special
    methods, detailed in this chapter.</para>

    <para>Note that all server objects will automatically respond to clients
    querying these methods, unless the property
    <property>allow_system_funcs</property> has been set to
    <constant>false</constant> before calling the
    <methodname>service()</methodname> method. This might pose a security risk
    if the server is exposed to public access, e.g. on the internet.</para>

    <sect1>
      <title>system.getCapabilities</title>

      <para></para>
    </sect1>

    <sect1>
      <title>system.listMethods</title>

      <para>This method may be used to enumerate the methods implemented by the
      XML-RPC server.</para>

      <para>The <function>system.listMethods</function> method requires no
      parameters. It returns an array of strings, each of which is the name of a
      method implemented by the server.</para>
    </sect1>

    <sect1 id="sysmethodsig">
      <title>system.methodSignature</title>

      <para>This method takes one parameter, the name of a method implemented by
      the XML-RPC server.</para>

      <para>It returns an array of possible signatures for this method. A
      signature is an array of types. The first of these types is the return
      type of the method, the rest are parameters.</para>

      <para>Multiple signatures (i.e. overloading) are permitted: this is the
      reason that an array of signatures are returned by this method.</para>

      <para>Signatures themselves are restricted to the top level parameters
      expected by a method. For instance if a method expects one array of
      structs as a parameter, and it returns a string, its signature is simply
      "string, array". If it expects three integers, its signature is "string,
      int, int, int".</para>

      <para>For parameters that can be of more than one type, the "undefined"
      string is supported.</para>

      <para>If no signature is defined for the method, a not-array value is
      returned. Therefore this is the way to test for a non-signature, if
      <parameter>$resp</parameter> below is the response object from a method
      call to <function>system.methodSignature</function>:</para>

      <programlisting>
$v = $resp-&gt;value();
if ($v-&gt;kindOf() != "array") {
  // then the method did not have a signature defined
}
                        </programlisting>

      <para>See the <filename>introspect.php</filename> demo included in this
      distribution for an example of using this method.</para>
    </sect1>

    <sect1 id="sysmethhelp">
      <title>system.methodHelp</title>

      <para>This method takes one parameter, the name of a method implemented by
      the XML-RPC server.</para>

      <para>It returns a documentation string describing the use of that method.
      If no such string is available, an empty string is returned.</para>

      <para>The documentation string may contain HTML markup.</para>
    </sect1>

    <sect1>
      <title>system.multicall</title>

      <para>This method takes one parameter, an array of 'request' struct types.
      Each request struct must contain a <parameter>methodName</parameter>
      member of type string and a <parameter>params</parameter> member of type
      array, and corresponds to the invocation of the corresponding
      method.</para>

      <para>It returns a response of type array, with each value of the array
      being either an error struct (containing the faultCode and faultString
      members) or the successful response value of the corresponding single
      method call.</para>
    </sect1>
  </chapter>

  <chapter id="examples" xreflabel="Examples">
    <title>Examples</title>

    <para>The best examples are to be found in the sample files included with
    the distribution. Some are included here.</para>

    <sect1 id="statename">
      <title>XML-RPC client: state name query</title>

      <para>Code to get the corresponding state name from a number (1-50) from
      the demo server available on SourceForge</para>

      <programlisting>
  $m = new xmlrpcmsg('examples.getStateName',
    array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
  $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
  $r = $c-&gt;send($m);
  if (!$r-&gt;faultCode()) {
      $v = $r-&gt;value();
      print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
        htmlentities($v-&gt;scalarval()) . "&lt;BR&gt;";
      print "&lt;HR&gt;I got this value back&lt;BR&gt;&lt;PRE&gt;" .
        htmlentities($r-&gt;serialize()) . "&lt;/PRE&gt;&lt;HR&gt;\n";
  } else {
      print "Fault &lt;BR&gt;";
      print "Code: " . htmlentities($r-&gt;faultCode()) . "&lt;BR&gt;" .
            "Reason: '" . htmlentities($r-&gt;faultString()) . "'&lt;BR&gt;";
  }
                </programlisting>
    </sect1>

    <sect1>
      <title>Executing a multicall call</title>

      <para>To be documented...</para>
    </sect1>
  </chapter>

  <chapter>
    <title>Frequently Asked Questions</title>

    <sect1>
      <title>How to send XML as payload of a method call</title>

      <para>Unfortunately, at the time the XML-RPC spec was designed, support
      for namespaces in XML was not as ubiquitous as it is now. As a
      consequence, no support was provided in the protocol for embedding XML
      elements from other namespaces into an xmlrpc request.</para>

      <para>To send an XML "chunk" as payload of a method call or response, two
      options are available: either send the complete XML block as a string
      xmlrpc value, or as a base64 value. Since the '&lt;' character in string
      values is encoded as '&amp;lt;' in the xml payload of the method call, the
      XML string will not break the surrounding xmlrpc, unless characters
      outside of the assumed character set are used. The second method has the
      added benefits of working independently of the charset encoding used for
      the xml to be transmitted, and preserving exactly whitespace, whilst
      incurring in some extra message length and cpu load (for carrying out the
      base64 encoding/decoding).</para>
    </sect1>

    <sect1>
      <title>Is there any limitation on the size of the requests / responses
      that can be successfully sent?</title>

      <para>Yes. But I have no hard figure to give; it most likely will depend
      on the version of PHP in usage and its configuration.</para>

      <para>Keep in mind that this library is not optimized for speed nor for
      memory usage. Better alternatives exist when there are strict requirements
      on throughput or resource usage, such as the php native xmlrpc extension
      (see the PHP manual for more information).</para>

      <para>Keep in mind also that HTTP is probably not the best choice in such
      a situation, and XML is a deadly enemy. CVS formatted data over socket
      would be much more efficient.</para>

      <para>If you really need to move a massive amount of data around, and you
      are crazy enough to do it using phpxmlrpc, your best bet is to bypass
      usage of the xmlrpcval objects, at least in the decoding phase, and have
      the server (or client) object return to the calling function directly php
      values (see <varname>xmlrpc_client::return_type</varname> and
      <varname>xmlrpc_server::functions_parameters_type</varname> for more
      details).</para>
    </sect1>

    <sect1>
      <title>My server (client) returns an error whenever the client (server)
      returns accented characters</title>

      <para>To be documented...</para>
    </sect1>

    <sect1>
      <title>My php error log is getting full of "deprecated" errors on
      different lines of xmlrpc.inc and xmlrpcs.inc</title>

      <para>This happens when the PHP in usage is version 5, and the error
      reporting level is set to include <constant>E_STRICT</constant> errors.
      Since the main development platform of the library remains (for the time
      being) PHP 4, there are no plans to fix this asap. The best workaround is
      to set the error reporting level to <constant>E_ALL ^
      E_STRICT</constant>.</para>
    </sect1>

    <sect1>
      <title>How to enable long-lasting method calls</title>

      <para>To be documented...</para>
    </sect1>

    <sect1>
      <title>My client returns "XML-RPC Fault #2: Invalid return payload: enable
      debugging to examine incoming payload": what should I do?</title>

      <para>The response you are seeing is a default error reponse that the
      client object returns to the php application when the server did not
      respond to the call with a valid xmlrpc response.</para>

      <para>The most likely cause is that you are not using the correct URL when
      creating the client object, or you do not have approriate access rights to
      the web page you are requesting, or some other common http
      misconfiguration.</para>

      <para>To find out what the server is really returning to your client, you
      have to enable the debug mode of the client, using
      $client-&gt;setdebug(1);</para>
    </sect1>

    <sect1>
      <title>How can I save to a file the xml of the xmlrpc responses received
      from servers?</title>

      <para>If what you need is to save the responses received from the server
      as xml, you have two options:</para>

      <para>1- use the serialize() method on the response object.</para>

      <programlisting>
$resp = $client-&gt;send($msg);
if (!$resp-&gt;faultCode())
  $data_to_be_saved = $resp-&gt;serialize();

</programlisting>

      <para>Note that this will not be 100% accurate, since the xml generated by
      the response object can be different from the xml received, especially if
      there is some character set conversion involved, or such (eg. if you
      receive an empty string tag as &lt;string/&gt;, serialize() will output
      &lt;string&gt;&lt;/string&gt;), or if the server sent back as response
      something invalid (in which case the xml generated client side using
      serialize() wil correspond to the error response generated internally by
      the lib).</para>

      <para>2 - set the client object to return the raw xml received instead of
      the decoded objects:</para>

      <programlisting>
$client = new xmlrpc_client($url);
$client-&gt;return_type = 'xml';
$resp = $client-&gt;send($msg);
if (!$resp-&gt;faultCode())
  $data_to_be_saved = $resp-&gt;value();

</programlisting>

      <para>Note that using this method the xml response response will not be
      parsed at all by the library, only the http communication protocol will be
      checked. This means that xmlrpc responses sent by the server that would
      have generated an error response on the client (eg. malformed xml,
      responses that have faultcode set, etc...) now will not be flagged as
      invalid, and you might end up saving not valid xml but random
      junk...</para>
    </sect1>
  </chapter>

  <appendix>
    <title>Integration with the PHP xmlrpc extension</title>

    <para>To be documented more...</para>

    <para>In short: for the fastest execution possible, you can enable the php
    native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
    following code snippet gives an example of such integration</para>

    <programlisting>
/*** client side ***/
$c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');

// tell the client to return raw xml as response value
$c-&gt;return_type = 'xml';

// let's the native xmlrpc extension take care of encoding request parameters
$r = $c-&gt;send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));

if ($r-&gt;faultCode())
  // HTTP transport error
  echo 'Got error '.$r-&gt;faultCode();
else
{
  // HTTP request OK, but XML returned from server not parsed yet
  $v = xmlrpc_decode($r-&gt;value());
  // check if we got a valid xmlrpc response from server
  if ($v === NULL)
    echo 'Got invalid response';
  else
  // check if server sent a fault response
  if (xmlrpc_is_fault($v))
    echo 'Got xmlrpc fault '.$v['faultCode'];
  else
    echo'Got response: '.htmlentities($v);
}

</programlisting>
  </appendix>

  <appendix>
    <title>Substitution of the PHP xmlrpc extension</title>

    <para>Yet another interesting situation is when you are using a ready-made
    php application, that provides support for the XMLRPC protocol via the
    native php xmlrpc extension, but the extension is not available on your php
    install (e.g. because of shared hosting constraints).</para>

    <para>Since version 2.1, the PHP-XMLRPC library provides a compatibility
    layer that aims to be 100% compliant with the xmlrpc extension API. This
    means that any code written to run on the extension should obtain the exact
    same results, albeit using more resources and a longer processing time,
    using the PHP-XMLRPC library and the extension compatibility module. The
    module is part of the EXTRAS package, available as a separate download from
    the sourceforge.net website, since version 0.2</para>
  </appendix>

  <appendix>
    <title>'Enough of xmlrpcvals!': new style library usage</title>

    <para>To be documented...</para>

    <para>In the meantime, see docs about xmlrpc_client::return_type and
    xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
    php_xmlrpc_decode and php_xmlrpc_decode_xml</para>
  </appendix>

  <appendix>
    <title>Usage of the debugger</title>

    <para>A webservice debugger is included in the library to help during
    development and testing.</para>

    <para>The interface should be self-explicative enough to need little
    documentation.</para>

    <para>The most useful feature of the debugger is without doubt the "Show
    debug info" option. It allows to have a screen dump of the complete http
    communication between client and server, including the http headers as well
    as the request and response payloads, and is invaluable when troubleshooting
    problems with charset encoding, authentication or http compression.</para>

    <para>The debugger can take advantage of the JSONRPC library extension, to
    allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library visual
    editor to allow easy mouse-driven construction of the payload for remote
    methods. Both components have to be downloaded separately from the
    sourceforge.net web pages and copied to the debugger directory to enable the
    extra functionality:</para>

    <para><itemizedlist>
        <listitem>
          <para>to enable jsonrpc functionality, download the PHP-XMLRPC EXTRAS
          package, and copy the file <filename>jsonrpc.inc</filename> either to
          the same directory as the debugger or somewhere in your php include
          path</para>
        </listitem>
      </itemizedlist><itemizedlist>
        <listitem>
          <para>to enable the visual value editing dialog, download the
          JS-XMLRPC library, and copy somewhere in the web root files
          <filename>visualeditor.php</filename>,
          <filename>visualeditor.css</filename> and the folders
          <filename>yui</filename> and <filename>img</filename>. Then edit the
          debugger file <filename>controller.php</filename> and set
          appropriately the variable <varname>$editorpath</varname>.</para>
        </listitem>
      </itemizedlist></para>
  </appendix>
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
sgml-namecase-general:t
sgml-general-insert-case:lower
End:
-->