doc/xmlrpc_php.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
   3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5 <!--
   6 PHP-XMLRPC User manual
   7 $Id: xmlrpc_php.xml,v 1.27 2008/09/19 18:35:33 ggiunta Exp $
   8 -->
   9 <book lang="en">
  10   <title>XML-RPC for PHP</title>
  11
  12   <subtitle>version 2.2.2</subtitle>
  13
  14   <bookinfo>
  15     <date>XXX YY, 2008</date>
  16
  17     <authorgroup>
  18       <author>
  19         <firstname>Edd</firstname>
  20
  21         <surname>Dumbill</surname>
  22       </author>
  23
  24       <author>
  25         <firstname>Gaetano</firstname>
  26
  27         <surname>Giunta</surname>
  28       </author>
  29
  30       <author>
  31         <firstname>Miles</firstname>
  32
  33         <surname>Lott</surname>
  34       </author>
  35
  36       <author>
  37         <firstname>Justin R.</firstname>
  38
  39         <surname>Miller</surname>
  40       </author>
  41
  42       <author>
  43         <firstname>Andres</firstname>
  44
  45         <surname>Salomon</surname>
  46       </author>
  47     </authorgroup>
  48
  49     <copyright>
  50       <year>1999,2000,2001</year>
  51
  52       <holder>Edd Dumbill, Useful Information Company</holder>
  53     </copyright>
  54
  55     <legalnotice>
  56       <para>All rights reserved.</para>
  57
  58       <para>Redistribution and use in source and binary forms, with or without
  59       modification, are permitted provided that the following conditions are
  60       met:</para>
  61
  62       <para><itemizedlist>
  63           <listitem>
  64             <para>Redistributions of source code must retain the above
  65             copyright notice, this list of conditions and the following
  66             disclaimer.</para>
  67           </listitem>
  68
  69           <listitem>
  70             <para>Redistributions in binary form must reproduce the above
  71             copyright notice, this list of conditions and the following
  72             disclaimer in the documentation and/or other materials provided
  73             with the distribution.</para>
  74           </listitem>
  75
  76           <listitem>
  77             <para>Neither the name of the "XML-RPC for PHP" nor the names of
  78             its contributors may be used to endorse or promote products
  79             derived from this software without specific prior written
  80             permission.</para>
  81           </listitem>
  82         </itemizedlist></para>
  83
  84       <para>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  85       CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
  86       BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  87       FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  88       REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  89       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  90       TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  91       PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  92       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  93       NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  94       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
  95     </legalnotice>
  96   </bookinfo>
  97
  98   <chapter id="introduction">
  99     <title>Introduction</title>
 100
 101     <para>XML-RPC is a format devised by <ulink
 102     url="http://www.userland.com/">Userland Software</ulink> for achieving
 103     remote procedure call via XML using HTTP as the transport. XML-RPC has its
 104     own web site, <ulink
 105     url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink></para>
 106
 107     <para>This collection of PHP classes provides a framework for writing
 108     XML-RPC clients and servers in PHP.</para>
 109
 110     <para>Main goals of the project are ease of use, flexibility and
 111     completeness.</para>
 112
 113     <para>The original author is Edd Dumbill of <ulink
 114     url="http://usefulinc.com/">Useful Information Company</ulink>. As of the
 115     1.0 stable release, the project has been opened to wider involvement and
 116     moved to <ulink
 117     url="http://phpxmlrpc.sourceforge.net/">SourceForge</ulink>.</para>
 118
 119     <para>A list of XML-RPC implementations for other languages such as Perl
 120     and Python can be found on the <ulink
 121     url="http://www.xmlrpc.com/">www.xmlrpc.com</ulink> site.</para>
 122
 123     <sect1>
 124       <title>Acknowledgements</title>
 125
 126       <para>Daniel E. Baumann</para>
 127
 128       <para>James Bercegay</para>
 129
 130       <para>Leon Blackwell</para>
 131
 132       <para>Stephane Bortzmeyer</para>
 133
 134       <para>Daniel Convissor</para>
 135
 136       <para>Geoffrey T. Dairiki</para>
 137
 138       <para>Stefan Esser</para>
 139
 140       <para>James Flemer</para>
 141
 142       <para>Ernst de Haan</para>
 143
 144       <para>Tom Knight</para>
 145
 146       <para>Axel Kollmorgen</para>
 147
 148       <para>Peter Kocks</para>
 149
 150       <para>Daniel Krippner</para>
 151
 152       <para>S. Kuip</para>
 153
 154       <para>A. Lambert</para>
 155
 156       <para>Dan Libby</para>
 157
 158       <para>Arnaud Limbourg</para>
 159
 160       <para>Ernest MacDougal Campbell III</para>
 161
 162       <para>Lukasz Mach</para>
 163
 164       <para>Kjartan Mannes</para>
 165
 166       <para>Ben Margolin</para>
 167
 168       <para>Nicolay Mausz</para>
 169
 170       <para>Justin Miller</para>
 171
 172       <para>Jan Pfeifer</para>
 173
 174       <para>Giancarlo Pinerolo</para>
 175
 176       <para>Peter Russel</para>
 177
 178       <para>Viliam Simko</para>
 179
 180       <para>Douglas Squirrel</para>
 181
 182       <para>Idan Sofer</para>
 183
 184       <para>Anatoly Techtonik</para>
 185
 186       <para>Eric van der Vlist</para>
 187
 188       <para>Christian Wenz</para>
 189
 190       <para>Jim Winstead</para>
 191
 192       <para>Przemyslaw Wroblewski</para>
 193     </sect1>
 194   </chapter>
 195
 196   <chapter id="news">
 197     <title>What's new</title>
 198
 199     <para><emphasis>Note:</emphasis> not all items the following list have
 200     (yet) been fully documented, and some might not be present in any other
 201     chapter in the manual. To find a more detailed description of new
 202     functions and methods please take a look at the source code of the
 203     library, which is quite thoroughly commented in javadoc-like form.</para>
 204
 205     <sect1>
 206       <title>2.2.2</title>
 207
 208       <para><emphasis>Note:</emphasis> this might the last release of the
 209       library that will support PHP 4. Future releases (if any) should target
 210       php 5.0 as minimum supported version.</para>
 211
 212       <para><itemizedlist>
 213           <listitem>
 214             <para>fixed: encoding of utf-8 characters outside of the BMP
 215             plane</para>
 216           </listitem>
 217
 218           <listitem>
 219             <para>fixed: character set declarations surrounded by double
 220             quotes were not recognized in http headers</para>
 221           </listitem>
 222
 223           <listitem>
 224             <para>fixed: be more tolerant in detection of charset in http
 225             headers</para>
 226           </listitem>
 227
 228           <listitem>
 229             <para>fixed: fix detection of zlib.output_compression</para>
 230           </listitem>
 231
 232           <listitem>
 233             <para>fixed: use feof() to test if socket connections are to be
 234             closed instead of the number of bytes read (rare bug when
 235             communicating with some servers)</para>
 236           </listitem>
 237
 238           <listitem>
 239             <para>fixed: format floating point values using the correct
 240             decimal separator even when php locale is set to one that uses
 241             comma</para>
 242           </listitem>
 243
 244           <listitem>
 245             <para>fixed: improve robustness of the debugger when parsing weird
 246             results from non-compliant servers</para>
 247           </listitem>
 248
 249           <listitem>
 250             <para>php warning when receiving 'false' in a bool value</para>
 251           </listitem>
 252
 253           <listitem>
 254             <para>improved: allow the add_to_map server method to add docs for
 255             single params too</para>
 256           </listitem>
 257
 258           <listitem>
 259             <para>improved: added the possibility to wrap for exposure as
 260             xmlrpc methods plain php class methods, object methods and even
 261             whole classes</para>
 262           </listitem>
 263         </itemizedlist></para>
 264     </sect1>
 265
 266     <sect1>
 267       <title>2.2.1</title>
 268
 269       <itemizedlist>
 270         <listitem>
 271           <para>fixed: work aroung bug in php 5.2.2 which broke support of
 272           HTTP_RAW_POST_DATA</para>
 273         </listitem>
 274
 275         <listitem>
 276           <para>fixed: is_dir parameter of setCaCertificate() method is
 277           reversed</para>
 278         </listitem>
 279
 280         <listitem>
 281           <para>fixed: a php warning in xmlrpc_client creator method</para>
 282         </listitem>
 283
 284         <listitem>
 285           <para>fixed: parsing of '1e+1' as valid float</para>
 286         </listitem>
 287
 288         <listitem>
 289           <para>fixed: allow errorlevel 3 to work when prev. error handler was
 290           a static method</para>
 291         </listitem>
 292
 293         <listitem>
 294           <para>fixed: usage of client::setcookie() for multiple cookies in
 295           non-ssl mode</para>
 296         </listitem>
 297
 298         <listitem>
 299           <para>improved: support for CP1252 charset is not part or the
 300           library but almost possible</para>
 301         </listitem>
 302
 303         <listitem>
 304           <para>improved: more info when curl is enabled and debug mode is
 305           on</para>
 306         </listitem>
 307       </itemizedlist>
 308     </sect1>
 309
 310     <sect1>
 311       <title>2.2</title>
 312
 313       <itemizedlist>
 314         <listitem>
 315           <para>fixed: debugger errors on php installs with magic_quotes_gpc
 316           on</para>
 317         </listitem>
 318
 319         <listitem>
 320           <para>fixed: support for https connections via proxy</para>
 321         </listitem>
 322
 323         <listitem>
 324           <para>fixed: wrap_xmlrpc_method() generated code failed to properly
 325           encode php objects</para>
 326         </listitem>
 327
 328         <listitem>
 329           <para>improved: slightly faster encoding of data which is internally
 330           UTF-8</para>
 331         </listitem>
 332
 333         <listitem>
 334           <para>improved: debugger always generates a 'null' id for jsonrpc if
 335           user omits it</para>
 336         </listitem>
 337
 338         <listitem>
 339           <para>new: debugger can take advantage of a graphical value builder
 340           (it has to be downloaded separately, as part of jsxmlrpc package.
 341           See Appendix D for more details)</para>
 342         </listitem>
 343
 344         <listitem>
 345           <para>new: support for the &lt;NIL/&gt; xmlrpc extension. see below
 346           for more details</para>
 347         </listitem>
 348
 349         <listitem>
 350           <para>new: server support for the system.getCapabilities xmlrpc
 351           extension</para>
 352         </listitem>
 353
 354         <listitem>
 355           <para>new: <function><link
 356           linkend="wrap_xmlrpc_method">wrap_xmlrpc_method()</link></function>
 357           accepts two new options: debug and return_on_fault</para>
 358         </listitem>
 359       </itemizedlist>
 360     </sect1>
 361
 362     <sect1>
 363       <title>2.1</title>
 364
 365       <para><itemizedlist>
 366           <listitem>
 367             <para>The <function>wrap_php_function</function> and
 368             <function>wrap_xmlrpc_method</function> functions have been moved
 369             out of the base library file <filename>xmlrpc.inc</filename> into
 370             a file of their own: <filename>xmlrpc_wrappers.inc</filename>. You
 371             will have to include() / require() it in your scripts if you have
 372             been using those functions. For increased security, the automatic
 373             rebuilding of php object instances out of received xmlrpc structs
 374             in <function>wrap_xmlrpc_method()</function> has been disabled
 375             (but it can be optionally re-enabled). Both
 376             <function>wrap_php_function()</function> and
 377             <function>wrap_xmlrpc_method()</function> functions accept many
 378             more options to fine tune their behaviour, including one to return
 379             the php code to be saved and later used as standalone php
 380             script</para>
 381           </listitem>
 382
 383           <listitem>
 384             <para>The constructor of xmlrpcval() values has seen some internal
 385             changes, and it will not throw a php warning anymore when invoked
 386             using an unknown xmlrpc type: the error will only be written to
 387             php error log. Also <code>new xmlrpcval('true', 'boolean')</code>
 388             is not supported anymore</para>
 389           </listitem>
 390
 391           <listitem>
 392             <para>The new function
 393             <function>php_xmlrpc_decode_xml()</function> will take the xml
 394             representation of either an xmlrpc request, response or single
 395             value and return the corresponding php-xmlrpc object
 396             instance</para>
 397           </listitem>
 398
 399           <listitem>
 400             <para>A new function <function>wrap_xmlrpc_server()</function>has
 401             been added, to wrap all (or some) of the methods exposed by a
 402             remote xmlrpc server into a php class</para>
 403           </listitem>
 404
 405           <listitem>
 406             <para>A new file has been added:
 407             <filename>verify_compat.php</filename>, to help users diagnose the
 408             level of compliance of their php installation with the
 409             library</para>
 410           </listitem>
 411
 412           <listitem>
 413             <para>Restored compatibility with php 4.0.5 (for those poor souls
 414             still stuck on it)</para>
 415           </listitem>
 416
 417           <listitem>
 418             <para>Method <methodname>xmlrpc_server-&gt;service()</methodname>
 419             now returns a value: either the response payload or xmlrpcresp
 420             object instance</para>
 421           </listitem>
 422
 423           <listitem>
 424             <para>Method
 425             <methodname>xmlrpc_server-&gt;add_to_map()</methodname> now
 426             accepts xmlrpc methods with no param definitions</para>
 427           </listitem>
 428
 429           <listitem>
 430             <para>Documentation for single parameters of exposed methods can
 431             be added to the dispatch map (and turned into html docs in
 432             conjunction with a future release of the 'extras' package)</para>
 433           </listitem>
 434
 435           <listitem>
 436             <para>Full response payload is saved into xmlrpcresp object for
 437             further debugging</para>
 438           </listitem>
 439
 440           <listitem>
 441             <para>The debugger can now generate code that wraps a remote
 442             method into a php function (works for jsonrpc, too); it also has
 443             better support for being activated via a single GET call (e.g. for
 444             integration into other tools)</para>
 445           </listitem>
 446
 447           <listitem>
 448             <para>Stricter parsing of incoming xmlrpc messages: two more
 449             invalid cases are now detected (double <literal>data</literal>
 450             element inside <literal>array</literal> and
 451             <literal>struct</literal>/<literal>array</literal> after scalar
 452             inside <literal>value</literal> element)</para>
 453           </listitem>
 454
 455           <listitem>
 456             <para>More logging of errors in a lot of situations</para>
 457           </listitem>
 458
 459           <listitem>
 460             <para>Javadoc documentation of lib files (almost) complete</para>
 461           </listitem>
 462
 463           <listitem>
 464             <para>Many performance tweaks and code cleanups, plus the usual
 465             crop of bugs fixed (see NEWS file for complete list of
 466             bugs)</para>
 467           </listitem>
 468
 469           <listitem>
 470             <para>Lib internals have been modified to provide better support
 471             for grafting extra functionality on top of it. Stay tuned for
 472             future releases of the EXTRAS package (or go read Appendix
 473             B)...</para>
 474           </listitem>
 475         </itemizedlist></para>
 476     </sect1>
 477
 478     <sect1>
 479       <title>2.0 final</title>
 480
 481       <para><itemizedlist>
 482           <listitem>
 483             <para>Added to the client class the possibility to use Digest and
 484             NTLM authentication methods (when using the CURL library) for
 485             connecting to servers and NTLM for connecting to proxies</para>
 486           </listitem>
 487
 488           <listitem>
 489             <para>Added to the client class the possibility to specify
 490             alternate certificate files/directories for authenticating the
 491             peer with when using HTTPS communication</para>
 492           </listitem>
 493
 494           <listitem>
 495             <para>Reviewed all examples and added a new demo file, containing
 496             a proxy to forward xmlrpc requests to other servers (useful e.g.
 497             for ajax coding)</para>
 498           </listitem>
 499
 500           <listitem>
 501             <para>The debugger has been upgraded to reflect the new client
 502             capabilities</para>
 503           </listitem>
 504
 505           <listitem>
 506             <para>All known bugs have been squashed, and the lib is more
 507             tolerant than ever of commonly-found mistakes</para>
 508           </listitem>
 509         </itemizedlist></para>
 510     </sect1>
 511
 512     <sect1>
 513       <title>2.0 Release candidate 3</title>
 514
 515       <para><itemizedlist>
 516           <listitem>
 517             <para>Added to server class the property
 518             <property>functions_parameters_type</property>, that allows the
 519             server to register plain php functions as xmlrpc methods (i.e.
 520             functions that do not take an xmlrpcmsg object as unique
 521             param)</para>
 522           </listitem>
 523
 524           <listitem>
 525             <para>let server and client objects serialize calls using a
 526             specified character set encoding for the produced xml instead of
 527             US-ASCII (ISO-8859-1 and UTF-8 supported)</para>
 528           </listitem>
 529
 530           <listitem>
 531             <para>let php_xmlrpc_decode accept xmlrpcmsg objects as valid
 532             input</para>
 533           </listitem>
 534
 535           <listitem>
 536             <para>'class::method' syntax is now accepted in the server
 537             dispatch map</para>
 538           </listitem>
 539
 540           <listitem>
 541             <para><function>xmlrpc_clent::SetDebug()</function> accepts
 542             integer values instead of a boolean value, with debugging level 2
 543             adding to the information printed to screen the complete client
 544             request</para>
 545           </listitem>
 546         </itemizedlist></para>
 547     </sect1>
 548
 549     <sect1>
 550       <title>2.0 Release candidate 2</title>
 551
 552       <para><itemizedlist>
 553           <listitem>
 554             <para>Added a new property of the client object:
 555             <code>xmlrpc_client-&gt;return_type</code>, indicating whether
 556             calls to the send() method will return xmlrpcresp objects whose
 557             value() is an xmlrpcval object, a php value (automatically
 558             decoded) or the raw xml received from the server.</para>
 559           </listitem>
 560
 561           <listitem>
 562             <para>Added in the extras dir. two new library file:
 563             <filename>jsonrpc.inc</filename> and
 564             <filename>jsonrpcs.inc</filename> containing new classes that
 565             implement support for the json-rpc protocol (alpha quality
 566             code)</para>
 567           </listitem>
 568
 569           <listitem>
 570             <para>Added a new client method: <code>setKey($key,
 571             $keypass)</code> to be used in HTTPS connections</para>
 572           </listitem>
 573
 574           <listitem>
 575             <para>Added a new file containing some benchmarks in the testsuite
 576             directory</para>
 577           </listitem>
 578         </itemizedlist></para>
 579     </sect1>
 580
 581     <sect1>
 582       <title>2.0 Release candidate 1</title>
 583
 584       <itemizedlist>
 585         <listitem>
 586           <para>Support for HTTP proxies (new method:
 587           <code>xmlrpc_client::setProxy()</code>)</para>
 588         </listitem>
 589
 590         <listitem>
 591           <para>Support HTTP compression of both requests and responses.
 592           Clients can specify what kind of compression they accept for
 593           responses between deflate/gzip/any, and whether to compress the
 594           requests. Servers by default compress responses to clients that
 595           explicitly declare support for compression (new methods:
 596           <code>xmlrpc_client::setAcceptedCompression()</code>,
 597           <code>xmlrpc_client::setRequestCompression()</code>). Note that the
 598           ZLIB php extension needs to be enabled in PHP to support
 599           compression.</para>
 600         </listitem>
 601
 602         <listitem>
 603           <para>Implement HTTP 1.1 connections, but only if CURL is enabled
 604           (added an extra parameter to
 605           <code>xmlrpc_client::xmlrpc_client</code> to set the desired HTTP
 606           protocol at creation time and a new supported value for the last
 607           parameter of <code>xmlrpc_client::send</code>, which now can be
 608           safely omitted if it has been specified at creation time)</para>
 609
 610           <para>With PHP versions greater than 4.3.8 keep-alives are enabled
 611           by default for HTTP 1.1 connections. This should yield faster
 612           execution times when making multiple calls in sequence to the same
 613           xml-rpc server from a single client.</para>
 614         </listitem>
 615
 616         <listitem>
 617           <para>Introduce support for cookies. Cookies to be sent to the
 618           server with a request can be set using
 619           <code>xmlrpc_client::setCookie()</code>, while cookies received from
 620           the server are found in <code>xmlrpcresp::cookies()</code>. It is
 621           left to the user to check for validity of received cookies and
 622           decide whether they apply to successive calls or not.</para>
 623         </listitem>
 624
 625         <listitem>
 626           <para>Better support for detecting different character set encodings
 627           of xml-rpc requests and responses: both client and server objects
 628           will correctly detect the charset encoding of received xml, and use
 629           an appropriate xml parser.</para>
 630
 631           <para>Supported encodings are US-ASCII, UTF-8 and ISO-8859-1.</para>
 632         </listitem>
 633
 634         <listitem>
 635           <para>Added one new xmlrpcmsg constructor syntax, allowing usage of
 636           a single string with the complete URL of the target server</para>
 637         </listitem>
 638
 639         <listitem>
 640           <para>Convert xml-rpc boolean values into native php values instead
 641           of 0 and 1</para>
 642         </listitem>
 643
 644         <listitem>
 645           <para>Force the <code>php_xmlrpc_encode</code> function to properly
 646           encode numerically indexed php arrays into xml-rpc arrays
 647           (numerically indexed php arrays always start with a key of 0 and
 648           increment keys by values of 1)</para>
 649         </listitem>
 650
 651         <listitem>
 652           <para>Prevent the <code>php_xmlrpc_encode</code> function from
 653           further re-encoding any objects of class <code>xmlrpcval</code> that
 654           are passed to it. This allows to call the function with arguments
 655           consisting of mixed php values / xmlrpcval objects.</para>
 656         </listitem>
 657
 658         <listitem>
 659           <para>Allow a server to NOT respond to system.* method calls
 660           (setting the <code>$server-&gt;allow_system_funcs</code>
 661           property).</para>
 662         </listitem>
 663
 664         <listitem>
 665           <para>Implement a new xmlrpcval method to determine if a value of
 666           type struct has a member of a given name without having to loop
 667           trough all members: <code>xmlrpcval::structMemExists()</code></para>
 668         </listitem>
 669
 670         <listitem>
 671           <para>Expand methods <code>xmlrpcval::addArray</code>,
 672           <code>addScalar</code> and <code>addStruct</code> allowing extra php
 673           values to be added to xmlrpcval objects already formed.</para>
 674         </listitem>
 675
 676         <listitem>
 677           <para>Let the <code>xmlrpc_client::send</code> method accept an XML
 678           string for sending instead of an xmlrpcmsg object, to facilitate
 679           debugging and integration with the php native xmlrpc
 680           extension</para>
 681         </listitem>
 682
 683         <listitem>
 684           <para>Extend the <code>php_xmlrpc_encode</code> and
 685           <code>php_xmlrpc_decode</code> functions to allow serialization and
 686           rebuilding of PHP objects. To successfully rebuild a serialized
 687           object, the object class must be defined in the deserializing end of
 688           the transfer. Note that object members of type resource will be
 689           deserialized as NULL values.</para>
 690
 691           <para>Note that his has been implemented adding a "php_class"
 692           attribute to xml representation of xmlrpcval of STRUCT type, which,
 693           strictly speaking, breaks the xml-rpc spec. Other xmlrpc
 694           implementations are supposed to ignore such an attribute (unless
 695           they implement a brain-dead custom xml parser...), so it should be
 696           safe enabling it in heterogeneous environments. The activation of
 697           this feature is done by usage of an option passed as second
 698           parameter to both <code>php_xmlrpc_encode</code> and
 699           <code>php_xmlrpc_decode</code>.</para>
 700         </listitem>
 701
 702         <listitem>
 703           <para>Extend the <code>php_xmlrpc_encode</code> function to allow
 704           automatic serialization of iso8601-conforming php strings as
 705           datetime.iso8601 xmlrpcvals, by usage of an optional
 706           parameter</para>
 707         </listitem>
 708
 709         <listitem>
 710           <para>Added an automatic stub code generator for converting xmlrpc
 711           methods to php functions and vice-versa.</para>
 712
 713           <para>This is done via two new functions:
 714           <code>wrap_php_function</code> and <code>wrap_xmlrpc_method</code>,
 715           and has many caveats, with php being a typeless language and
 716           all...</para>
 717
 718           <para>With PHP versions lesser than 5.0.3 wrapping of php functions
 719           into xmlrpc methods is not supported yet.</para>
 720         </listitem>
 721
 722         <listitem>
 723           <para>Allow object methods to be used in server dispatch map</para>
 724         </listitem>
 725
 726         <listitem>
 727           <para>Added a complete debugger solution, in the
 728           <filename>debugger</filename> folder</para>
 729         </listitem>
 730
 731         <listitem>
 732           <para>Added configurable server-side debug messages, controlled by
 733           the new method <code>xmlrpc_server::SetDebug()</code>. At level 0,
 734           no debug messages are sent to the client; level 1 is the same as the
 735           old behaviour; at level 2 a lot more info is echoed back to the
 736           client, regarding the received call; at level 3 all warnings raised
 737           during server processing are trapped (this prevents breaking the xml
 738           to be echoed back to the client) and added to the debug info sent
 739           back to the client</para>
 740         </listitem>
 741
 742         <listitem>
 743           <para>New XML parsing code, yields smaller memory footprint and
 744           faster execution times, not to mention complete elimination of the
 745           dreaded <filename>eval()</filename> construct, so prone to code
 746           injection exploits</para>
 747         </listitem>
 748
 749         <listitem>
 750           <para>Rewritten most of the error messages, making text more
 751           explicative</para>
 752         </listitem>
 753       </itemizedlist>
 754     </sect1>
 755   </chapter>
 756
 757   <chapter id="requirements">
 758     <title>System Requirements</title>
 759
 760     <para>The library has been designed with goals of scalability and backward
 761     compatibility. As such, it supports a wide range of PHP installs. Note
 762     that not all features of the lib are available in every
 763     configuration.</para>
 764
 765     <para>The <emphasis>minimum supported</emphasis> PHP version is
 766     4.2.</para>
 767
 768     <para>A compatibility layer is provided that allows the code to run on PHP
 769     4.0.5 and 4.1. Note that if you are stuck on those platforms, we suggest
 770     you upgrade as soon as possible.</para>
 771
 772     <para>Automatic generation of xml-rpc methods from php functions is only
 773     supported with PHP version 5.0.3 and later (note that the lib will
 774     generate some warnings with PHP 5 in strict error reporting mode).</para>
 775
 776     <para>If you wish to use SSL or HTTP 1.1 to communicate with remote
 777     servers, you need the "curl" extension compiled into your PHP
 778     installation. This is available in PHP 4.0.2 and greater, although 4.0.6
 779     has a bug preventing SSL working, and versions prior to 4.3.8 do not
 780     support streamlining multiple requests using HTTP Keep-Alive.</para>
 781
 782     <para>The "xmlrpc" native extension is not required to be compiled into
 783     your PHP installation, but if it is, there will be no interference with
 784     the operation of this library.</para>
 785   </chapter>
 786
 787   <chapter id="manifest">
 788     <title>Files in the distribution</title>
 789
 790     <glosslist>
 791       <glossentry>
 792         <glossterm>lib/xmlrpc.inc</glossterm>
 793
 794         <glossdef>
 795           <para>the XML-RPC classes. <function>include()</function> this in
 796           your PHP files to use the classes.</para>
 797         </glossdef>
 798       </glossentry>
 799
 800       <glossentry>
 801         <glossterm>lib/xmlrpcs.inc</glossterm>
 802
 803         <glossdef>
 804           <para>the XML-RPC server class. <function>include()</function> this
 805           in addition to xmlrpc.inc to get server functionality</para>
 806         </glossdef>
 807       </glossentry>
 808
 809       <glossentry>
 810         <glossterm>lib/xmlrpc_wrappers.inc</glossterm>
 811
 812         <glossdef>
 813           <para>helper functions to "automagically" convert plain php
 814           functions to xmlrpc services and vice versa</para>
 815         </glossdef>
 816       </glossentry>
 817
 818       <glossentry>
 819         <glossterm>lib/compat/array_key_exists.php, lib/compat/is_a.php,
 820         lib/compat/is_scalar.php, lib/compat/var_export.php,
 821         lib/compat/vesrions_compare.php</glossterm>
 822
 823         <glossdef>
 824           <para>compatibility functions: these files implement the
 825           compatibility layer needed to run the library with PHP versions 4.0
 826           and 4.1</para>
 827         </glossdef>
 828       </glossentry>
 829
 830       <glossentry>
 831         <glossterm>demo/server/proxy.php</glossterm>
 832
 833         <glossdef>
 834           <para>a sample server implementing xmlrpc proxy
 835           functionality.</para>
 836         </glossdef>
 837       </glossentry>
 838
 839       <glossentry>
 840         <glossterm>demo/server/server.php</glossterm>
 841
 842         <glossdef>
 843           <para>a sample server hosting various demo functions, as well as a
 844           full suite of functions used for interoperability testing. It is
 845           used by testsuite.php (see below) for unit testing the library, and
 846           is not to be copied literally into your production servers</para>
 847         </glossdef>
 848       </glossentry>
 849
 850       <glossentry>
 851         <glossterm>demo/client/client.php, demo/client/agesort.php,
 852         demo/client/which.php</glossterm>
 853
 854         <glossdef>
 855           <para>client code to exercise some of the functions in server.php,
 856           including the <function>interopEchoTests.whichToolkit</function>
 857           method.</para>
 858         </glossdef>
 859       </glossentry>
 860
 861       <glossentry>
 862         <glossterm>demo/client/wrap.php</glossterm>
 863
 864         <glossdef>
 865           <para>client code to illustrate 'wrapping' of remote methods into
 866           php functions.</para>
 867         </glossdef>
 868       </glossentry>
 869
 870       <glossentry>
 871         <glossterm>demo/client/introspect.php</glossterm>
 872
 873         <glossdef>
 874           <para>client code to illustrate usage of introspection capabilities
 875           offered by server.php.</para>
 876         </glossdef>
 877       </glossentry>
 878
 879       <glossentry>
 880         <glossterm>demo/client/mail.php</glossterm>
 881
 882         <glossdef>
 883           <para>client code to illustrate usage of an xmlrpc-to-email gateway
 884           using Dave Winer's XML-RPC server at userland.com.</para>
 885         </glossdef>
 886       </glossentry>
 887
 888       <glossentry>
 889         <glossterm>demo/client/zopetest.php</glossterm>
 890
 891         <glossdef>
 892           <para>example client code that queries an xmlrpc server built in
 893           Zope.</para>
 894         </glossdef>
 895       </glossentry>
 896
 897       <glossentry>
 898         <glossterm>demo/vardemo.php</glossterm>
 899
 900         <glossdef>
 901           <para>examples of how to construct xmlrpcval types</para>
 902         </glossdef>
 903       </glossentry>
 904
 905       <glossentry>
 906         <glossterm>demo/demo1.txt, demo/demo2.txt, demo/demo3.txt</glossterm>
 907
 908         <glossdef>
 909           <para>XML-RPC responses captured in a file for testing purposes (you
 910           can use these to test the
 911           <function>xmlrpcmsg-&gt;parseResponse()</function> method).</para>
 912         </glossdef>
 913       </glossentry>
 914
 915       <glossentry>
 916         <glossterm>demo/server/discuss.php,
 917         demo/client/comment.php</glossterm>
 918
 919         <glossdef>
 920           <para>Software used in the PHP chapter of <xref
 921           linkend="jellyfish" /> to provide a comment server and allow the
 922           attachment of comments to stories from Meerkat's data store.</para>
 923         </glossdef>
 924       </glossentry>
 925
 926       <glossentry>
 927         <glossterm>test/testsuite.php, test/parse_args.php</glossterm>
 928
 929         <glossdef>
 930           <para>A unit test suite for this software package. If you do
 931           development on this software, please consider submitting tests for
 932           this suite.</para>
 933         </glossdef>
 934       </glossentry>
 935
 936       <glossentry>
 937         <glossterm>test/benchmark.php</glossterm>
 938
 939         <glossdef>
 940           <para>A (very limited) benchmarking suite for this software package.
 941           If you do development on this software, please consider submitting
 942           benchmarks for this suite.</para>
 943         </glossdef>
 944       </glossentry>
 945
 946       <glossentry>
 947         <glossterm>test/phpunit.php, test/PHPUnit/*.php</glossterm>
 948
 949         <glossdef>
 950           <para>An (incomplete) version PEAR's unit test framework for PHP.
 951           The complete package can be found at <ulink
 952           url="http://pear.php.net/package/PHPUnit">http://pear.php.net/package/PHPUnit</ulink></para>
 953         </glossdef>
 954       </glossentry>
 955
 956       <glossentry>
 957         <glossterm>test/verify_compat.php</glossterm>
 958
 959         <glossdef>
 960           <para>Script designed to help the user to verify the level of
 961           compatibility of the library with the current php install</para>
 962         </glossdef>
 963       </glossentry>
 964
 965       <glossentry>
 966         <glossterm>extras/test.pl, extras/test.py</glossterm>
 967
 968         <glossdef>
 969           <para>Perl and Python programs to exercise server.php to test that
 970           some of the methods work.</para>
 971         </glossdef>
 972       </glossentry>
 973
 974       <glossentry>
 975         <glossterm>extras/workspace.testPhpServer.fttb</glossterm>
 976
 977         <glossdef>
 978           <para>Frontier scripts to exercise the demo server. Thanks to Dave
 979           Winer for permission to include these. See <ulink
 980           url="http://www.xmlrpc.com/discuss/msgReader$853">Dave's
 981           announcement of these.</ulink></para>
 982         </glossdef>
 983       </glossentry>
 984
 985       <glossentry>
 986         <glossterm>extras/rsakey.pem</glossterm>
 987
 988         <glossdef>
 989           <para>A test certificate key for the SSL support, which can be used
 990           to generate dummy certificates. It has the passphrase "test."</para>
 991         </glossdef>
 992       </glossentry>
 993     </glosslist>
 994   </chapter>
 995
 996   <chapter id="bugs">
 997     <title>Known bugs and limitations</title>
 998
 999     <para>This started out as a bare framework. Many "nice" bits haven't been
1000     put in yet. Specifically, very little type validation or coercion has been
1001     put in. PHP being a loosely-typed language, this is going to have to be
1002     done explicitly (in other words: you can call a lot of library functions
1003     passing them arguments of the wrong type and receive an error message only
1004     much further down the code, where it will be difficult to
1005     understand).</para>
1006
1007     <para>dateTime.iso8601 is supported opaquely. It can't be done natively as
1008     the XML-RPC specification explicitly forbids passing of timezone
1009     specifiers in ISO8601 format dates. You can, however, use the <xref
1010     linkend="iso8601encode" /> and <xref linkend="iso8601decode" /> functions
1011     to do the encoding and decoding for you.</para>
1012
1013     <para>Very little HTTP response checking is performed (e.g. HTTP redirects
1014     are not followed and the Content-Length HTTP header, mandated by the
1015     xml-rpc spec, is not validated); cookie support still involves quite a bit
1016     of coding on the part of the user.</para>
1017
1018     <para>If a specific character set encoding other than US-ASCII, ISO-8859-1
1019     or UTF-8 is received in the HTTP header or XML prologue of xml-rpc request
1020     or response messages then it will be ignored for the moment, and the
1021     content will be parsed as if it had been encoded using the charset defined
1022     by <xref linkend="xmlrpc-defencoding" /></para>
1023
1024     <para>Very large floating point numbers are serialized using exponential
1025     notation, even though the spec explicitly forbids this behaviour. This
1026     will not be a problem if this library is used on both ends of the
1027     communication, but might cause problems with other implementations.</para>
1028
1029     <para>Support for receiving from servers version 1 cookies (i.e.
1030     conforming to RFC 2965) is quite incomplete, and might cause unforeseen
1031     errors.</para>
1032
1033     <para>A PHP warning will be generated in many places when using
1034     <filename>xmlrpc.inc</filename> and <filename>xmlrpcs.inc</filename> with
1035     PHP 5 in strict error reporting mode. The simplest workaround to this
1036     problem is to lower the <parameter>error_reporting</parameter> level in
1037     php.ini.</para>
1038   </chapter>
1039
1040   <chapter id="support">
1041     <title>Support</title>
1042
1043     <sect1>
1044       <title>Online Support</title>
1045
1046       <para>XML-RPC for PHP is offered "as-is" without any warranty or
1047       commitment to support. However, informal advice and help is available
1048       via the XML-RPC for PHP website and mailing list and from
1049       XML-RPC.com.</para>
1050
1051       <itemizedlist>
1052         <listitem>
1053           <para>The <emphasis>XML-RPC for PHP</emphasis> development is hosted
1054           on <ulink
1055           url="http://phpxmlrpc.sourceforge.net">phpxmlrpc.sourceforge.net</ulink>.
1056           Bugs, feature requests and patches can be posted to the <ulink
1057           url="http://sourceforge.net/projects/phpxmlrpc">project's
1058           website</ulink>.</para>
1059         </listitem>
1060
1061         <listitem>
1062           <para>The <emphasis>PHP XML-RPC interest mailing list</emphasis> is
1063           run by the author. More details <ulink
1064           url="http://lists.gnomehack.com/mailman/listinfo/phpxmlrpc">can be
1065           found here</ulink>.</para>
1066         </listitem>
1067
1068         <listitem>
1069           <para>For more general XML-RPC questions, there is a Yahoo! Groups
1070           <ulink url="http://groups.yahoo.com/group/xml-rpc/">XML-RPC mailing
1071           list</ulink>.</para>
1072         </listitem>
1073
1074         <listitem>
1075           <para>The <ulink
1076           url="http://www.xmlrpc.com/discuss">XML-RPC.com</ulink> discussion
1077           group is a useful place to get help with using XML-RPC. This group
1078           is also gatewayed into the Yahoo! Groups mailing list.</para>
1079         </listitem>
1080       </itemizedlist>
1081     </sect1>
1082
1083     <sect1 id="jellyfish" xreflabel="The Jellyfish Book">
1084       <title>The Jellyfish Book</title>
1085
1086       <para><graphic align="right" depth="190" fileref="progxmlrpc.s.gif"
1087       format="GIF" width="145" />Together with Simon St.Laurent and Joe
1088       Johnston, Edd Dumbill wrote a book on XML-RPC for O'Reilly and
1089       Associates on XML-RPC. It features a rather fetching jellyfish on the
1090       cover.</para>
1091
1092       <para>Complete details of the book are <ulink
1093       url="http://www.oreilly.com/catalog/progxmlrpc/">available from
1094       O'Reilly's web site.</ulink></para>
1095
1096       <para>Edd is responsible for the chapter on PHP, which includes a worked
1097       example of creating a forum server, and hooking it up the O'Reilly's
1098       <ulink url="http://meerkat.oreillynet.com/">Meerkat</ulink> service in
1099       order to allow commenting on news stories from around the Web.</para>
1100
1101       <para>If you've benefited from the effort that has been put into writing
1102       this software, then please consider buying the book!</para>
1103     </sect1>
1104   </chapter>
1105
1106   <chapter id="apidocs">
1107     <title>Class documentation</title>
1108
1109     <sect1 id="xmlrpcval" xreflabel="xmlrpcval">
1110       <title>xmlrpcval</title>
1111
1112       <para>This is where a lot of the hard work gets done. This class enables
1113       the creation and encapsulation of values for XML-RPC.</para>
1114
1115       <para>Ensure you've read the XML-RPC spec at <ulink
1116       url="http://www.xmlrpc.com/stories/storyReader$7">http://www.xmlrpc.com/stories/storyReader$7</ulink>
1117       before reading on as it will make things clearer.</para>
1118
1119       <para>The <classname>xmlrpcval</classname> class can store arbitrarily
1120       complicated values using the following types: <literal>i4 int boolean
1121       string double dateTime.iso8601 base64 array struct</literal>. You should
1122       refer to the <ulink url="http://www.xmlrpc.com/spec">spec</ulink> for
1123       more information on what each of these types mean.</para>
1124
1125       <sect2>
1126         <title>Notes on types</title>
1127
1128         <sect3>
1129           <title>int</title>
1130
1131           <para>The type <classname>i4</classname> is accepted as a synonym
1132           for <classname>int</classname> when creating xmlrpcval objects. The
1133           xml parsing code will always convert <classname>i4</classname> to
1134           <classname>int</classname>: <classname>int</classname> is regarded
1135           by this implementation as the canonical name for this type.</para>
1136         </sect3>
1137
1138         <sect3>
1139           <title>base64</title>
1140
1141           <para>Base 64 encoding is performed transparently to the caller when
1142           using this type. Decoding is also transparent. Therefore you ought
1143           to consider it as a "binary" data type, for use when you want to
1144           pass data that is not 7-bit clean.</para>
1145         </sect3>
1146
1147         <sect3>
1148           <title>boolean</title>
1149
1150           <para>The php values <literal>true</literal> and
1151           <literal>1</literal> map to <literal>true</literal>. All other
1152           values (including the empty string) are converted to
1153           <literal>false</literal>.</para>
1154         </sect3>
1155
1156         <sect3>
1157           <title>string</title>
1158
1159           <para>Characters &lt;, &gt;, ', ", &amp;, are encoded using their
1160           entity reference as &amp;lt; &amp;gt; &amp;apos; &amp;quot; and
1161           &amp;amp; All other characters outside of the ASCII range are
1162           encoded using their character reference representation (e.g.
1163           &amp;#200 for é). The XML-RPC spec recommends only encoding
1164           <literal>&lt; &amp;</literal> but this implementation goes further,
1165           for reasons explained by <ulink
1166           url="http://www.w3.org/TR/REC-xml#syntax">the XML 1.0
1167           recommendation</ulink>. In particular, using character reference
1168           representation has the advantage of producing XML that is valid
1169           independently of the charset encoding assumed.</para>
1170         </sect3>
1171       </sect2>
1172
1173       <sect2 id="xmlrpcval-creation" xreflabel="xmlrpcval constructors">
1174         <title>Creation</title>
1175
1176         <para>The constructor is the normal way to create an
1177         <classname>xmlrpcval</classname>. The constructor can take these
1178         forms:</para>
1179
1180         <funcsynopsis>
1181           <funcprototype>
1182             <funcdef><type>xmlrpcval</type>new
1183             <function>xmlrpcval</function></funcdef>
1184
1185             <void />
1186           </funcprototype>
1187
1188           <funcprototype>
1189             <funcdef><type>xmlrpcval</type>new
1190             <function>xmlrpcval</function></funcdef>
1191
1192             <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
1193           </funcprototype>
1194
1195           <funcprototype>
1196             <funcdef><type>xmlrpcval</type>new
1197             <function>xmlrpcval</function></funcdef>
1198
1199             <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
1200
1201             <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
1202           </funcprototype>
1203
1204           <funcprototype>
1205             <funcdef><type>xmlrpcval</type>new
1206             <function>xmlrpcval</function></funcdef>
1207
1208             <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
1209
1210             <paramdef><type>string</type><parameter>$arraytyp</parameter></paramdef>
1211           </funcprototype>
1212         </funcsynopsis>
1213
1214         <para>The first constructor creates an empty value, which must be
1215         altered using the methods <function>addScalar</function>,
1216         <function>addArray</function> or <function>addStruct</function> before
1217         it can be used.</para>
1218
1219         <para>The second constructor creates a simple string value.</para>
1220
1221         <para>The third constructor is used to create a scalar value. The
1222         second parameter must be a name of an XML-RPC type. Valid types are:
1223         "<literal>int</literal>", "<literal>boolean</literal>",
1224         "<literal>string</literal>", "<literal>double</literal>",
1225         "<literal>dateTime.iso8601</literal>",
1226         "<literal>base64</literal>".</para>
1227
1228         <para>Examples:</para>
1229
1230         <programlisting language="php">
1231 $myInt = new xmlrpcvalue(1267, "int");
1232 $myString = new xmlrpcvalue("Hello, World!", "string");
1233 $myBool = new xmlrpcvalue(1, "boolean");
1234 $myString2 = new xmlrpcvalue(1.24, "string"); // note: this will serialize a php float value as xmlrpc string
1235 </programlisting>
1236
1237         <para>The fourth constructor form can be used to compose complex
1238         XML-RPC values. The first argument is either a simple array in the
1239         case of an XML-RPC <classname>array</classname> or an associative
1240         array in the case of a <classname>struct</classname>. The elements of
1241         the array <emphasis>must be <classname>xmlrpcval</classname> objects
1242         themselves</emphasis>.</para>
1243
1244         <para>The second parameter must be either "<literal>array</literal>"
1245         or "<literal>struct</literal>".</para>
1246
1247         <para>Examples:</para>
1248
1249         <programlisting language="php">
1250 $myArray = new xmlrpcval(
1251   array(
1252     new xmlrpcval("Tom"),
1253     new xmlrpcval("Dick"),
1254     new xmlrpcval("Harry")
1255   ),
1256   "array");
1257
1258 // recursive struct
1259 $myStruct = new xmlrpcval(
1260   array(
1261     "name" =&gt; new xmlrpcval("Tom", "string"),
1262     "age" =&gt; new xmlrpcval(34, "int"),
1263     "address" =&gt; new xmlrpcval(
1264       array(
1265         "street" =&gt; new xmlrpcval("Fifht Ave", "string"),
1266         "city" =&gt; new xmlrpcval("NY", "string")
1267       ),
1268       "struct")
1269   ),
1270   "struct");
1271 </programlisting>
1272
1273         <para>See the file <literal>vardemo.php</literal> in this distribution
1274         for more examples.</para>
1275       </sect2>
1276
1277       <sect2 id="xmlrpcval-methods" xreflabel="xmlrpcval methods">
1278         <title>Methods</title>
1279
1280         <sect3>
1281           <title>addScalar</title>
1282
1283           <funcsynopsis>
1284             <funcprototype>
1285               <funcdef><type>int</type><function>addScalar</function></funcdef>
1286
1287               <paramdef><type>string</type><parameter>$stringVal</parameter></paramdef>
1288             </funcprototype>
1289
1290             <funcprototype>
1291               <funcdef><type>int</type><function>addScalar</function></funcdef>
1292
1293               <paramdef><type>mixed</type><parameter>$scalarVal</parameter></paramdef>
1294
1295               <paramdef><type>string</type><parameter>$scalartyp</parameter></paramdef>
1296             </funcprototype>
1297           </funcsynopsis>
1298
1299           <para>If <parameter>$val</parameter> is an empty
1300           <classname>xmlrpcval</classname> this method makes it a scalar
1301           value, and sets that value.</para>
1302
1303           <para>If <parameter>$val</parameter> is already a scalar value, then
1304           no more scalars can be added and <literal>0</literal> is
1305           returned.</para>
1306
1307           <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
1308           the php value <parameter>$scalarval</parameter> is added as its last
1309           element.</para>
1310
1311           <para>If all went OK, <literal>1</literal> is returned, otherwise
1312           <literal>0</literal>.</para>
1313         </sect3>
1314
1315         <sect3>
1316           <title>addArray</title>
1317
1318           <funcsynopsis>
1319             <funcprototype>
1320               <funcdef><type>int</type><function>addArray</function></funcdef>
1321
1322               <paramdef><type>array</type><parameter>$arrayVal</parameter></paramdef>
1323             </funcprototype>
1324           </funcsynopsis>
1325
1326           <para>The argument is a simple (numerically indexed) array. The
1327           elements of the array <emphasis>must be
1328           <classname>xmlrpcval</classname> objects
1329           themselves</emphasis>.</para>
1330
1331           <para>Turns an empty <classname>xmlrpcval</classname> into an
1332           <classname>array</classname> with contents as specified by
1333           <parameter>$arrayVal</parameter>.</para>
1334
1335           <para>If <parameter>$val</parameter> is an xmlrpcval of type array,
1336           the elements of <parameter>$arrayVal</parameter> are appended to the
1337           existing ones.</para>
1338
1339           <para>See the fourth constructor form for more information.</para>
1340
1341           <para>If all went OK, <literal>1</literal> is returned, otherwise
1342           <literal>0</literal>.</para>
1343         </sect3>
1344
1345         <sect3>
1346           <title>addStruct</title>
1347
1348           <funcsynopsis>
1349             <funcprototype>
1350               <funcdef><type>int</type><function>addStruct</function></funcdef>
1351
1352               <paramdef><type>array</type><parameter>$assocArrayVal</parameter></paramdef>
1353             </funcprototype>
1354           </funcsynopsis>
1355
1356           <para>The argument is an associative array. The elements of the
1357           array <emphasis>must be <classname>xmlrpcval</classname> objects
1358           themselves</emphasis>.</para>
1359
1360           <para>Turns an empty <classname>xmlrpcval</classname> into a
1361           <classname>struct</classname> with contents as specified by
1362           <parameter>$assocArrayVal</parameter>.</para>
1363
1364           <para>If <parameter>$val</parameter> is an xmlrpcval of type struct,
1365           the elements of <parameter>$arrayVal</parameter> are merged with the
1366           existing ones.</para>
1367
1368           <para>See the fourth constructor form for more information.</para>
1369
1370           <para>If all went OK, <literal>1</literal> is returned, otherwise
1371           <literal>0</literal>.</para>
1372         </sect3>
1373
1374         <sect3>
1375           <title>kindOf</title>
1376
1377           <funcsynopsis>
1378             <funcprototype>
1379               <funcdef><type>string</type><function>kindOf</function></funcdef>
1380
1381               <void />
1382             </funcprototype>
1383           </funcsynopsis>
1384
1385           <para>Returns a string containing "struct", "array" or "scalar"
1386           describing the base type of the value. If it returns "undef" it
1387           means that the value hasn't been initialised.</para>
1388         </sect3>
1389
1390         <sect3>
1391           <title>serialize</title>
1392
1393           <funcsynopsis>
1394             <funcprototype>
1395               <funcdef><type>string</type><function>serialize</function></funcdef>
1396
1397               <void />
1398             </funcprototype>
1399           </funcsynopsis>
1400
1401           <para>Returns a string containing the XML-RPC representation of this
1402           value.</para>
1403         </sect3>
1404
1405         <sect3>
1406           <title>scalarVal</title>
1407
1408           <funcsynopsis>
1409             <funcprototype>
1410               <funcdef><type>mixed</type><function>scalarVal</function></funcdef>
1411
1412               <void />
1413             </funcprototype>
1414           </funcsynopsis>
1415
1416           <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
1417           method returns the actual PHP-language value of the scalar (base 64
1418           decoding is automatically handled here).</para>
1419         </sect3>
1420
1421         <sect3>
1422           <title>scalarTyp</title>
1423
1424           <funcsynopsis>
1425             <funcprototype>
1426               <funcdef><type>string</type><function>scalarTyp</function></funcdef>
1427
1428               <void />
1429             </funcprototype>
1430           </funcsynopsis>
1431
1432           <para>If <function>$val-&gt;kindOf() == "scalar"</function>, this
1433           method returns a string denoting the type of the scalar. As
1434           mentioned before, <literal>i4</literal> is always coerced to
1435           <literal>int</literal>.</para>
1436         </sect3>
1437
1438         <sect3>
1439           <title>arrayMem</title>
1440
1441           <funcsynopsis>
1442             <funcprototype>
1443               <funcdef><type>xmlrpcval</type><function>arrayMem</function></funcdef>
1444
1445               <paramdef><type>int</type><parameter>$n</parameter></paramdef>
1446             </funcprototype>
1447           </funcsynopsis>
1448
1449           <para>If <function>$val-&gt;kindOf() == "array"</function>, returns
1450           the <parameter>$n</parameter>th element in the array represented by
1451           the value <parameter>$val</parameter>. The value returned is an
1452           <classname>xmlrpcval</classname> object.</para>
1453
1454           <para><programlisting language="php">
1455 // iterating over values of an array object
1456 for ($i = 0; $i &lt; $val-&gt;arraySize(); $i++)
1457 {
1458   $v = $val-&gt;arrayMem($i);
1459   echo "Element $i of the array is of type ".$v-&gt;kindOf();
1460 }
1461 </programlisting></para>
1462         </sect3>
1463
1464         <sect3>
1465           <title>arraySize</title>
1466
1467           <funcsynopsis>
1468             <funcprototype>
1469               <funcdef><type>int</type><function>arraySize</function></funcdef>
1470
1471               <void />
1472             </funcprototype>
1473           </funcsynopsis>
1474
1475           <para>If <parameter>$val</parameter> is an
1476           <classname>array</classname>, returns the number of elements in that
1477           array.</para>
1478         </sect3>
1479
1480         <sect3>
1481           <title>structMem</title>
1482
1483           <funcsynopsis>
1484             <funcprototype>
1485               <funcdef><type>xmlrpcval</type><function>structMem</function></funcdef>
1486
1487               <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
1488             </funcprototype>
1489           </funcsynopsis>
1490
1491           <para>If <function>$val-&gt;kindOf() == "struct"</function>, returns
1492           the element called <parameter>$memberName</parameter> from the
1493           struct represented by the value <parameter>$val</parameter>. The
1494           value returned is an <classname>xmlrpcval</classname> object.</para>
1495         </sect3>
1496
1497         <sect3>
1498           <title>structEach</title>
1499
1500           <funcsynopsis>
1501             <funcprototype>
1502               <funcdef><type>array</type><function>structEach</function></funcdef>
1503
1504               <void />
1505             </funcprototype>
1506           </funcsynopsis>
1507
1508           <para>Returns the next (key, value) pair from the struct, when
1509           <parameter>$val</parameter> is a struct.
1510           <parameter>$value</parameter> is an xmlrpcval itself. See also <xref
1511           linkend="structreset" />.</para>
1512
1513           <para><programlisting language="php">
1514 // iterating over all values of a struct object
1515 $val-&gt;structreset();
1516 while (list($key, $v) = $val-&gt;structEach())
1517 {
1518   echo "Element $key of the struct is of type ".$v-&gt;kindOf();
1519 }
1520 </programlisting></para>
1521         </sect3>
1522
1523         <sect3 id="structreset" xreflabel="structreset()">
1524           <title>structReset</title>
1525
1526           <funcsynopsis>
1527             <funcprototype>
1528               <funcdef><type>void</type><function>structReset</function></funcdef>
1529
1530               <void />
1531             </funcprototype>
1532           </funcsynopsis>
1533
1534           <para>Resets the internal pointer for
1535           <function>structEach()</function> to the beginning of the struct,
1536           where <parameter>$val</parameter> is a struct.</para>
1537         </sect3>
1538
1539         <sect3 id="structmemexists" xreflabel="structmemexists()">
1540           <title>structMemExists</title>
1541
1542           <funcsynopsis>
1543             <funcprototype>
1544               <funcdef><type>bool</type><function>structMemExsists</function></funcdef>
1545
1546               <paramdef><type>string</type><parameter>$memberName</parameter></paramdef>
1547             </funcprototype>
1548           </funcsynopsis>
1549
1550           <para>Returns <constant>TRUE</constant> or
1551           <constant>FALSE</constant> depending on whether a member of the
1552           given name exists in the struct.</para>
1553         </sect3>
1554       </sect2>
1555     </sect1>
1556
1557     <sect1 id="xmlrpcmsg" xreflabel="xmlrpcmsg">
1558       <title>xmlrpcmsg</title>
1559
1560       <para>This class provides a representation for a request to an XML-RPC
1561       server. A client sends an <classname>xmlrpcmsg</classname> to a server,
1562       and receives back an <classname>xmlrpcresp</classname> (see <xref
1563       linkend="xmlrpc-client-send" />).</para>
1564
1565       <sect2>
1566         <title>Creation</title>
1567
1568         <para>The constructor takes the following forms:</para>
1569
1570         <funcsynopsis>
1571           <funcprototype>
1572             <funcdef><type>xmlrpcmsg</type>new
1573             <function>xmlrpcmsg</function></funcdef>
1574
1575             <paramdef><type>string</type><parameter>$methodName</parameter></paramdef>
1576
1577             <paramdef><type>array</type><parameter>$parameterArray</parameter><initializer>null</initializer></paramdef>
1578           </funcprototype>
1579         </funcsynopsis>
1580
1581         <para>Where <parameter>methodName</parameter> is a string indicating
1582         the name of the method you wish to invoke, and
1583         <parameter>parameterArray</parameter> is a simple php
1584         <classname>Array</classname> of <classname>xmlrpcval</classname>
1585         objects. Here's an example message to the <emphasis>US state
1586         name</emphasis> server:</para>
1587
1588         <programlisting language="php">
1589 $msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
1590 </programlisting>
1591
1592         <para>This example requests the name of state number 23. For more
1593         information on <classname>xmlrpcval</classname> objects, see <xref
1594         linkend="xmlrpcval" />.</para>
1595
1596         <para>Note that the <parameter>parameterArray</parameter> parameter is
1597         optional and can be omitted for methods that take no input parameters
1598         or if you plan to add parameters one by one.</para>
1599       </sect2>
1600
1601       <sect2>
1602         <title>Methods</title>
1603
1604         <sect3>
1605           <title>addParam</title>
1606
1607           <funcsynopsis>
1608             <funcprototype>
1609               <funcdef><type>bool</type><function>addParam</function></funcdef>
1610
1611               <paramdef><type>xmlrpcval</type><parameter>$xmlrpcVal</parameter></paramdef>
1612             </funcprototype>
1613           </funcsynopsis>
1614
1615           <para>Adds the <classname>xmlrpcval</classname>
1616           <parameter>xmlrpcVal</parameter> to the parameter list for this
1617           method call. Returns TRUE or FALSE on error.</para>
1618         </sect3>
1619
1620         <sect3>
1621           <title>getNumParams</title>
1622
1623           <funcsynopsis>
1624             <funcprototype>
1625               <funcdef><type>int</type><function>getNumParams</function></funcdef>
1626
1627               <void />
1628             </funcprototype>
1629           </funcsynopsis>
1630
1631           <para>Returns the number of parameters attached to this
1632           message.</para>
1633         </sect3>
1634
1635         <sect3>
1636           <title>getParam</title>
1637
1638           <funcsynopsis>
1639             <funcprototype>
1640               <funcdef><type>xmlrpcval</type><function>getParam</function></funcdef>
1641
1642               <paramdef><type>int</type><parameter>$n</parameter></paramdef>
1643             </funcprototype>
1644           </funcsynopsis>
1645
1646           <para>Gets the <parameter>n</parameter>th parameter in the message
1647           (with the index zero-based). Use this method in server
1648           implementations to retrieve the values sent by the client.</para>
1649         </sect3>
1650
1651         <sect3>
1652           <title>method</title>
1653
1654           <funcsynopsis>
1655             <funcprototype>
1656               <funcdef><type>string</type><function>method</function></funcdef>
1657
1658               <void />
1659             </funcprototype>
1660
1661             <funcprototype>
1662               <funcdef><type>string</type><function>method</function></funcdef>
1663
1664               <paramdef><type>string</type><parameter>$methName</parameter></paramdef>
1665             </funcprototype>
1666           </funcsynopsis>
1667
1668           <para>Gets or sets the method contained in the XML-RPC
1669           message.</para>
1670         </sect3>
1671
1672         <sect3>
1673           <title>parseResponse</title>
1674
1675           <funcsynopsis>
1676             <funcprototype>
1677               <funcdef><type>xmlrpcresp</type><function>parseResponse</function></funcdef>
1678
1679               <paramdef><type>string</type><parameter>$xmlString</parameter></paramdef>
1680             </funcprototype>
1681           </funcsynopsis>
1682
1683           <para>Given an incoming XML-RPC server response contained in the
1684           string <parameter>$xmlString</parameter>, this method constructs an
1685           <classname>xmlrpcresp</classname> response object and returns it,
1686           setting error codes as appropriate (see <xref
1687           linkend="xmlrpc-client-send" />).</para>
1688
1689           <para>This method processes any HTTP/MIME headers it finds.</para>
1690         </sect3>
1691
1692         <sect3>
1693           <title>parseResponseFile</title>
1694
1695           <funcsynopsis>
1696             <funcprototype>
1697               <funcdef><type>xmlrpcresp</type><function>parseResponseFile</function></funcdef>
1698
1699               <paramdef><type>file handle
1700               resource</type><parameter>$fileHandle</parameter></paramdef>
1701             </funcprototype>
1702           </funcsynopsis>
1703
1704           <para>Given an incoming XML-RPC server response on the open file
1705           handle <parameter>fileHandle</parameter>, this method reads all the
1706           data it finds and passes it to
1707           <function>parseResponse.</function></para>
1708
1709           <para>This method is useful to construct responses from pre-prepared
1710           files (see files <literal>demo1.txt, demo2.txt, demo3.txt</literal>
1711           in this distribution). It processes any HTTP headers it finds, and
1712           does not close the file handle.</para>
1713         </sect3>
1714
1715         <sect3>
1716           <title>serialize</title>
1717
1718           <funcsynopsis>
1719             <funcprototype>
1720               <funcdef><type>string
1721               </type><function>serialize</function></funcdef>
1722
1723               <void />
1724             </funcprototype>
1725           </funcsynopsis>
1726
1727           <para>Returns the an XML string representing the XML-RPC
1728           message.</para>
1729         </sect3>
1730       </sect2>
1731     </sect1>
1732
1733     <sect1 id="xmlrpc-client" xreflabel="xmlrpc_client">
1734       <title>xmlrpc_client</title>
1735
1736       <para>This is the basic class used to represent a client of an XML-RPC
1737       server.</para>
1738
1739       <sect2>
1740         <title>Creation</title>
1741
1742         <para>The constructor accepts one of two possible syntaxes:</para>
1743
1744         <funcsynopsis>
1745           <funcprototype>
1746             <funcdef><type>xmlrpc_client</type>new
1747             <function>xmlrpc_client</function></funcdef>
1748
1749             <paramdef><type>string</type><parameter>$server_url</parameter></paramdef>
1750           </funcprototype>
1751
1752           <funcprototype>
1753             <funcdef><type>xmlrpc_client</type>new
1754             <function>xmlrpc_client</function></funcdef>
1755
1756             <paramdef><type>string</type><parameter>$server_path</parameter></paramdef>
1757
1758             <paramdef><type>string</type><parameter>$server_hostname</parameter></paramdef>
1759
1760             <paramdef><type>int</type><parameter>$server_port</parameter><initializer>80</initializer></paramdef>
1761
1762             <paramdef><type>string</type><parameter>$transport</parameter><initializer>'http'</initializer></paramdef>
1763           </funcprototype>
1764         </funcsynopsis>
1765
1766         <para>Here are a couple of usage examples of the first form:</para>
1767
1768         <programlisting language="php">
1769 $client = new xmlrpc_client("http://phpxmlrpc.sourceforge.net/server.php");
1770 $another_client = new xmlrpc_client("https://james:bond@secret.service.com:4443/xmlrpcserver?agent=007");
1771 </programlisting>
1772
1773         <para>The second syntax does not allow to express a username and
1774         password to be used for basic HTTP authorization as in the second
1775         example above, but instead it allows to choose whether xmlrpc calls
1776         will be made using the HTTP 1.0 or 1.1 protocol.</para>
1777
1778         <para>Here's another example client set up to query Userland's XML-RPC
1779         server at <emphasis>betty.userland.com</emphasis>:</para>
1780
1781         <programlisting language="php">
1782 $client = new xmlrpc_client("/RPC2", "betty.userland.com", 80);
1783 </programlisting>
1784
1785         <para>The <parameter>server_port</parameter> parameter is optional,
1786         and if omitted will default to 80 when using HTTP and 443 when using
1787         HTTPS (see the <xref linkend="xmlrpc-client-send" /> method
1788         below).</para>
1789
1790         <para>The <parameter>transport</parameter> parameter is optional, and
1791         if omitted will default to 'http'. Allowed values are either
1792         '<symbol>http'</symbol>, '<symbol>https</symbol>' or
1793         '<symbol>http11'</symbol>. Its value can be overridden with every call
1794         to the <methodname>send</methodname> method. See the
1795         <methodname>send</methodname> method below for more details about the
1796         meaning of the different values.</para>
1797       </sect2>
1798
1799       <sect2>
1800         <title>Methods</title>
1801
1802         <para>This class supports the following methods.</para>
1803
1804         <sect3 id="xmlrpc-client-send" xreflabel="xmlrpc_client-&gt;send">
1805           <title>send</title>
1806
1807           <para>This method takes the forms:</para>
1808
1809           <funcsynopsis>
1810             <funcprototype>
1811               <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
1812
1813               <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpc_message</parameter></paramdef>
1814
1815               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1816
1817               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1818             </funcprototype>
1819
1820             <funcprototype>
1821               <funcdef><type>array</type><function>send</function></funcdef>
1822
1823               <paramdef><type>array</type><parameter>$xmlrpc_messages</parameter></paramdef>
1824
1825               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1826
1827               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1828             </funcprototype>
1829
1830             <funcprototype>
1831               <funcdef><type>xmlrpcresp</type><function>send</function></funcdef>
1832
1833               <paramdef><type>string</type><parameter>$xml_payload</parameter></paramdef>
1834
1835               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1836
1837               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1838             </funcprototype>
1839           </funcsynopsis>
1840
1841           <para>Where <parameter>xmlrpc_message</parameter> is an instance of
1842           <classname>xmlrpcmsg</classname> (see <xref linkend="xmlrpcmsg" />),
1843           and <parameter>response</parameter> is an instance of
1844           <classname>xmlrpcresp</classname> (see <xref
1845           linkend="xmlrpcresp" />).</para>
1846
1847           <para><parameter>If xmlrpc_messages</parameter> is an array of
1848           message instances, <code>responses</code> will be an array of
1849           response instances. The client will try to make use of a single
1850           <code>system.multicall</code> xml-rpc method call to forward to the
1851           server all the messages in a single HTTP round trip, unless
1852           <code>$client-&gt;no_multicall</code> has been previously set to
1853           <code>TRUE</code> (see the multicall method below), in which case
1854           many consecutive xmlrpc requests will be sent.</para>
1855
1856           <para>The third syntax allows to build by hand (or any other means)
1857           a complete xmlrpc request message, and send it to the server.
1858           <parameter>xml_payload</parameter> should be a string containing the
1859           complete xml representation of the request. It is e.g. useful when,
1860           for maximal speed of execution, the request is serialized into a
1861           string using the native php xmlrpc functions (see <ulink
1862           url="http://www.php.net/xmlrpc">the php manual on
1863           xmlrpc</ulink>).</para>
1864
1865           <para>The <parameter>timeout</parameter> is optional, and will be
1866           set to <literal>0</literal> (wait for platform-specific predefined
1867           timeout) if omitted. This timeout value is passed to
1868           <function>fsockopen()</function>. It is also used for detecting
1869           server timeouts during communication (i.e. if the server does not
1870           send anything to the client for <parameter>timeout</parameter>
1871           seconds, the connection will be closed).</para>
1872
1873           <para>The <parameter>transport</parameter> parameter is optional,
1874           and if omitted will default to the transport set using instance
1875           creator or 'http' if omitted. The only other valid values are
1876           'https', which will use an SSL HTTP connection to connect to the
1877           remote server, and 'http11'. Note that your PHP must have the "curl"
1878           extension compiled in order to use both these features. Note that
1879           when using SSL you should normally set your port number to 443,
1880           unless the SSL server you are contacting runs at any other
1881           port.</para>
1882
1883           <warning>
1884             <para>PHP 4.0.6 has a bug which prevents SSL working.</para>
1885           </warning>
1886
1887           <para>In addition to low-level errors, the XML-RPC server you were
1888           querying may return an error in the
1889           <classname>xmlrpcresp</classname> object. See <xref
1890           linkend="xmlrpcresp" /> for details of how to handle these
1891           errors.</para>
1892         </sect3>
1893
1894         <sect3 id="multicall" xreflabel="xmlrpc_client-&gt;multicall">
1895           <title>multiCall</title>
1896
1897           <para>This method takes the form:</para>
1898
1899           <funcsynopsis>
1900             <funcprototype>
1901               <funcdef><type>array</type><function>multiCall</function></funcdef>
1902
1903               <paramdef><type>array</type><parameter>$messages</parameter></paramdef>
1904
1905               <paramdef><type>int</type><parameter>$timeout</parameter></paramdef>
1906
1907               <paramdef><type>string</type><parameter>$transport</parameter></paramdef>
1908
1909               <paramdef><type>bool</type><parameter>$fallback</parameter></paramdef>
1910             </funcprototype>
1911           </funcsynopsis>
1912
1913           <para>This method is used to boxcar many method calls in a single
1914           xml-rpc request. It will try first to make use of the
1915           <code>system.multicall</code> xml-rpc method call, and fall back to
1916           executing many separate requests if the server returns any
1917           error.</para>
1918
1919           <para><parameter>msgs</parameter> is an array of
1920           <classname>xmlrpcmsg</classname> objects (see <xref
1921           linkend="xmlrpcmsg" />), and <parameter>response</parameter> is an
1922           array of <classname>xmlrpcresp</classname> objects (see <xref
1923           linkend="xmlrpcresp" />).</para>
1924
1925           <para>The <parameter>timeout</parameter> and
1926           <parameter>transport</parameter> parameters are optional, and behave
1927           as in the <methodname>send</methodname> method above.</para>
1928
1929           <para>The <parameter>fallback</parameter> parameter is optional, and
1930           defaults to <constant>TRUE</constant>. When set to
1931           <constant>FALSE</constant> it will prevent the client to try using
1932           many single method calls in case of failure of the first multicall
1933           request. It should be set only when the server is known to support
1934           the multicall extension.</para>
1935         </sect3>
1936
1937         <sect3>
1938           <title>setAcceptedCompression</title>
1939
1940           <funcsynopsis>
1941             <funcprototype>
1942               <funcdef><type>void</type><function>setAcceptedCompression</function></funcdef>
1943
1944               <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
1945             </funcprototype>
1946           </funcsynopsis>
1947
1948           <para>This method defines whether the client will accept compressed
1949           xml payload forming the bodies of the xmlrpc responses received from
1950           servers. Note that enabling reception of compressed responses merely
1951           adds some standard http headers to xmlrpc requests. It is up to the
1952           xmlrpc server to return compressed responses when receiving such
1953           requests. Allowed values for
1954           <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
1955           'any' or null (with any meaning either gzip or deflate).</para>
1956
1957           <para>This requires the "zlib" extension to be enabled in your php
1958           install. If it is, by default <classname>xmlrpc_client</classname>
1959           instances will enable reception of compressed content.</para>
1960         </sect3>
1961
1962         <sect3>
1963           <title>setCaCertificate</title>
1964
1965           <funcsynopsis>
1966             <funcprototype>
1967               <funcdef><type>void</type><function>setCaCertificate</function></funcdef>
1968
1969               <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
1970
1971               <paramdef><type>bool</type><parameter>$is_dir</parameter></paramdef>
1972             </funcprototype>
1973           </funcsynopsis>
1974
1975           <para>This method sets an optional certificate to be used in
1976           SSL-enabled communication to validate a remote server with (when the
1977           <parameter>server_method</parameter> is set to 'https' in the
1978           client's construction or in the send method and
1979           <methodname>SetSSLVerifypeer</methodname> has been set to
1980           <constant>TRUE</constant>).</para>
1981
1982           <para>The <parameter>certificate</parameter> parameter must be the
1983           filename of a PEM formatted certificate, or a directory containing
1984           multiple certificate files. The <parameter>is_dir</parameter>
1985           parameter defaults to <constant>FALSE</constant>, set it to
1986           <constant>TRUE</constant> to specify that
1987           <parameter>certificate</parameter> indicates a directory instead of
1988           a single file.</para>
1989
1990           <para>This requires the "curl" extension to be compiled into your
1991           installation of PHP. For more details see the man page for the
1992           <function>curl_setopt</function> function.</para>
1993         </sect3>
1994
1995         <sect3>
1996           <title>setCertificate</title>
1997
1998           <funcsynopsis>
1999             <funcprototype>
2000               <funcdef><type>void</type><function>setCertificate</function></funcdef>
2001
2002               <paramdef><type>string</type><parameter>$certificate</parameter></paramdef>
2003
2004               <paramdef><type>string</type><parameter>$passphrase</parameter></paramdef>
2005             </funcprototype>
2006           </funcsynopsis>
2007
2008           <para>This method sets the optional certificate and passphrase used
2009           in SSL-enabled communication with a remote server (when the
2010           <parameter>server_method</parameter> is set to 'https' in the
2011           client's construction or in the send method).</para>
2012
2013           <para>The <parameter>certificate</parameter> parameter must be the
2014           filename of a PEM formatted certificate. The
2015           <parameter>passphrase</parameter> parameter must contain the
2016           password required to use the certificate.</para>
2017
2018           <para>This requires the "curl" extension to be compiled into your
2019           installation of PHP. For more details see the man page for the
2020           <function>curl_setopt</function> function.</para>
2021
2022           <para>Note: to retrieve information about the client certificate on
2023           the server side, you will need to look into the environment
2024           variables which are set up by the webserver. Different webservers
2025           will typically set up different variables.</para>
2026         </sect3>
2027
2028         <sect3>
2029           <title>setCookie</title>
2030
2031           <funcsynopsis>
2032             <funcprototype>
2033               <funcdef><type>void</type><function>setCookie</function></funcdef>
2034
2035               <paramdef><type>string</type><parameter>$name</parameter></paramdef>
2036
2037               <paramdef><type>string</type><parameter>$value</parameter></paramdef>
2038
2039               <paramdef><type>string</type><parameter>$path</parameter></paramdef>
2040
2041               <paramdef><type>string</type><parameter>$domain</parameter></paramdef>
2042
2043               <paramdef><type>int</type><parameter>$port</parameter></paramdef>
2044             </funcprototype>
2045           </funcsynopsis>
2046
2047           <para>This method sets a cookie that will be sent to the xmlrpc
2048           server along with every further request (useful e.g. for keeping
2049           session info outside of the xml-rpc payload).</para>
2050
2051           <para><parameter>$value</parameter> is optional, and defaults to
2052           null.</para>
2053
2054           <para><parameter>$path, $domain and $port</parameter> are optional,
2055           and will be omitted from the cookie header if unspecified. Note that
2056           setting any of these values will turn the cookie into a 'version 1'
2057           cookie, that might not be fully supported by the server (see RFC2965
2058           for more details).</para>
2059         </sect3>
2060
2061         <sect3>
2062           <title>setCredentials</title>
2063
2064           <funcsynopsis>
2065             <funcprototype>
2066               <funcdef><type>void</type><function>setCredentials</function></funcdef>
2067
2068               <paramdef><type>string</type><parameter>$username</parameter></paramdef>
2069
2070               <paramdef><type>string</type><parameter>$password</parameter></paramdef>
2071
2072               <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
2073             </funcprototype>
2074           </funcsynopsis>
2075
2076           <para>This method sets the username and password for authorizing the
2077           client to a server. With the default (HTTP) transport, this
2078           information is used for HTTP Basic authorization. Note that username
2079           and password can also be set using the class constructor. With HTTP
2080           1.1 and HTTPS transport, NTLM and Digest authentication protocols
2081           are also supported. To enable them use the constants
2082           <constant>CURLAUTH_DIGEST</constant> and
2083           <constant>CURLAUTH_NTLM</constant> as values for the authtype
2084           parameter.</para>
2085         </sect3>
2086
2087         <sect3>
2088           <title>setDebug</title>
2089
2090           <funcsynopsis>
2091             <funcprototype>
2092               <funcdef><type>void</type><function>setDebug</function></funcdef>
2093
2094               <paramdef><type>int</type><parameter>$debugLvl</parameter></paramdef>
2095             </funcprototype>
2096           </funcsynopsis>
2097
2098           <para><parameter>debugLvl</parameter> is either <literal>0,
2099           1</literal> or 2 depending on whether you require the client to
2100           print debugging information to the browser. The default is not to
2101           output this information (0).</para>
2102
2103           <para>The debugging information at level 1includes the raw data
2104           returned from the XML-RPC server it was querying (including bot HTTP
2105           headers and the full XML payload), and the PHP value the client
2106           attempts to create to represent the value returned by the server. At
2107           level2, the complete payload of the xmlrpc request is also printed,
2108           before being sent t the server.</para>
2109
2110           <para>This option can be very useful when debugging servers as it
2111           allows you to see exactly what the client sends and the server
2112           returns.</para>
2113         </sect3>
2114
2115         <sect3>
2116           <title>setKey</title>
2117
2118           <funcsynopsis>
2119             <funcprototype>
2120               <funcdef><type>void</type><function>setKey</function></funcdef>
2121
2122               <paramdef><type>int</type><parameter>$key</parameter></paramdef>
2123
2124               <paramdef><type>int</type><parameter>$keypass</parameter></paramdef>
2125             </funcprototype>
2126           </funcsynopsis>
2127
2128           <para>This method sets the optional certificate key and passphrase
2129           used in SSL-enabled communication with a remote server (when the
2130           <parameter>transport</parameter> is set to 'https' in the client's
2131           construction or in the send method).</para>
2132
2133           <para>This requires the "curl" extension to be compiled into your
2134           installation of PHP. For more details see the man page for the
2135           <function>curl_setopt</function> function.</para>
2136         </sect3>
2137
2138         <sect3>
2139           <title>setProxy</title>
2140
2141           <funcsynopsis>
2142             <funcprototype>
2143               <funcdef><type>void</type><function>setProxy</function></funcdef>
2144
2145               <paramdef><type>string</type><parameter>$proxyhost</parameter></paramdef>
2146
2147               <paramdef><type>int</type><parameter>$proxyport</parameter></paramdef>
2148
2149               <paramdef><type>string</type><parameter>$proxyusername</parameter></paramdef>
2150
2151               <paramdef><type>string</type><parameter>$proxypassword</parameter></paramdef>
2152
2153               <paramdef><type>int</type><parameter>$authtype</parameter></paramdef>
2154             </funcprototype>
2155           </funcsynopsis>
2156
2157           <para>This method enables calling servers via an HTTP proxy. The
2158           <parameter>proxyusername</parameter>,<parameter>
2159           proxypassword</parameter> and <parameter>authtype</parameter>
2160           parameters are optional. <parameter>Authtype</parameter> defaults to
2161           <constant>CURLAUTH_BASIC</constant> (Basic authentication protocol);
2162           the only other valid value is the constant
2163           <constant>CURLAUTH_NTLM</constant>, and has effect only when the
2164           client uses the HTTP 1.1 protocol.</para>
2165
2166           <para>NB: CURL versions before 7.11.10 cannot use a proxy to
2167           communicate with https servers.</para>
2168         </sect3>
2169
2170         <sect3>
2171           <title>setRequestCompression</title>
2172
2173           <funcsynopsis>
2174             <funcprototype>
2175               <funcdef><type>void</type><function>setRequestCompression</function></funcdef>
2176
2177               <paramdef><type>string</type><parameter>$compressionmethod</parameter></paramdef>
2178             </funcprototype>
2179           </funcsynopsis>
2180
2181           <para>This method defines whether the xml payload forming the
2182           request body will be sent to the server in compressed format, as per
2183           the HTTP specification. This is particularly useful for large
2184           request parameters and over slow network connections. Allowed values
2185           for <parameter>compressionmethod</parameter> are: 'gzip', 'deflate',
2186           'any' or null (with any meaning either gzip or deflate). Note that
2187           there is no automatic fallback mechanism in place for errors due to
2188           servers not supporting receiving compressed request bodies, so make
2189           sure that the particular server you are querying does accept
2190           compressed requests before turning it on.</para>
2191
2192           <para>This requires the "zlib" extension to be enabled in your php
2193           install.</para>
2194         </sect3>
2195
2196         <sect3>
2197           <title>setSSLVerifyHost</title>
2198
2199           <funcsynopsis>
2200             <funcprototype>
2201               <funcdef><type>void</type><function>setSSLVerifyHost</function></funcdef>
2202
2203               <paramdef><type>int</type><parameter>$i</parameter></paramdef>
2204             </funcprototype>
2205           </funcsynopsis>
2206
2207           <para>This method defines whether connections made to XML-RPC
2208           backends via HTTPS should verify the remote host's SSL certificate's
2209           common name (CN). By default, only the existence of a CN is checked.
2210           <parameter><parameter>$i</parameter></parameter> should be an
2211           integer value; 0 to not check the CN at all, 1 to merely check for
2212           its existence, and 2 to check that the CN on the certificate matches
2213           the hostname that is being connected to.</para>
2214         </sect3>
2215
2216         <sect3>
2217           <title>setSSLVerifyPeer</title>
2218
2219           <funcsynopsis>
2220             <funcprototype>
2221               <funcdef><type>void</type><function>setSSLVerifyPeer</function></funcdef>
2222
2223               <paramdef><type>bool</type><parameter>$i</parameter></paramdef>
2224             </funcprototype>
2225           </funcsynopsis>
2226
2227           <para>This method defines whether connections made to XML-RPC
2228           backends via HTTPS should verify the remote host's SSL certificate,
2229           and cause the connection to fail if the cert verification fails.
2230           <parameter><parameter>$i</parameter></parameter> should be a boolean
2231           value. Default value: <constant>TRUE</constant>. To specify custom
2232           SSL certificates to validate the server with, use the
2233           <methodname>setCaCertificate</methodname> method.</para>
2234         </sect3>
2235       </sect2>
2236
2237       <sect2>
2238         <title>Variables</title>
2239
2240         <para>NB: direct manipulation of these variables is only recommended
2241         for advanced users.</para>
2242
2243         <sect3>
2244           <title>no_multicall</title>
2245
2246           <para>This member variable determines whether the multicall() method
2247           will try to take advantage of the system.multicall xmlrpc method to
2248           dispatch to the server an array of requests in a single http
2249           roundtrip or simply execute many consecutive http calls. Defaults to
2250           FALSE, but it will be enabled automatically on the first failure of
2251           execution of system.multicall.</para>
2252         </sect3>
2253
2254         <sect3>
2255           <title>request_charset_encoding</title>
2256
2257           <para>This is the charset encoding that will be used for serializing
2258           request sent by the client.</para>
2259
2260           <para>If defaults to NULL, which means using US-ASCII and encoding
2261           all characters outside of the ASCII range using their xml character
2262           entity representation (this has the benefit that line end characters
2263           will not be mangled in the transfer, a CR-LF will be preserved as
2264           well as a singe LF).</para>
2265
2266           <para>Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'</para>
2267         </sect3>
2268
2269         <sect3 id="return-type" xreflabel="return_type">
2270           <title>return_type</title>
2271
2272           <para>This member variable determines whether the value returned
2273           inside an xmlrpcresp object as results of calls to the send() and
2274           multicall() methods will be an xmlrpcval object, a plain php value
2275           or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
2276           'phpvals' and 'xml'. To allow the user to differentiate between a
2277           correct and a faulty response, fault responses will be returned as
2278           xmlrpcresp objects in any case. Note that the 'phpvals' setting will
2279           yield faster execution times, but some of the information from the
2280           original response will be lost. It will be e.g. impossible to tell
2281           whether a particular php string value was sent by the server as an
2282           xmlrpc string or base64 value.</para>
2283
2284           <para>Example usage:</para>
2285
2286           <programlisting language="php">
2287 $client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server");
2288 $client-&gt;return_type = 'phpvals';
2289 $message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
2290 $resp = $client-&gt;send($message);
2291 if ($resp-&gt;faultCode()) echo 'KO. Error: '.$resp-&gt;faultString(); else echo 'OK: got '.$resp-&gt;value();
2292 </programlisting>
2293
2294           <para>For more details about usage of the 'xml' value, see Appendix
2295           A.</para>
2296         </sect3>
2297       </sect2>
2298     </sect1>
2299
2300     <sect1 id="xmlrpcresp" xreflabel="xmlrpcresp">
2301       <title>xmlrpcresp</title>
2302
2303       <para>This class is used to contain responses to XML-RPC requests. A
2304       server method handler will construct an
2305       <classname>xmlrpcresp</classname> and pass it as a return value. This
2306       same value will be returned by the result of an invocation of the
2307       <function>send</function> method of the
2308       <classname>xmlrpc_client</classname> class.</para>
2309
2310       <sect2>
2311         <title>Creation</title>
2312
2313         <funcsynopsis>
2314           <funcprototype>
2315             <funcdef><type>xmlrpcresp</type>new
2316             <function>xmlrpcresp</function></funcdef>
2317
2318             <paramdef><type>xmlrpcval</type><parameter>$xmlrpcval</parameter></paramdef>
2319           </funcprototype>
2320
2321           <funcprototype>
2322             <funcdef><type>xmlrpcresp</type>new
2323             <function>xmlrpcresp</function></funcdef>
2324
2325             <paramdef><parameter>0</parameter></paramdef>
2326
2327             <paramdef><type>int</type><parameter>$errcode</parameter></paramdef>
2328
2329             <paramdef><type>string</type><parameter>$err_string</parameter></paramdef>
2330           </funcprototype>
2331         </funcsynopsis>
2332
2333         <para>The first syntax is used when execution has happened without
2334         difficulty: <parameter>$xmlrpcval</parameter> is an
2335         <classname>xmlrpcval</classname> value with the result of the method
2336         execution contained in it. Alternatively it can be a string containing
2337         the xml serialization of the single xml-rpc value result of method
2338         execution.</para>
2339
2340         <para>The second type of constructor is used in case of failure.
2341         <parameter>errcode</parameter> and <parameter>err_string</parameter>
2342         are used to provide indication of what has gone wrong. See <xref
2343         linkend="xmlrpc-server" /> for more information on passing error
2344         codes.</para>
2345       </sect2>
2346
2347       <sect2>
2348         <title>Methods</title>
2349
2350         <sect3>
2351           <title>faultCode</title>
2352
2353           <funcsynopsis>
2354             <funcprototype>
2355               <funcdef><type>int</type><function>faultCode</function></funcdef>
2356
2357               <void />
2358             </funcprototype>
2359           </funcsynopsis>
2360
2361           <para>Returns the integer fault code return from the XML-RPC
2362           response. A zero value indicates success, any other value indicates
2363           a failure response.</para>
2364         </sect3>
2365
2366         <sect3>
2367           <title>faultString</title>
2368
2369           <funcsynopsis>
2370             <funcprototype>
2371               <funcdef><type>string</type><function>faultString</function></funcdef>
2372
2373               <void />
2374             </funcprototype>
2375           </funcsynopsis>
2376
2377           <para>Returns the human readable explanation of the fault indicated
2378           by <function>$resp-&gt;faultCode</function>().</para>
2379         </sect3>
2380
2381         <sect3>
2382           <title>value</title>
2383
2384           <funcsynopsis>
2385             <funcprototype>
2386               <funcdef><type>xmlrpcval</type><function>value</function></funcdef>
2387
2388               <void />
2389             </funcprototype>
2390           </funcsynopsis>
2391
2392           <para>Returns an <classname>xmlrpcval</classname> object containing
2393           the return value sent by the server. If the response's
2394           <function>faultCode</function> is non-zero then the value returned
2395           by this method should not be used (it may not even be an
2396           object).</para>
2397
2398           <para>Note: if the xmlrpcresp instance in question has been created
2399           by an <classname>xmlrpc_client</classname> object whose
2400           <varname>return_type</varname> was set to 'phpvals', then a plain
2401           php value will be returned instead of an
2402           <classname>xmlrpcval</classname> object. If the
2403           <varname>return_type</varname> was set to 'xml', an xml string will
2404           be returned (see the return_type member var above for more
2405           details).</para>
2406         </sect3>
2407
2408         <sect3>
2409           <title>serialize</title>
2410
2411           <funcsynopsis>
2412             <funcprototype>
2413               <funcdef><type>string</type><function>serialize</function></funcdef>
2414
2415               <void />
2416             </funcprototype>
2417           </funcsynopsis>
2418
2419           <para>Returns an XML string representation of the response (xml
2420           prologue not included).</para>
2421         </sect3>
2422       </sect2>
2423     </sect1>
2424
2425     <sect1 id="xmlrpc-server" xreflabel="xmlrpc_server">
2426       <title>xmlrpc_server</title>
2427
2428       <para>The implementation of this class has been kept as simple to use as
2429       possible. The constructor for the server basically does all the work.
2430       Here's a minimal example:</para>
2431
2432       <programlisting language="php">
2433   function foo ($xmlrpcmsg) {
2434     ...
2435     return new xmlrpcresp($some_xmlrpc_val);
2436   }
2437
2438   class bar {
2439     function foobar($xmlrpcmsg) {
2440       ...
2441       return new xmlrpcresp($some_xmlrpc_val);
2442     }
2443   }
2444
2445   $s = new xmlrpc_server(
2446     array(
2447       "examples.myFunc1" =&gt; array("function" =&gt; "foo"),
2448       "examples.myFunc2" =&gt; array("function" =&gt; "bar::foobar"),
2449     ));
2450 </programlisting>
2451
2452       <para>This performs everything you need to do with a server. The single
2453       constructor argument is an associative array from xmlrpc method names to
2454       php function names. The incoming request is parsed and dispatched to the
2455       relevant php function, which is responsible for returning a
2456       <classname>xmlrpcresp</classname> object, that will be serialized back
2457       to the caller.</para>
2458
2459       <sect2>
2460         <title>Method handler functions</title>
2461
2462         <para>Both php functions and class methods can be registered as xmlrpc
2463         method handlers.</para>
2464
2465         <para>The synopsis of a method handler function is:</para>
2466
2467         <para><synopsis>xmlrpcresp $resp = function (xmlrpcmsg $msg)</synopsis></para>
2468
2469         <para>No text should be echoed 'to screen' by the handler function, or
2470         it will break the xml response sent back to the client. This applies
2471         also to error and warning messages that PHP prints to screen unless
2472         the appropriate parameters have been set in the php.in file. Another
2473         way to prevent echoing of errors inside the response and facilitate
2474         debugging is to use the server SetDebug method with debug level 3 (see
2475         below).</para>
2476
2477         <para>Note that if you implement a method with a name prefixed by
2478         <code>system.</code> the handler function will be invoked by the
2479         server with two parameters, the first being the server itself and the
2480         second being the <classname>xmlrpcmsg</classname> object.</para>
2481
2482         <para>The same php function can be registered as handler of multiple
2483         xmlrpc methods.</para>
2484
2485         <para>Here is a more detailed example of what the handler function
2486         <function>foo</function> may do:</para>
2487
2488         <programlisting language="php">
2489   function foo ($xmlrpcmsg) {
2490     global $xmlrpcerruser; // import user errcode base value
2491
2492     $meth = $xmlrpcmsg-&gt;method(); // retrieve method name
2493     $par = $xmlrpcmsg-&gt;getParam(0); // retrieve value of first parameter - assumes at least one param received
2494     $val = $par-&gt;scalarval(); // decode value of first parameter - assumes it is a scalar value
2495
2496     ...
2497
2498     if ($err) {
2499       // this is an error condition
2500       return new xmlrpcresp(0, $xmlrpcerruser+1, // user error 1
2501         "There's a problem, Captain");
2502     } else {
2503       // this is a successful value being returned
2504       return new xmlrpcresp(new xmlrpcval("All's fine!", "string"));
2505     }
2506   }
2507 </programlisting>
2508
2509         <para>See <filename>server.php</filename> in this distribution for
2510         more examples of how to do this.</para>
2511
2512         <para>Since release 2.0RC3 there is a new, even simpler way of
2513         registering php functions with the server. See section 5.7
2514         below</para>
2515       </sect2>
2516
2517       <sect2>
2518         <title>The dispatch map</title>
2519
2520         <para>The first argument to the <function>xmlrpc_server</function>
2521         constructor is an array, called the <emphasis>dispatch map</emphasis>.
2522         In this array is the information the server needs to service the
2523         XML-RPC methods you define.</para>
2524
2525         <para>The dispatch map takes the form of an associative array of
2526         associative arrays: the outer array has one entry for each method, the
2527         key being the method name. The corresponding value is another
2528         associative array, which can have the following members:</para>
2529
2530         <itemizedlist>
2531           <listitem>
2532             <para><function><literal>function</literal></function> - this
2533             entry is mandatory. It must be either a name of a function in the
2534             global scope which services the XML-RPC method, or an array
2535             containing an instance of an object and a static method name (for
2536             static class methods the 'class::method' syntax is also
2537             supported).</para>
2538           </listitem>
2539
2540           <listitem>
2541             <para><function><literal>signature</literal></function> - this
2542             entry is an array containing the possible signatures (see <xref
2543             linkend="signatures" />) for the method. If this entry is present
2544             then the server will check that the correct number and type of
2545             parameters have been sent for this method before dispatching
2546             it.</para>
2547           </listitem>
2548
2549           <listitem>
2550             <para><function><literal>docstring</literal></function> - this
2551             entry is a string containing documentation for the method. The
2552             documentation may contain HTML markup.</para>
2553           </listitem>
2554
2555           <listitem>
2556             <para><literal>signature_docs</literal> - this entry can be used
2557             to provide documentation for the single parameters. It must match
2558             in structure the 'signature' member. By default, only the
2559             <classname>documenting_xmlrpc_server</classname> class in the
2560             extras package will take advantage of this, since the
2561             "system.methodHelp" protocol does not support documenting method
2562             parameters individually.</para>
2563           </listitem>
2564         </itemizedlist>
2565
2566         <para>Look at the <filename>server.php</filename> example in the
2567         distribution to see what a dispatch map looks like.</para>
2568       </sect2>
2569
2570       <sect2 id="signatures" xreflabel="Signatures">
2571         <title>Method signatures</title>
2572
2573         <para>A signature is a description of a method's return type and its
2574         parameter types. A method may have more than one signature.</para>
2575
2576         <para>Within a server's dispatch map, each method has an array of
2577         possible signatures. Each signature is an array of types. The first
2578         entry is the return type. For instance, the method <programlisting
2579         language="php">string examples.getStateName(int)
2580 </programlisting> has the signature <programlisting language="php">array($xmlrpcString, $xmlrpcInt)
2581 </programlisting> and, assuming that it is the only possible signature for the
2582         method, it might be used like this in server creation: <programlisting
2583         language="php">
2584 $findstate_sig = array(array($xmlrpcString, $xmlrpcInt));
2585
2586 $findstate_doc = 'When passed an integer between 1 and 51 returns the
2587 name of a US state, where the integer is the index of that state name
2588 in an alphabetic order.';
2589
2590 $s = new xmlrpc_server( array(
2591   "examples.getStateName" =&gt; array(
2592     "function" =&gt; "findstate",
2593     "signature" =&gt; $findstate_sig,
2594     "docstring" =&gt; $findstate_doc
2595   )));
2596 </programlisting></para>
2597
2598         <para>Note that method signatures do not allow to check nested
2599         parameters, e.g. the number, names and types of the members of a
2600         struct param cannot be validated.</para>
2601
2602         <para>If a method that you want to expose has a definite number of
2603         parameters, but each of those parameters could reasonably be of
2604         multiple types, the array of acceptable signatures will easily grow
2605         into a combinatorial explosion. To avoid such a situation, the lib
2606         defines the global var <varname>$xmlrpcValue</varname>, which can be
2607         used in method signatures as a placeholder for 'any xmlrpc
2608         type':</para>
2609
2610         <para><programlisting language="php">
2611 $echoback_sig = array(array($xmlrpcValue, $xmlrpcValue));
2612
2613 $findstate_doc = 'Echoes back to the client the received value, regardless of its type';
2614
2615 $s = new xmlrpc_server( array(
2616   "echoBack" =&gt; array(
2617     "function" =&gt; "echoback",
2618     "signature" =&gt; $echoback_sig, // this sig guarantees that the method handler will be called with one and only one parameter
2619     "docstring" =&gt; $echoback_doc
2620   )));
2621 </programlisting></para>
2622
2623         <para>Methods <methodname>system.listMethods</methodname>,
2624         <methodname>system.methodHelp</methodname>,
2625         <methodname>system.methodSignature</methodname> and
2626         <methodname>system.multicall</methodname> are already defined by the
2627         server, and should not be reimplemented (see Reserved Methods
2628         below).</para>
2629       </sect2>
2630
2631       <sect2>
2632         <title>Delaying the server response</title>
2633
2634         <para>You may want to construct the server, but for some reason not
2635         fulfill the request immediately (security verification, for instance).
2636         If you omit to pass to the constructor the dispatch map or pass it a
2637         second argument of <literal>0</literal> this will have the desired
2638         effect. You can then use the <function>service()</function> method of
2639         the server class to service the request. For example:</para>
2640
2641         <programlisting language="php">
2642 $s = new xmlrpc_server($myDispMap, 0); // second parameter = 0 prevents automatic servicing of request
2643
2644 // ... some code that does other stuff here
2645
2646 $s-&gt;service();
2647 </programlisting>
2648
2649         <para>Note that the <methodname>service</methodname> method will print
2650         the complete result payload to screen and send appropriate HTTP
2651         headers back to the client, but also return the response object. This
2652         permits further manipulation of the response.</para>
2653
2654         <para>To prevent the server from sending HTTP headers back to the
2655         client, you can pass a second parameter with a value of
2656         <literal>TRUE</literal> to the <methodname>service</methodname>
2657         method. In this case, the response payload will be returned instead of
2658         the response object.</para>
2659
2660         <para>Xmlrpc requests retrieved by other means than HTTP POST bodies
2661         can also be processed. For example:</para>
2662
2663         <programlisting language="php">
2664 $s = new xmlrpc_server(); // not passing a dispatch map prevents automatic servicing of request
2665
2666 // ... some code that does other stuff here, including setting dispatch map into server object
2667
2668 $resp = $s-&gt;service($xmlrpc_request_body, true); // parse a variable instead of POST body, retrieve response payload
2669
2670 // ... some code that does other stuff with xml response $resp here
2671 </programlisting>
2672       </sect2>
2673
2674       <sect2>
2675         <title>Modifying the server behaviour</title>
2676
2677         <para>A couple of methods / class variables are available to modify
2678         the behaviour of the server. The only way to take advantage of their
2679         existence is by usage of a delayed server response (see above)</para>
2680
2681         <sect3>
2682           <title>setDebug()</title>
2683
2684           <para>This function controls weather the server is going to echo
2685           debugging messages back to the client as comments in response body.
2686           Valid values: 0,1,2,3, with 1 being the default. At level 0, no
2687           debug info is returned to the client. At level 2, the complete
2688           client request is added to the response, as part of the xml
2689           comments. At level 3, a new PHP error handler is set when executing
2690           user functions exposed as server methods, and all non-fatal errors
2691           are trapped and added as comments into the response.</para>
2692         </sect3>
2693
2694         <sect3>
2695           <title>allow_system_funcs</title>
2696
2697           <para>Default_value: TRUE. When set to FALSE, disables support for
2698           <methodname>System.xxx</methodname> functions in the server. It
2699           might be useful e.g. if you do not wish the server to respond to
2700           requests to <methodname>System.ListMethods</methodname>.</para>
2701         </sect3>
2702
2703         <sect3>
2704           <title>compress_response</title>
2705
2706           <para>When set to TRUE, enables the server to take advantage of HTTP
2707           compression, otherwise disables it. Responses will be transparently
2708           compressed, but only when an xmlrpc-client declares its support for
2709           compression in the HTTP headers of the request.</para>
2710
2711           <para>Note that the ZLIB php extension must be installed for this to
2712           work. If it is, <varname>compress_response</varname> will default to
2713           TRUE.</para>
2714         </sect3>
2715
2716         <sect3>
2717           <title>response_charset_encoding</title>
2718
2719           <para>Charset encoding to be used for response (only affects string
2720           values).</para>
2721
2722           <para>If it can, the server will convert the generated response from
2723           internal_encoding to the intended one.</para>
2724
2725           <para>Valid values are: a supported xml encoding (only UTF-8 and
2726           ISO-8859-1 at present, unless mbstring is enabled), null (leave
2727           charset unspecified in response and convert output stream to
2728           US_ASCII), 'default' (use xmlrpc library default as specified in
2729           xmlrpc.inc, convert output stream if needed), or 'auto' (use
2730           client-specified charset encoding or same as request if request
2731           headers do not specify it (unless request is US-ASCII: then use
2732           library default anyway).</para>
2733         </sect3>
2734       </sect2>
2735
2736       <sect2>
2737         <title>Fault reporting</title>
2738
2739         <para>Fault codes for your servers should start at the value indicated
2740         by the global <literal>$xmlrpcerruser</literal> + 1.</para>
2741
2742         <para>Standard errors returned by the server include:</para>
2743
2744         <variablelist>
2745           <varlistentry>
2746             <term><literal>1</literal> <phrase>Unknown method</phrase></term>
2747
2748             <listitem>
2749               <para>Returned if the server was asked to dispatch a method it
2750               didn't know about</para>
2751             </listitem>
2752           </varlistentry>
2753
2754           <varlistentry>
2755             <term><literal>2</literal> <phrase>Invalid return
2756             payload</phrase></term>
2757
2758             <listitem>
2759               <para>This error is actually generated by the client, not
2760               server, code, but signifies that a server returned something it
2761               couldn't understand. A more detailed error report is sometimes
2762               added onto the end of the phrase above.</para>
2763             </listitem>
2764           </varlistentry>
2765
2766           <varlistentry>
2767             <term><literal>3</literal> <phrase>Incorrect
2768             parameters</phrase></term>
2769
2770             <listitem>
2771               <para>This error is generated when the server has signature(s)
2772               defined for a method, and the parameters passed by the client do
2773               not match any of signatures.</para>
2774             </listitem>
2775           </varlistentry>
2776
2777           <varlistentry>
2778             <term><literal>4</literal> <phrase>Can't introspect: method
2779             unknown</phrase></term>
2780
2781             <listitem>
2782               <para>This error is generated by the builtin
2783               <function>system.*</function> methods when any kind of
2784               introspection is attempted on a method undefined by the
2785               server.</para>
2786             </listitem>
2787           </varlistentry>
2788
2789           <varlistentry>
2790             <term><literal>5</literal> <phrase>Didn't receive 200 OK from
2791             remote server</phrase></term>
2792
2793             <listitem>
2794               <para>This error is generated by the client when a remote server
2795               doesn't return HTTP/1.1 200 OK in response to a request. A more
2796               detailed error report is added onto the end of the phrase
2797               above.</para>
2798             </listitem>
2799           </varlistentry>
2800
2801           <varlistentry>
2802             <term><literal>6</literal> <phrase>No data received from
2803             server</phrase></term>
2804
2805             <listitem>
2806               <para>This error is generated by the client when a remote server
2807               returns HTTP/1.1 200 OK in response to a request, but no
2808               response body follows the HTTP headers.</para>
2809             </listitem>
2810           </varlistentry>
2811
2812           <varlistentry>
2813             <term><literal>7</literal> <phrase>No SSL support compiled
2814             in</phrase></term>
2815
2816             <listitem>
2817               <para>This error is generated by the client when trying to send
2818               a request with HTTPS and the CURL extension is not available to
2819               PHP.</para>
2820             </listitem>
2821           </varlistentry>
2822
2823           <varlistentry>
2824             <term><literal>8</literal> <phrase>CURL error</phrase></term>
2825
2826             <listitem>
2827               <para>This error is generated by the client when trying to send
2828               a request with HTTPS and the HTTPS communication fails.</para>
2829             </listitem>
2830           </varlistentry>
2831
2832           <varlistentry>
2833             <term><literal>9-14</literal> <phrase>multicall
2834             errors</phrase></term>
2835
2836             <listitem>
2837               <para>These errors are generated by the server when something
2838               fails inside a system.multicall request.</para>
2839             </listitem>
2840           </varlistentry>
2841
2842           <varlistentry>
2843             <term><literal>100-</literal> <phrase>XML parse
2844             errors</phrase></term>
2845
2846             <listitem>
2847               <para>Returns 100 plus the XML parser error code for the fault
2848               that occurred. The <function>faultString</function> returned
2849               explains where the parse error was in the incoming XML
2850               stream.</para>
2851             </listitem>
2852           </varlistentry>
2853         </variablelist>
2854       </sect2>
2855
2856       <sect2>
2857         <title>'New style' servers</title>
2858
2859         <para>In the same spirit of simplification that inspired the
2860         <varname>xmlrpc_client::return_type</varname> class variable, a new
2861         class variable has been added to the server class:
2862         <varname>functions_parameters_type</varname>. When set to 'phpvals',
2863         the functions registered in the server dispatch map will be called
2864         with plain php values as parameters, instead of a single xmlrpcmsg
2865         instance parameter. The return value of those functions is expected to
2866         be a plain php value, too. An example is worth a thousand
2867         words:<programlisting language="php">
2868   function foo($usr_id, $out_lang='en') {
2869     global $xmlrpcerruser;
2870
2871     ...
2872
2873     if ($someErrorCondition)
2874       return new xmlrpcresp(0, $xmlrpcerruser+1, 'DOH!');
2875     else
2876       return array(
2877         'name' =&gt; 'Joe',
2878         'age' =&gt; 27,
2879         'picture' =&gt; new xmlrpcval(file_get_contents($picOfTheGuy), 'base64')
2880       );
2881   }
2882
2883   $s = new xmlrpc_server(
2884     array(
2885       "examples.myFunc" =&gt; array(
2886         "function" =&gt; "bar::foobar",
2887         "signature" =&gt; array(
2888           array($xmlrpcString, $xmlrpcInt),
2889           array($xmlrpcString, $xmlrpcInt, $xmlrpcString)
2890         )
2891       )
2892     ), false);
2893   $s-&gt;functions_parameters_type = 'phpvals';
2894   $s-&gt;service();
2895 </programlisting>There are a few things to keep in mind when using this
2896         simplified syntax:</para>
2897
2898         <para>to return an xmlrpc error, the method handler function must
2899         return an instance of xmlrpcresp. There is no other way for the server
2900         to know when an error response should be served to the client;</para>
2901
2902         <para>to return a base64 value, the method handler function must
2903         encode it on its own, creating an instance of an xmlrpcval
2904         object;</para>
2905
2906         <para>the method handler function cannot determine the name of the
2907         xmlrpc method it is serving, unlike standard handler functions that
2908         can retrieve it from the message object;</para>
2909
2910         <para>when receiving nested parameters, the method handler function
2911         has no way to distinguish a php string that was sent as base64 value
2912         from one that was sent as a string value;</para>
2913
2914         <para>this has a direct consequence on the support of
2915         system.multicall: a method whose signature contains datetime or base64
2916         values will not be available to multicall calls;</para>
2917
2918         <para>last but not least, the direct parsing of xml to php values is
2919         much faster than using xmlrpcvals, and allows the library to handle
2920         much bigger messages without allocating all available server memory or
2921         smashing PHP recursive call stack.</para>
2922       </sect2>
2923     </sect1>
2924   </chapter>
2925
2926   <chapter id="globalvars">
2927     <title>Global variables</title>
2928
2929     <para>Many global variables are defined in the xmlrpc.inc file. Some of
2930     those are meant to be used as constants (and modifying their value might
2931     cause unpredictable behaviour), while some others can be modified in your
2932     php scripts to alter the behaviour of the xml-rpc client and
2933     server.</para>
2934
2935     <sect1>
2936       <title>"Constant" variables</title>
2937
2938       <sect2>
2939         <title>$xmlrpcerruser</title>
2940
2941         <para><fieldsynopsis>
2942             <varname>$xmlrpcerruser</varname>
2943
2944             <initializer>800</initializer>
2945           </fieldsynopsis>The minimum value for errors reported by user
2946         implemented XML-RPC servers. Error numbers lower than that are
2947         reserved for library usage.</para>
2948       </sect2>
2949
2950       <sect2>
2951         <title>$xmlrpcI4, $xmlrpcInt, $xmlrpcBoolean, $xmlrpcDouble,
2952         $xmlrpcString, $xmlrpcDateTime, $xmlrpcBase64, $xmlrpcArray,
2953         $xmlrpcStruct, $xmlrpcValue, $xmlrpcNull</title>
2954
2955         <para>For convenience the strings representing the XML-RPC types have
2956         been encoded as global variables:<programlisting language="php">
2957 $xmlrpcI4="i4";
2958 $xmlrpcInt="int";
2959 $xmlrpcBoolean="boolean";
2960 $xmlrpcDouble="double";
2961 $xmlrpcString="string";
2962 $xmlrpcDateTime="dateTime.iso8601";
2963 $xmlrpcBase64="base64";
2964 $xmlrpcArray="array";
2965 $xmlrpcStruct="struct";
2966 $xmlrpcValue="undefined";
2967 $xmlrpcNull="null";
2968 </programlisting></para>
2969       </sect2>
2970
2971       <sect2>
2972         <title>$xmlrpcTypes, $xmlrpc_valid_parents, $xmlrpcerr, $xmlrpcstr,
2973         $xmlrpcerrxml, $xmlrpc_backslash, $_xh, $xml_iso88591_Entities,
2974         $xmlEntities, $xmlrpcs_capabilities</title>
2975
2976         <para>Reserved for internal usage.</para>
2977       </sect2>
2978     </sect1>
2979
2980     <sect1>
2981       <title>Variables whose value can be modified</title>
2982
2983       <sect2 id="xmlrpc-defencoding" xreflabel="xmlrpc_defencoding">
2984         <title xreflabel="">xmlrpc_defencoding</title>
2985
2986         <fieldsynopsis>
2987           <varname>$xmlrpc_defencoding</varname>
2988
2989           <initializer>"UTF8"</initializer>
2990         </fieldsynopsis>
2991
2992         <para>This variable defines the character set encoding that will be
2993         used by the xml-rpc client and server to decode the received messages,
2994         when a specific charset declaration is not found (in the messages sent
2995         non-ascii chars are always encoded using character references, so that
2996         the produced xml is valid regardless of the charset encoding
2997         assumed).</para>
2998
2999         <para>Allowed values: <literal>"UTF8"</literal>,
3000         <literal>"ISO-8859-1"</literal>, <literal>"ASCII".</literal></para>
3001
3002         <para>Note that the appropriate RFC actually mandates that XML
3003         received over HTTP without indication of charset encoding be treated
3004         as US-ASCII, but many servers and clients 'in the wild' violate the
3005         standard, and assume the default encoding is UTF-8.</para>
3006       </sect2>
3007
3008       <sect2>
3009         <title>xmlrpc_internalencoding</title>
3010
3011         <para><fieldsynopsis>
3012             <varname>$xmlrpc_internalencoding</varname>
3013
3014             <initializer>"ISO-8859-1"</initializer>
3015           </fieldsynopsis>This variable defines the character set encoding
3016         that the library uses to transparently encode into valid XML the
3017         xml-rpc values created by the user and to re-encode the received
3018         xml-rpc values when it passes them to the PHP application. It only
3019         affects xml-rpc values of string type. It is a separate value from
3020         xmlrpc_defencoding, allowing e.g. to send/receive xml messages encoded
3021         on-the-wire in US-ASCII and process them as UTF-8. It defaults to the
3022         character set used internally by PHP (unless you are running an
3023         MBString-enabled installation), so you should change it only in
3024         special situations, if e.g. the string values exchanged in the xml-rpc
3025         messages are directly inserted into / fetched from a database
3026         configured to return UTF8 encoded strings to PHP. Example
3027         usage:</para>
3028
3029         <para><programlisting language="php">
3030 &lt;?php
3031
3032 include('xmlrpc.inc');
3033 $xmlrpc_internalencoding = 'UTF-8'; // this has to be set after the inclusion above
3034 $v = new xmlrpcval('Îºá½¹Ï\83Î¼Îµ'); // This xmlrpc value will be correctly serialized as the greek word 'kosme'
3035 </programlisting></para>
3036       </sect2>
3037
3038       <sect2>
3039         <title>xmlrpcName</title>
3040
3041         <para><fieldsynopsis>
3042             <varname>$xmlrpcName</varname>
3043
3044             <initializer>"XML-RPC for PHP"</initializer>
3045           </fieldsynopsis>The string representation of the name of the XML-RPC
3046         for PHP library. It is used by the client for building the User-Agent
3047         HTTP header that is sent with every request to the server. You can
3048         change its value if you need to customize the User-Agent
3049         string.</para>
3050       </sect2>
3051
3052       <sect2>
3053         <title>xmlrpcVersion</title>
3054
3055         <para><fieldsynopsis>
3056             <varname>$xmlrpcVersion</varname>
3057
3058             <initializer>"2.2"</initializer>
3059           </fieldsynopsis>The string representation of the version number of
3060         the XML-RPC for PHP library in use. It is used by the client for
3061         building the User-Agent HTTP header that is sent with every request to
3062         the server. You can change its value if you need to customize the
3063         User-Agent string.</para>
3064       </sect2>
3065
3066       <sect2>
3067         <title>xmlrpc_null_extension</title>
3068
3069         <para>When set to <constant>TRUE</constant>, the lib will enable
3070         support for the &lt;NIL/&gt; xmlrpc value, as per the extension to the
3071         standard proposed here. This means that &lt;NIL/&gt; tags will be
3072         parsed as valid xmlrpc, and the corresponding xmlrpcvals will return
3073         "null" for <methodname>scalarTyp()</methodname>.</para>
3074       </sect2>
3075     </sect1>
3076   </chapter>
3077
3078   <chapter id="helpers">
3079     <title>Helper functions</title>
3080
3081     <para>XML-RPC for PHP contains some helper functions which you can use to
3082     make processing of XML-RPC requests easier.</para>
3083
3084     <sect1>
3085       <title>Date functions</title>
3086
3087       <para>The XML-RPC specification has this to say on dates:</para>
3088
3089       <blockquote>
3090         <para id="wrap_xmlrpc_method">Don't assume a timezone. It should be
3091         specified by the server in its documentation what assumptions it makes
3092         about timezones.</para>
3093       </blockquote>
3094
3095       <para>Unfortunately, this means that date processing isn't
3096       straightforward. Although XML-RPC uses ISO 8601 format dates, it doesn't
3097       use the timezone specifier.</para>
3098
3099       <para>We strongly recommend that in every case where you pass dates in
3100       XML-RPC calls, you use UTC (GMT) as your timezone. Most computer
3101       languages include routines for handling GMT times natively, and you
3102       won't have to translate between timezones.</para>
3103
3104       <para>For more information about dates, see <ulink
3105       url="http://www.uic.edu/year2000/datefmt.html">ISO 8601: The Right
3106       Format for Dates</ulink>, which has a handy link to a PDF of the ISO
3107       8601 specification. Note that XML-RPC uses exactly one of the available
3108       representations: CCYYMMDDTHH:MM:SS.</para>
3109
3110       <sect2 id="iso8601encode" xreflabel="iso8601_encode()">
3111         <title>iso8601_encode</title>
3112
3113         <funcsynopsis>
3114           <funcprototype>
3115             <funcdef><type>string</type><function>iso8601_encode</function></funcdef>
3116
3117             <paramdef><type>string</type><parameter>$time_t</parameter></paramdef>
3118
3119             <paramdef
3120             choice="opt"><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
3121           </funcprototype>
3122         </funcsynopsis>
3123
3124         <para>Returns an ISO 8601 formatted date generated from the UNIX
3125         timestamp <parameter>$time_t</parameter>, as returned by the PHP
3126         function <function>time()</function>.</para>
3127
3128         <para>The argument <parameter>$utc</parameter> can be omitted, in
3129         which case it defaults to <literal>0</literal>. If it is set to
3130         <literal>1</literal>, then the function corrects the time passed in
3131         for UTC. Example: if you're in the GMT-6:00 timezone and set
3132         <parameter>$utc</parameter>, you will receive a date representation
3133         six hours ahead of your local time.</para>
3134
3135         <para>The included demo program <filename>vardemo.php</filename>
3136         includes a demonstration of this function.</para>
3137       </sect2>
3138
3139       <sect2 id="iso8601decode" xreflabel="iso8601_decode()">
3140         <title>iso8601_decode</title>
3141
3142         <funcsynopsis>
3143           <funcprototype>
3144             <funcdef><type>int</type><function>iso8601_decode</function></funcdef>
3145
3146             <paramdef><type>string</type><parameter>$isoString</parameter></paramdef>
3147
3148             <paramdef><type>int</type><parameter>$utc</parameter><initializer>0</initializer></paramdef>
3149           </funcprototype>
3150         </funcsynopsis>
3151
3152         <para>Returns a UNIX timestamp from an ISO 8601 encoded time and date
3153         string passed in. If <parameter>$utc</parameter> is
3154         <literal>1</literal> then <parameter>$isoString</parameter> is assumed
3155         to be in the UTC timezone, and thus the result is also UTC: otherwise,
3156         the timezone is assumed to be your local timezone and you receive a
3157         local timestamp.</para>
3158       </sect2>
3159     </sect1>
3160
3161     <sect1 id="arrayuse">
3162       <title>Easy use with nested PHP values</title>
3163
3164       <para>Dan Libby was kind enough to contribute two helper functions that
3165       make it easier to translate to and from PHP values. This makes it easier
3166       to deal with complex structures. At the moment support is limited to
3167       <type>int</type>, <type>double</type>, <type>string</type>,
3168       <type>array</type>, <type>datetime</type> and <type>struct</type>
3169       datatypes; note also that all PHP arrays are encoded as structs, except
3170       arrays whose keys are integer numbers starting with 0 and incremented by
3171       1.</para>
3172
3173       <para>These functions reside in <filename>xmlrpc.inc</filename>.</para>
3174
3175       <sect2 id="phpxmlrpcdecode">
3176         <title>php_xmlrpc_decode</title>
3177
3178         <funcsynopsis>
3179           <funcprototype>
3180             <funcdef><type>mixed</type><function>php_xmlrpc_decode</function></funcdef>
3181
3182             <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
3183
3184             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3185           </funcprototype>
3186
3187           <funcprototype>
3188             <funcdef><type>array</type><function>php_xmlrpc_decode</function></funcdef>
3189
3190             <paramdef><type>xmlrpcmsg</type><parameter>$xmlrpcmsg_val</parameter></paramdef>
3191
3192             <paramdef><type>string</type><parameter>$options</parameter></paramdef>
3193           </funcprototype>
3194         </funcsynopsis>
3195
3196         <para>Returns a native PHP value corresponding to the values found in
3197         the <type>xmlrpcval</type> <parameter>$xmlrpc_val</parameter>,
3198         translated into PHP types. Base-64 and datetime values are
3199         automatically decoded to strings.</para>
3200
3201         <para>In the second form, returns an array containing the parameters
3202         of the given
3203         <parameter><classname>xmlrpcmsg</classname>_val</parameter>, decoded
3204         to php types.</para>
3205
3206         <para>The <parameter>options</parameter> parameter is optional. If
3207         specified, it must consist of an array of options to be enabled in the
3208         decoding process. At the moment the only valid option is
3209         <symbol>decode_php_objs</symbol>. When it is set, php objects that
3210         have been converted to xml-rpc structs using the
3211         <function>php_xmlrpc_encode</function> function and a corresponding
3212         encoding option will be converted back into object values instead of
3213         arrays (provided that the class definition is available at
3214         reconstruction time).</para>
3215
3216         <para><emphasis><emphasis>WARNING</emphasis>:</emphasis> please take
3217         extreme care before enabling the <symbol>decode_php_objs</symbol>
3218         option: when php objects are rebuilt from the received xml, their
3219         constructor function will be silently invoked. This means that you are
3220         allowing the remote end to trigger execution of uncontrolled PHP code
3221         on your server, opening the door to code injection exploits. Only
3222         enable this option when you have complete trust of the remote
3223         server/client.</para>
3224
3225         <para>Example:<programlisting language="php">
3226 // wrapper to expose an existing php function as xmlrpc method handler
3227 function foo_wrapper($m)
3228 {
3229   $params = php_xmlrpc_decode($m);
3230   $retval = call_user_func_array('foo', $params);
3231   return new xmlrpcresp(new xmlrpcval($retval)); // foo return value will be serialized as string
3232 }
3233
3234 $s = new xmlrpc_server(array(
3235    "examples.myFunc1" =&gt; array(
3236      "function" =&gt; "foo_wrapper",
3237      "signatures" =&gt; ...
3238   )));
3239 </programlisting></para>
3240       </sect2>
3241
3242       <sect2 id="phpxmlrpcencode">
3243         <title>php_xmlrpc_encode</title>
3244
3245         <funcsynopsis>
3246           <funcprototype>
3247             <funcdef><type>xmlrpcval</type><function>php_xmlrpc_encode</function></funcdef>
3248
3249             <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
3250
3251             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3252           </funcprototype>
3253         </funcsynopsis>
3254
3255         <para>Returns an <type>xmlrpcval</type> object populated with the PHP
3256         values in <parameter>$phpval</parameter>. Works recursively on arrays
3257         and objects, encoding numerically indexed php arrays into array-type
3258         xmlrpcval objects and non numerically indexed php arrays into
3259         struct-type xmlrpcval objects. Php objects are encoded into
3260         struct-type xmlrpcvals, excepted for php values that are already
3261         instances of the xmlrpcval class or descendants thereof, which will
3262         not be further encoded. Note that there's no support for encoding php
3263         values into base-64 values. Encoding of date-times is optionally
3264         carried on on php strings with the correct format.</para>
3265
3266         <para>The <parameter>options</parameter> parameter is optional. If
3267         specified, it must consist of an array of options to be enabled in the
3268         encoding process. At the moment the only valid options are
3269         <symbol>encode_php_objs</symbol> and
3270         <symbol>auto_dates</symbol>.</para>
3271
3272         <para>The first will enable the creation of 'particular' xmlrpcval
3273         objects out of php objects, that add a "php_class" xml attribute to
3274         their serialized representation. This attribute allows the function
3275         php_xmlrpc_decode to rebuild the native php objects (provided that the
3276         same class definition exists on both sides of the
3277         communication)</para>
3278
3279         <para>Example:<programlisting language="php">
3280 // the easy way to build a complex xml-rpc struct, showing nested base64 value and datetime values
3281 $val = php_xmlrpc_encode(array(
3282   'first struct_element: an int' =&gt; 666,
3283   'second: an array' =&gt; array ('apple', 'orange', 'banana'),
3284   'third: a base64 element' =&gt; new xmlrpcval('hello world', 'base64'),
3285   'fourth: a datetime' =&gt; '20060107T01:53:00'
3286   ), array('auto_dates'));
3287 </programlisting></para>
3288       </sect2>
3289
3290       <sect2>
3291         <title>php_xmlrpc_decode_xml</title>
3292
3293         <funcsynopsis>
3294           <funcprototype>
3295             <funcdef><type>xmlrpcval | xmlrpcresp |
3296             xmlrpcmsg</type><function>php_xmlrpc_decode_xml</function></funcdef>
3297
3298             <paramdef><type>string</type><parameter>$xml</parameter></paramdef>
3299
3300             <paramdef><type>array</type><parameter>$options</parameter></paramdef>
3301           </funcprototype>
3302         </funcsynopsis>
3303
3304         <para>Decodes the xml representation of either an xmlrpc request,
3305         response or single value, returning the corresponding php-xmlrpc
3306         object, or <literal>FALSE</literal> in case of an error.</para>
3307
3308         <para>The <parameter>options</parameter> parameter is optional. If
3309         specified, it must consist of an array of options to be enabled in the
3310         decoding process. At the moment, no option is supported.</para>
3311
3312         <para>Example:<programlisting language="php">
3313 $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;';
3314 $val = php_xmlrpc_decode_xml($text);
3315 if ($val) echo 'Found a value of type '.$val-&gt;kindOf(); else echo 'Found invalid xml';
3316 </programlisting></para>
3317       </sect2>
3318     </sect1>
3319
3320     <sect1>
3321       <title>Automatic conversion of php functions into xmlrpc methods (and
3322       vice versa)</title>
3323
3324       <para>For the extremely lazy coder, helper functions have been added
3325       that allow to convert a php function into an xmlrpc method, and a
3326       remotely exposed xmlrpc method into a local php function - or a set of
3327       methods into a php class. Note that these comes with many caveat.</para>
3328
3329       <sect2>
3330         <title>wrap_xmlrpc_method</title>
3331
3332         <funcsynopsis>
3333           <funcprototype>
3334             <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
3335
3336             <paramdef>$client</paramdef>
3337
3338             <paramdef>$methodname</paramdef>
3339
3340             <paramdef>$extra_options</paramdef>
3341           </funcprototype>
3342
3343           <funcprototype>
3344             <funcdef><type>string</type><function>wrap_xmlrpc_method</function></funcdef>
3345
3346             <paramdef>$client</paramdef>
3347
3348             <paramdef>$methodname</paramdef>
3349
3350             <paramdef>$signum</paramdef>
3351
3352             <paramdef>$timeout</paramdef>
3353
3354             <paramdef>$protocol</paramdef>
3355
3356             <paramdef>$funcname</paramdef>
3357           </funcprototype>
3358         </funcsynopsis>
3359
3360         <para>Given an xmlrpc server and a method name, creates a php wrapper
3361         function that will call the remote method and return results using
3362         native php types for both params and results. The generated php
3363         function will return an xmlrpcresp object for failed xmlrpc
3364         calls.</para>
3365
3366         <para>The second syntax is deprecated, and is listed here only for
3367         backward compatibility.</para>
3368
3369         <para>The server must support the
3370         <methodname>system.methodSignature</methodname> xmlrpc method call for
3371         this function to work.</para>
3372
3373         <para>The <parameter>client</parameter> param must be a valid
3374         xmlrpc_client object, previously created with the address of the
3375         target xmlrpc server, and to which the preferred communication options
3376         have been set.</para>
3377
3378         <para>The optional parameters can be passed as array key,value pairs
3379         in the <parameter>extra_options</parameter> param.</para>
3380
3381         <para>The <parameter>signum</parameter> optional param has the purpose
3382         of indicating which method signature to use, if the given server
3383         method has multiple signatures (defaults to 0).</para>
3384
3385         <para>The <parameter>timeout</parameter> and
3386         <parameter>protocol</parameter> optional params are the same as in the
3387         <methodname>xmlrpc_client::send()</methodname> method.</para>
3388
3389         <para>If set, the optional <parameter>new_function_name</parameter>
3390         parameter indicates which name should be used for the generated
3391         function. In case it is not set the function name will be
3392         auto-generated.</para>
3393
3394         <para>If the <literal>return_source</literal> optional parameter is
3395         set, the function will return the php source code to build the wrapper
3396         function, instead of evaluating it (useful to save the code and use it
3397         later as stand-alone xmlrpc client).</para>
3398
3399         <para>If the <literal>encode_php_objs</literal> optional parameter is
3400         set, instances of php objects later passed as parameters to the newly
3401         created function will receive a 'special' treatment that allows the
3402         server to rebuild them as php objects instead of simple arrays. Note
3403         that this entails using a "slightly augmented" version of the xmlrpc
3404         protocol (ie. using element attributes), which might not be understood
3405         by xmlrpc servers implemented using other libraries.</para>
3406
3407         <para>If the <literal>decode_php_objs</literal> optional parameter is
3408         set, instances of php objects that have been appropriately encoded by
3409         the server using a coordinate option will be deserialized as php
3410         objects instead of simple arrays (the same class definition should be
3411         present server side and client side).</para>
3412
3413         <para><emphasis>Note that this might pose a security risk</emphasis>,
3414         since in order to rebuild the object instances their constructor
3415         method has to be invoked, and this means that the remote server can
3416         trigger execution of unforeseen php code on the client: not really a
3417         code injection, but almost. Please enable this option only when you
3418         trust the remote server.</para>
3419
3420         <para>In case of an error during generation of the wrapper function,
3421         FALSE is returned, otherwise the name (or source code) of the new
3422         function.</para>
3423
3424         <para>Known limitations: server must support
3425         <methodname>system.methodsignature</methodname> for the wanted xmlrpc
3426         method; for methods that expose multiple signatures, only one can be
3427         picked; for remote calls with nested xmlrpc params, the caller of the
3428         generated php function has to encode on its own the params passed to
3429         the php function if these are structs or arrays whose (sub)members
3430         include values of type base64.</para>
3431
3432         <para>Note: calling the generated php function 'might' be slow: a new
3433         xmlrpc client is created on every invocation and an xmlrpc-connection
3434         opened+closed. An extra 'debug' param is appended to the parameter
3435         list of the generated php function, useful for debugging
3436         purposes.</para>
3437
3438         <para>Example usage:</para>
3439
3440         <programlisting language="php">
3441 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
3442
3443 $function = wrap_xmlrpc_method($client, 'examples.getStateName');
3444
3445 if (!$function)
3446   die('Cannot introspect remote method');
3447 else {
3448   $stateno = 15;
3449   $statename = $function($a);
3450   if (is_a($statename, 'xmlrpcresp')) // call failed
3451   {
3452     echo 'Call failed: '.$statename-&gt;faultCode().'. Calling again with debug on';
3453     $function($a, true);
3454   }
3455   else
3456     echo "OK, state nr. $stateno is $statename";
3457 }
3458 </programlisting>
3459       </sect2>
3460
3461       <sect2 id="wrap_php_function">
3462         <title>wrap_php_function</title>
3463
3464         <funcsynopsis>
3465           <funcprototype>
3466             <funcdef><type>array</type><function>wrap_php_function</function></funcdef>
3467
3468             <paramdef><type>string</type><parameter>$funcname</parameter></paramdef>
3469
3470             <paramdef><type>string</type><parameter>$wrapper_function_name</parameter></paramdef>
3471
3472             <paramdef><type>array</type><parameter>$extra_options</parameter></paramdef>
3473           </funcprototype>
3474         </funcsynopsis>
3475
3476         <para>Given a user-defined PHP function, create a PHP 'wrapper'
3477         function that can be exposed as xmlrpc method from an xmlrpc_server
3478         object and called from remote clients, and return the appropriate
3479         definition to be added to a server's dispatch map.</para>
3480
3481         <para>The optional <parameter>$wrapper_function_name</parameter>
3482         specifies the name that will be used for the auto-generated
3483         function.</para>
3484
3485         <para>Since php is a typeless language, to infer types of input and
3486         output parameters, it relies on parsing the javadoc-style comment
3487         block associated with the given function. Usage of xmlrpc native types
3488         (such as datetime.dateTime.iso8601 and base64) in the docblock @param
3489         tag is also allowed, if you need the php function to receive/send data
3490         in that particular format (note that base64 encoding/decoding is
3491         transparently carried out by the lib, while datetime vals are passed
3492         around as strings).</para>
3493
3494         <para>Known limitations: requires PHP 5.0.3 +; only works for
3495         user-defined functions, not for PHP internal functions (reflection
3496         does not support retrieving number/type of params for those); the
3497         wrapped php function will not be able to programmatically return an
3498         xmlrpc error response.</para>
3499
3500         <para>If the <literal>return_source</literal> optional parameter is
3501         set, the function will return the php source code to build the wrapper
3502         function, instead of evaluating it (useful to save the code and use it
3503         later in a stand-alone xmlrpc server). It will be in the stored in the
3504         <literal>source</literal> member of the returned array.</para>
3505
3506         <para>If the <literal>suppress_warnings</literal> optional parameter
3507         is set, any runtime warning generated while processing the
3508         user-defined php function will be catched and not be printed in the
3509         generated xml response.</para>
3510
3511         <para>If the <parameter>extra_options</parameter> array contains the
3512         <literal>encode_php_objs</literal> value, wrapped functions returning
3513         php objects will generate "special" xmlrpc responses: when the xmlrpc
3514         decoding of those responses is carried out by this same lib, using the
3515         appropriate param in php_xmlrpc_decode(), the objects will be
3516         rebuilt.</para>
3517
3518         <para>In short: php objects can be serialized, too (except for their
3519         resource members), using this function. Other libs might choke on the
3520         very same xml that will be generated in this case (i.e. it has a
3521         nonstandard attribute on struct element tags)</para>
3522
3523         <para>If the <literal>decode_php_objs</literal> optional parameter is
3524         set, instances of php objects that have been appropriately encoded by
3525         the client using a coordinate option will be deserialized and passed
3526         to the user function as php objects instead of simple arrays (the same
3527         class definition should be present server side and client
3528         side).</para>
3529
3530         <para><emphasis>Note that this might pose a security risk</emphasis>,
3531         since in order to rebuild the object instances their constructor
3532         method has to be invoked, and this means that the remote client can
3533         trigger execution of unforeseen php code on the server: not really a
3534         code injection, but almost. Please enable this option only when you
3535         trust the remote clients.</para>
3536
3537         <para>Example usage:</para>
3538
3539         <para><programlisting language="php">/**
3540 * State name from state number decoder. NB: do NOT remove this comment block.
3541 * @param integer $stateno the state number
3542 * @return string the name of the state (or error description)
3543 */
3544 function findstate($stateno)
3545 {
3546   global $stateNames;
3547   if (isset($stateNames[$stateno-1]))
3548   {
3549     return $stateNames[$stateno-1];
3550   }
3551   else
3552   {
3553     return "I don't have a state for the index '" . $stateno . "'";
3554   }
3555 }
3556
3557 // wrap php function, build xmlrpc server
3558 $methods = array();
3559 $findstate_sig = wrap_php_function('findstate');
3560 if ($findstate_sig)
3561   $methods['examples.getStateName'] = $findstate_sig;
3562 $srv = new xmlrpc_server($methods);
3563 </programlisting></para>
3564       </sect2>
3565     </sect1>
3566
3567     <sect1 id="deprecated">
3568       <title>Functions removed from the library</title>
3569
3570       <para>The following two functions have been deprecated in version 1.1 of
3571       the library, and removed in version 2, in order to avoid conflicts with
3572       the EPI xml-rpc library, which also defines two functions with the same
3573       names.</para>
3574
3575       <para>To ease the transition to the new naming scheme and avoid breaking
3576       existing implementations, the following scheme has been adopted:
3577       <itemizedlist>
3578           <listitem>
3579             <para>If EPI-XMLRPC is not active in the current PHP installation,
3580             the constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
3581             <literal>'0'</literal></para>
3582           </listitem>
3583
3584           <listitem>
3585             <para>If EPI-XMLRPC is active in the current PHP installation, the
3586             constant <literal>XMLRPC_EPI_ENABLED</literal> will be set to
3587             <literal>'1'</literal></para>
3588           </listitem>
3589         </itemizedlist></para>
3590
3591       <para>The following documentation is kept for historical
3592       reference:</para>
3593
3594       <sect2 id="xmlrpcdecode">
3595         <title>xmlrpc_decode</title>
3596
3597         <funcsynopsis>
3598           <funcprototype>
3599             <funcdef><type>mixed</type><function>xmlrpc_decode</function></funcdef>
3600
3601             <paramdef><type>xmlrpcval</type><parameter>$xmlrpc_val</parameter></paramdef>
3602           </funcprototype>
3603         </funcsynopsis>
3604
3605         <para>Alias for php_xmlrpc_decode.</para>
3606       </sect2>
3607
3608       <sect2 id="xmlrpcencode">
3609         <title>xmlrpc_encode</title>
3610
3611         <funcsynopsis>
3612           <funcprototype>
3613             <funcdef><type>xmlrpcval</type><function>xmlrpc_encode</function></funcdef>
3614
3615             <paramdef><type>mixed</type><parameter>$phpval</parameter></paramdef>
3616           </funcprototype>
3617         </funcsynopsis>
3618
3619         <para>Alias for php_xmlrpc_encode.</para>
3620       </sect2>
3621     </sect1>
3622
3623     <sect1 id="debugging">
3624       <title>Debugging aids</title>
3625
3626       <sect2>
3627         <title>xmlrpc_debugmsg</title>
3628
3629         <funcsynopsis>
3630           <funcprototype>
3631             <funcdef><type>void</type><function>xmlrpc_debugmsg</function></funcdef>
3632
3633             <paramdef><type>string</type><parameter>$debugstring</parameter></paramdef>
3634           </funcprototype>
3635         </funcsynopsis>
3636
3637         <para>Sends the contents of <parameter>$debugstring</parameter> in XML
3638         comments in the server return payload. If a PHP client has debugging
3639         turned on, the user will be able to see server debug
3640         information.</para>
3641
3642         <para>Use this function in your methods so you can pass back
3643         diagnostic information. It is only available from
3644         <filename>xmlrpcs.inc</filename>.</para>
3645       </sect2>
3646     </sect1>
3647   </chapter>
3648
3649   <chapter id="reserved" xreflabel="Reserved methods">
3650     <title>Reserved methods</title>
3651
3652     <para>In order to extend the functionality offered by XML-RPC servers
3653     without impacting on the protocol, reserved methods are supported in this
3654     release.</para>
3655
3656     <para>All methods starting with <function>system.</function> are
3657     considered reserved by the server. PHP for XML-RPC itself provides four
3658     special methods, detailed in this chapter.</para>
3659
3660     <para>Note that all server objects will automatically respond to clients
3661     querying these methods, unless the property
3662     <property>allow_system_funcs</property> has been set to
3663     <constant>false</constant> before calling the
3664     <methodname>service()</methodname> method. This might pose a security risk
3665     if the server is exposed to public access, e.g. on the internet.</para>
3666
3667     <sect1>
3668       <title>system.getCapabilities</title>
3669
3670       <para></para>
3671     </sect1>
3672
3673     <sect1>
3674       <title>system.listMethods</title>
3675
3676       <para>This method may be used to enumerate the methods implemented by
3677       the XML-RPC server.</para>
3678
3679       <para>The <function>system.listMethods</function> method requires no
3680       parameters. It returns an array of strings, each of which is the name of
3681       a method implemented by the server.</para>
3682     </sect1>
3683
3684     <sect1 id="sysmethodsig">
3685       <title>system.methodSignature</title>
3686
3687       <para>This method takes one parameter, the name of a method implemented
3688       by the XML-RPC server.</para>
3689
3690       <para>It returns an array of possible signatures for this method. A
3691       signature is an array of types. The first of these types is the return
3692       type of the method, the rest are parameters.</para>
3693
3694       <para>Multiple signatures (i.e. overloading) are permitted: this is the
3695       reason that an array of signatures are returned by this method.</para>
3696
3697       <para>Signatures themselves are restricted to the top level parameters
3698       expected by a method. For instance if a method expects one array of
3699       structs as a parameter, and it returns a string, its signature is simply
3700       "string, array". If it expects three integers, its signature is "string,
3701       int, int, int".</para>
3702
3703       <para>For parameters that can be of more than one type, the "undefined"
3704       string is supported.</para>
3705
3706       <para>If no signature is defined for the method, a not-array value is
3707       returned. Therefore this is the way to test for a non-signature, if
3708       <parameter>$resp</parameter> below is the response object from a method
3709       call to <function>system.methodSignature</function>:</para>
3710
3711       <programlisting language="php">
3712 $v = $resp-&gt;value();
3713 if ($v-&gt;kindOf() != "array") {
3714   // then the method did not have a signature defined
3715 }
3716 </programlisting>
3717
3718       <para>See the <filename>introspect.php</filename> demo included in this
3719       distribution for an example of using this method.</para>
3720     </sect1>
3721
3722     <sect1 id="sysmethhelp">
3723       <title>system.methodHelp</title>
3724
3725       <para>This method takes one parameter, the name of a method implemented
3726       by the XML-RPC server.</para>
3727
3728       <para>It returns a documentation string describing the use of that
3729       method. If no such string is available, an empty string is
3730       returned.</para>
3731
3732       <para>The documentation string may contain HTML markup.</para>
3733     </sect1>
3734
3735     <sect1>
3736       <title>system.multicall</title>
3737
3738       <para>This method takes one parameter, an array of 'request' struct
3739       types. Each request struct must contain a
3740       <parameter>methodName</parameter> member of type string and a
3741       <parameter>params</parameter> member of type array, and corresponds to
3742       the invocation of the corresponding method.</para>
3743
3744       <para>It returns a response of type array, with each value of the array
3745       being either an error struct (containing the faultCode and faultString
3746       members) or the successful response value of the corresponding single
3747       method call.</para>
3748     </sect1>
3749   </chapter>
3750
3751   <chapter id="examples" xreflabel="Examples">
3752     <title>Examples</title>
3753
3754     <para>The best examples are to be found in the sample files included with
3755     the distribution. Some are included here.</para>
3756
3757     <sect1 id="statename">
3758       <title>XML-RPC client: state name query</title>
3759
3760       <para>Code to get the corresponding state name from a number (1-50) from
3761       the demo server available on SourceForge</para>
3762
3763       <programlisting language="php">
3764   $m = new xmlrpcmsg('examples.getStateName',
3765     array(new xmlrpcval($HTTP_POST_VARS["stateno"], "int")));
3766   $c = new xmlrpc_client("/server.php", "phpxmlrpc.sourceforge.net", 80);
3767   $r = $c-&gt;send($m);
3768   if (!$r-&gt;faultCode()) {
3769       $v = $r-&gt;value();
3770       print "State number " . htmlentities($HTTP_POST_VARS["stateno"]) . " is " .
3771         htmlentities($v-&gt;scalarval()) . "&lt;BR&gt;";
3772       print "&lt;HR&gt;I got this value back&lt;BR&gt;&lt;PRE&gt;" .
3773         htmlentities($r-&gt;serialize()) . "&lt;/PRE&gt;&lt;HR&gt;\n";
3774   } else {
3775       print "Fault &lt;BR&gt;";
3776       print "Code: " . htmlentities($r-&gt;faultCode()) . "&lt;BR&gt;" .
3777             "Reason: '" . htmlentities($r-&gt;faultString()) . "'&lt;BR&gt;";
3778   }
3779 </programlisting>
3780     </sect1>
3781
3782     <sect1>
3783       <title>Executing a multicall call</title>
3784
3785       <para>To be documented...</para>
3786     </sect1>
3787   </chapter>
3788
3789   <chapter id="faq">
3790     <title>Frequently Asked Questions</title>
3791
3792     <sect1>
3793       <title>How to send custom XML as payload of a method call</title>
3794
3795       <para>Unfortunately, at the time the XML-RPC spec was designed, support
3796       for namespaces in XML was not as ubiquitous as it is now. As a
3797       consequence, no support was provided in the protocol for embedding XML
3798       elements from other namespaces into an xmlrpc request.</para>
3799
3800       <para>To send an XML "chunk" as payload of a method call or response,
3801       two options are available: either send the complete XML block as a
3802       string xmlrpc value, or as a base64 value. Since the '&lt;' character in
3803       string values is encoded as '&amp;lt;' in the xml payload of the method
3804       call, the XML string will not break the surrounding xmlrpc, unless
3805       characters outside of the assumed character set are used. The second
3806       method has the added benefits of working independently of the charset
3807       encoding used for the xml to be transmitted, and preserving exactly
3808       whitespace, whilst incurring in some extra message length and cpu load
3809       (for carrying out the base64 encoding/decoding).</para>
3810     </sect1>
3811
3812     <sect1>
3813       <title>Is there any limitation on the size of the requests / responses
3814       that can be successfully sent?</title>
3815
3816       <para>Yes. But I have no hard figure to give; it most likely will depend
3817       on the version of PHP in usage and its configuration.</para>
3818
3819       <para>Keep in mind that this library is not optimized for speed nor for
3820       memory usage. Better alternatives exist when there are strict
3821       requirements on throughput or resource usage, such as the php native
3822       xmlrpc extension (see the PHP manual for more information).</para>
3823
3824       <para>Keep in mind also that HTTP is probably not the best choice in
3825       such a situation, and XML is a deadly enemy. CSV formatted data over
3826       socket would be much more efficient.</para>
3827
3828       <para>If you really need to move a massive amount of data around, and
3829       you are crazy enough to do it using phpxmlrpc, your best bet is to
3830       bypass usage of the xmlrpcval objects, at least in the decoding phase,
3831       and have the server (or client) object return to the calling function
3832       directly php values (see <varname>xmlrpc_client::return_type</varname>
3833       and <varname>xmlrpc_server::functions_parameters_type</varname> for more
3834       details).</para>
3835     </sect1>
3836
3837     <sect1>
3838       <title>My server (client) returns an error whenever the client (server)
3839       returns accented characters</title>
3840
3841       <para>To be documented...</para>
3842     </sect1>
3843
3844     <sect1>
3845       <title>My php error log is getting full of "deprecated" errors on
3846       different lines of xmlrpc.inc and xmlrpcs.inc</title>
3847
3848       <para>This happens when the PHP in usage is version 5, and the error
3849       reporting level is set to include <constant>E_STRICT</constant> errors.
3850       Since the main development platform of the library remains (for the time
3851       being) PHP 4, there are no plans to fix this asap. The best workaround
3852       is to set the error reporting level to <constant>E_ALL ^
3853       E_STRICT</constant>.</para>
3854     </sect1>
3855
3856     <sect1>
3857       <title>How to enable long-lasting method calls</title>
3858
3859       <para>To be documented...</para>
3860     </sect1>
3861
3862     <sect1>
3863       <title>My client returns "XML-RPC Fault #2: Invalid return payload:
3864       enable debugging to examine incoming payload": what should I do?</title>
3865
3866       <para>The response you are seeing is a default error response that the
3867       client object returns to the php application when the server did not
3868       respond to the call with a valid xmlrpc response.</para>
3869
3870       <para>The most likely cause is that you are not using the correct URL
3871       when creating the client object, or you do not have appropriate access
3872       rights to the web page you are requesting, or some other common http
3873       misconfiguration.</para>
3874
3875       <para>To find out what the server is really returning to your client,
3876       you have to enable the debug mode of the client, using
3877       $client-&gt;setdebug(1);</para>
3878     </sect1>
3879
3880     <sect1>
3881       <title>How can I save to a file the xml of the xmlrpc responses received
3882       from servers?</title>
3883
3884       <para>If what you need is to save the responses received from the server
3885       as xml, you have two options:</para>
3886
3887       <para>1- use the serialize() method on the response object.</para>
3888
3889       <programlisting language="php">
3890 $resp = $client-&gt;send($msg);
3891 if (!$resp-&gt;faultCode())
3892   $data_to_be_saved = $resp-&gt;serialize();
3893 </programlisting>
3894
3895       <para>Note that this will not be 100% accurate, since the xml generated
3896       by the response object can be different from the xml received,
3897       especially if there is some character set conversion involved, or such
3898       (eg. if you receive an empty string tag as &lt;string/&gt;, serialize()
3899       will output &lt;string&gt;&lt;/string&gt;), or if the server sent back
3900       as response something invalid (in which case the xml generated client
3901       side using serialize() will correspond to the error response generated
3902       internally by the lib).</para>
3903
3904       <para>2 - set the client object to return the raw xml received instead
3905       of the decoded objects:</para>
3906
3907       <programlisting language="php">
3908 $client = new xmlrpc_client($url);
3909 $client-&gt;return_type = 'xml';
3910 $resp = $client-&gt;send($msg);
3911 if (!$resp-&gt;faultCode())
3912   $data_to_be_saved = $resp-&gt;value();
3913 </programlisting>
3914
3915       <para>Note that using this method the xml response response will not be
3916       parsed at all by the library, only the http communication protocol will
3917       be checked. This means that xmlrpc responses sent by the server that
3918       would have generated an error response on the client (eg. malformed xml,
3919       responses that have faultcode set, etc...) now will not be flagged as
3920       invalid, and you might end up saving not valid xml but random
3921       junk...</para>
3922     </sect1>
3923
3924     <sect1>
3925       <title>Can I use the ms windows character set?</title>
3926
3927       <para>If the data your application is using comes from a Microsoft
3928       application, there are some chances that the character set used to
3929       encode it is CP1252 (the same might apply to data received from an
3930       external xmlrpc server/client, but it is quite rare to find xmlrpc
3931       toolkits that encode to CP1252 instead of UTF8). It is a character set
3932       which is "almost" compatible with ISO 8859-1, but for a few extra
3933       characters.</para>
3934
3935       <para>PHP-XMLRPC only supports the ISO 8859-1 and UTF8 character sets.
3936       The net result of this situation is that those extra characters will not
3937       be properly encoded, and will be received at the other end of the
3938       XML-RPC tranmission as "garbled data". Unfortunately the library cannot
3939       provide real support for CP1252 because of limitations in the PHP 4 xml
3940       parser. Luckily, we tried our best to support this character set anyway,
3941       and, since version 2.2.1, there is some form of support, left commented
3942       in the code.</para>
3943
3944       <para>To properly encode outgoing data that is natively in CP1252, you
3945       will have to uncomment all relative code in the file
3946       <filename>xmlrpc.inc</filename> (you can search for the string "1252"),
3947       then set <code>$GLOBALS['xmlrpc_internalencoding']='CP1252';</code>
3948       Please note that all incoming data will then be fed to your application
3949       as UTF-8 to avoid any potentail data loss.</para>
3950     </sect1>
3951
3952     <sect1>
3953       <title>Does the library support using cookies / http sessions?</title>
3954
3955       <para>In short: yes, but a little coding is needed to make it
3956       happen.</para>
3957
3958       <para>The code below uses sessions to e.g. let the client store a value
3959       on the server and retrieve it later.</para>
3960
3961       <para><programlisting>
3962 $resp = $client-&gt;send(new xmlrpcmsg('registervalue', array(new xmlrpcval('foo'), new xmlrpcval('bar'))));
3963 if (!$resp-&gt;faultCode())
3964 {
3965   $cookies = $resp-&gt;cookies();
3966   if (array_key_exists('PHPSESSID', $cookies)) // nb: make sure to use the correct session cookie name
3967   {
3968     $session_id = $cookies['PHPSESSID']['value'];
3969
3970     // do some other stuff here...
3971
3972     $client-&gt;setcookie('PHPSESSID', $session_id);
3973     $val = $client-&gt;send(new xmlrpcmsg('getvalue', array(new xmlrpcval('foo')));
3974   }
3975 }
3976 </programlisting>Server-side sessions are handled normally like in any other
3977       php application. Please see the php manual for more information about
3978       sessions.</para>
3979
3980       <para>NB: unlike web browsers, not all xmlrpc clients support usage of
3981       http cookies. If you have troubles with sessions and control only the
3982       server side of the communication, please check with the makers of the
3983       xmlrpc client in use.</para>
3984     </sect1>
3985   </chapter>
3986
3987   <appendix id="integration">
3988     <title>Integration with the PHP xmlrpc extension</title>
3989
3990     <para>To be documented more...</para>
3991
3992     <para>In short: for the fastest execution possible, you can enable the php
3993     native xmlrpc extension, and use it in conjunction with phpxmlrpc. The
3994     following code snippet gives an example of such integration</para>
3995
3996     <programlisting language="php">
3997 /*** client side ***/
3998 $c = new xmlrpc_client('http://phpxmlrpc.sourceforge.net/server.php');
3999
4000 // tell the client to return raw xml as response value
4001 $c-&gt;return_type = 'xml';
4002
4003 // let the native xmlrpc extension take care of encoding request parameters
4004 $r = $c-&gt;send(xmlrpc_encode_request('examples.getStateName', $_POST['stateno']));
4005
4006 if ($r-&gt;faultCode())
4007   // HTTP transport error
4008   echo 'Got error '.$r-&gt;faultCode();
4009 else
4010 {
4011   // HTTP request OK, but XML returned from server not parsed yet
4012   $v = xmlrpc_decode($r-&gt;value());
4013   // check if we got a valid xmlrpc response from server
4014   if ($v === NULL)
4015     echo 'Got invalid response';
4016   else
4017   // check if server sent a fault response
4018   if (xmlrpc_is_fault($v))
4019     echo 'Got xmlrpc fault '.$v['faultCode'];
4020   else
4021     echo'Got response: '.htmlentities($v);
4022 }
4023 </programlisting>
4024   </appendix>
4025
4026   <appendix id="substitution">
4027     <title>Substitution of the PHP xmlrpc extension</title>
4028
4029     <para>Yet another interesting situation is when you are using a ready-made
4030     php application, that provides support for the XMLRPC protocol via the
4031     native php xmlrpc extension, but the extension is not available on your
4032     php install (e.g. because of shared hosting constraints).</para>
4033
4034     <para>Since version 2.1, the PHP-XMLRPC library provides a compatibility
4035     layer that aims to be 100% compliant with the xmlrpc extension API. This
4036     means that any code written to run on the extension should obtain the
4037     exact same results, albeit using more resources and a longer processing
4038     time, using the PHP-XMLRPC library and the extension compatibility module.
4039     The module is part of the EXTRAS package, available as a separate download
4040     from the sourceforge.net website, since version 0.2</para>
4041   </appendix>
4042
4043   <appendix id="enough">
4044     <title>'Enough of xmlrpcvals!': new style library usage</title>
4045
4046     <para>To be documented...</para>
4047
4048     <para>In the meantime, see docs about xmlrpc_client::return_type and
4049     xmlrpc_server::functions_parameters_types, as well as php_xmlrpc_encode,
4050     php_xmlrpc_decode and php_xmlrpc_decode_xml</para>
4051   </appendix>
4052
4053   <appendix id="debugger">
4054     <title>Usage of the debugger</title>
4055
4056     <para>A webservice debugger is included in the library to help during
4057     development and testing.</para>
4058
4059     <para>The interface should be self-explicative enough to need little
4060     documentation.</para>
4061
4062     <para><graphic align="center" fileref="debugger.gif"
4063     format="GIF" /></para>
4064
4065     <para>The most useful feature of the debugger is without doubt the "Show
4066     debug info" option. It allows to have a screen dump of the complete http
4067     communication between client and server, including the http headers as
4068     well as the request and response payloads, and is invaluable when
4069     troubleshooting problems with charset encoding, authentication or http
4070     compression.</para>
4071
4072     <para>The debugger can take advantage of the JSONRPC library extension, to
4073     allow debugging of JSON-RPC webservices, and of the JS-XMLRPC library
4074     visual editor to allow easy mouse-driven construction of the payload for
4075     remote methods. Both components have to be downloaded separately from the
4076     sourceforge.net web pages and copied to the debugger directory to enable
4077     the extra functionality:</para>
4078
4079     <para><itemizedlist>
4080         <listitem>
4081           <para>to enable jsonrpc functionality, download the PHP-XMLRPC
4082           EXTRAS package, and copy the file <filename>jsonrpc.inc</filename>
4083           either to the same directory as the debugger or somewhere in your
4084           php include path</para>
4085         </listitem>
4086       </itemizedlist><itemizedlist>
4087         <listitem>
4088           <para>to enable the visual value editing dialog, download the
4089           JS-XMLRPC library, and copy somewhere in the web root files
4090           <filename>visualeditor.php</filename>,
4091           <filename>visualeditor.css</filename> and the folders
4092           <filename>yui</filename> and <filename>img</filename>. Then edit the
4093           debugger file <filename>controller.php</filename> and set
4094           appropriately the variable <varname>$editorpath</varname>.</para>
4095         </listitem>
4096       </itemizedlist></para>
4097   </appendix>
4098 </book>
4099 <!-- Keep this comment at the end of the file
4100 Local variables:
4101 mode: sgml
4102 sgml-omittag:nil
4103 sgml-shorttag:t
4104 sgml-minimize-attributes:nil
4105 sgml-always-quote-attributes:t
4106 sgml-indent-step:2
4107 sgml-indent-data:t
4108 sgml-parent-document:nil
4109 sgml-exposed-tags:nil
4110 sgml-local-catalogs:nil
4111 sgml-local-ecat-files:nil
4112 sgml-namecase-general:t
4113 sgml-general-insert-case:lower
4114 End:
4115 -->