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