[Sommaire] [Imprimer]

   1  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2  
   3  <html>
   4  <head>
   5      <title>XML-RPC Message Builder</title>
   6    
   7    <style type="text/css">
   8    .code {
   9      font-family:courier,monospace;
  10      font-size:12px;
  11    }
  12    body,td {
  13      font-family: verdana;
  14      font-size:12px;
  15    }
  16    h2 {
  17      border-bottom:1px solid #c0c0c0;
  18    }
  19    </style>
  20    
  21  </head>
  22  
  23  <body>
  24  <p><a href="http://www.scottandrew.com">s c o t t a n d r e w . c o m</a></p>
  25  <p><i>Last updated: 08/20/2001</i></p>
  26  
  27  <h2>What is this?</h2>
  28  <p>It's an XML-RPC message builder, written in JavaScript.  It takes JavaScript data objects and converts them into an XML-RPC message.</p>
  29  <p>There are actually two components available here.  One is the message builder, the other a PHP gateway called <strong>xmlrpc-socket</strong> that forwards XML-RPC requests to remote servers over the Internet. Together they turn your browser into an XML-RPC client.</p>
  30  
  31  <p>You can see a live demo of it <a href="test-rs.html">here</a>.</p>
  32  
  33  <p>Download the library <a href="#rpc-download">here</a>.</p>
  34  
  35  <p>You can read more about the XML-RPC specification <a href="http://www.xmlrpc.com">here</a>.</p>
  36  
  37  <p><a href="mailto:xmlrpc@scottandrew.com">Comments?</a></p>
  38  
  39  <p>
  40  <ol>
  41  <li><a href="#rpc-create">Creating an XML-RPC Message</a></li>
  42  <ol type="A">
  43  <li><a href="#rpc-methods">Object Methods</a></li>
  44  <li><a href="#rpc-dtypes">Supported Data Types</a></li>
  45  </ol>
  46  <li><a href="#rpc-sample">A Sample XML-RPC Message</a></li>
  47  <li><a href="#rpc-use">Making the Procedure Call</a></li>
  48  <ol type="A">
  49  <li><a href="#rpc-socket">Using xmlrpc-socket</a></li>
  50  </ol>
  51  <li><a href="#rpc-download">Download</a></li>
  52  </ol>
  53  </p>
  54  
  55  <a name="rpc-create"></a>
  56  <h2>Creating an XML-RPC Message</h2>
  57  
  58  <p>First, create a new instance of the XMLRPCMessage object. The syntax is:</p>
  59  
  60  <p><code>var msg = new XMLRPCMessage([string methodName]);</code></p>
  61  
  62  <p><code>methodName</code> is the name of the method you wish to call on the remote server.  This parameter is optional.  If left out, the default requested method is <code>system.listMethods</code></p>
  63  
  64  <a name="rpc-methods"></a>
  65  <h3>Object Methods</h3>
  66  <p>The XMLRPCMessage object has three methods:</p>
  67  
  68  <table cellspacing="0" cellpadding="4" border="1" width="600">
  69  <tr>
  70      <td class="code" valign="top">void addParameter(object variant)</td>
  71      <td valign="top">Accepts a JavaScript data type and adds a matching XML-RPC data type to the message</td>
  72  </tr>
  73  <tr>
  74      <td class="code" valign="top">void setMethod(string methodName)</td>
  75      <td valign="top">Declares the XML-RPC method you wish to call on the remote server.  You only need to use this if you haven't specified a method name when creating the XMLRPCMessage object.</td>
  76  </tr>
  77  <tr>
  78      <td class="code" valign="top">string xml()</td>
  79      <td valign="top">Returns a string of XML containing the message contents.</td>
  80  </tr>
  81  </table>
  82  <h3>Supported Data Types</h3>
  83  <a name="rpc-dtypes"></a>
  84  <p>The XMLRPCMessage object is designed to take any JavaScript data type and convert it into the proper XML-RPC data type.  Simply pass the JS data thingy to the <code>addParameter</code> method and it will be converted to the proper format and value.</p>
  85  
  86  <p>The following data types are supported:</p>
  87  
  88  <table cellspacing="0" cellpadding="6" border="1" width="600">
  89  <tr>
  90      <th>JavaScript Data Type</th>
  91      <th>Example</th>
  92      <th>XML-RPC equivalent</th>
  93      <th>Notes</th>
  94  </tr>
  95  <tr>
  96      <td>Boolean</td>
  97      <td>true</td>
  98      <td><xmp><boolean>1</boolean></xmp></td>
  99      <td>&nbsp;</td>
 100  </tr>
 101  <tr>
 102      <td>four-byte signed integer</td>
 103      <td>7</td>
 104      <td><xmp><i4>7</i4></xmp></td>
 105      <td>&nbsp;</td>
 106  </tr>
 107  <tr>
 108      <td>double-precision signed floating point number</td>
 109      <td>-3.14</td>
 110      <td><xmp><double>-3.14</double></xmp></td>
 111      <td>The script automagically determines whether a number is an integer or double.</td>
 112  </tr>
 113  <tr>
 114      <td>string</td>
 115      <td><xmp>"scottandrew"</xmp></td>
 116      <td>
 117  <xmp>
 118  <string>
 119   scottandrew
 120  </string>
 121  </xmp></td>
 122      <td>&nbsp;</td>
 123  </tr>
 124  <tr>
 125      <td>Date object</td>
 126      <td><xmp>d = new Date();</xmp></td>
 127      <td>
 128  <xmp>
 129  <dateTime.iso8601>
 130   20010716T18:16:18
 131  </dateTime.iso8601>
 132  </xmp></td>
 133      <td>Date objects are automatically converted into the ISO8601 format. You cannot pass date strings here; those will remain strings. Instead create a new Date object and use that.</td>
 134  </tr>
 135  <tr>
 136      <td>array</td>
 137      <td>
 138  <xmp>
 139  a = [
 140   "one",
 141   "two",
 142   "three"
 143  ];</xmp></td>
 144      <td>
 145  <xmp>
 146  <array>
 147   <data>
 148    <value>
 149     <string>one</string>
 150    </value>
 151    <value>
 152     <string>two</string>
 153    </value>
 154    <value>
 155     <string>three</string>
 156    </value>
 157   </data>
 158  </array>
 159  </xmp></td>
 160      <td rowspan="2">You don't have to worry if an Array or Object has a variety of data types as members; the script identifies the data type of each member and includes it in the message.<br /><br />Both arrays and structs can contain other arrays and structs as members, so it's possible to take a complex Object and describe it in XML by passing it to addParameter (this recursive feature is still being tested, though).</td>
 161  </tr>
 162  
 163  <tr>
 164      <td>object</td>
 165      <td>
 166  <xmp>
 167  obj = new Object();
 168  obj.a = "hello";
 169  obj.b = 7.22;
 170  obj.c = 100;
 171  </xmp></td>
 172      <td>
 173  <xmp>
 174  <struct>
 175   <member>
 176    <name>a</name>
 177    <value>
 178     <string>hello</string>
 179    </value>
 180   </member>
 181   <member>
 182    <name>b</name>
 183    <value>
 184     <double>7.22</double>
 185    </value>
 186   </member>
 187   <member>
 188    <name>c</name>
 189    <value>
 190     <i4>100</i4>
 191    </value>
 192   </member>
 193  </struct>
 194  </xmp></td>
 195  </tr>
 196  </table>
 197  
 198  <p>This library does not currently support the base64 data type.</p>
 199  
 200  <a name="rpc-sample"></a>
 201  <h2>A Sample Message</h2>
 202  <p>Here is an example of using the XMLRPCMessage object to create a message:</p>
 203  <p><pre>
 204  var a = ["chicken","duck","goose"];
 205  
 206  var obj = new Object();
 207  obj.x = 20;
 208  obj.y = "cow";
 209  obj.z = 3.14;
 210  
 211  var date = new Date();
 212  
 213  var msg = new XMLRPCMessage("system.myMethod");
 214  msg.addParameter("mississippi");
 215  msg.addParameter(7);
 216  msg.addParameter(false);
 217  msg.addParameter(a);
 218  msg.addParameter(obj);
 219  msg.addParameter(date);
 220  </pre>
 221  </p>
 222  <p>This will create the following XML-RPC message:</p>
 223  <p>
 224  <xmp>
 225  <?xml version="1.0"?>
 226  <methodCall>
 227   <methodName>system.myMethod</methodName>
 228   <params>
 229     <param>
 230     <value><string>mississippi</string></value>
 231    </param>
 232    <param>
 233     <value><i4>7</i4></value>
 234    </param>
 235    <param>
 236     <value><boolean>0</boolean></value>
 237    </param>
 238    <param>
 239     <value>
 240      <array><data>
 241       <value><string>chicken</string></value>
 242       <value><string>duck</string></value>
 243       <value><string>goose</string></value>
 244      </data></array>
 245     </value>
 246    </param>
 247    <param>
 248     <value>
 249      <struct>
 250       <member>
 251        <name>x</name>
 252        <value><i4>20</i4></value>
 253       </member>
 254       <member>
 255        <name>y</name>
 256        <value><string>cow</string></value>
 257       </member>
 258       <member>
 259        <name>z</name>
 260        <value><double>3.14</double></value>
 261       </member>
 262      </struct>
 263     </value>
 264    </param>
 265    <param>
 266     <value><dateTime.iso8601>20010720T14:48:10</dateTime.iso8601></value>
 267    </param>
 268   </params>
 269  </methodCall>
 270  </xmp>
 271  </p>
 272  
 273  <a name="rpc-use"></a>
 274  <h2>Making The Procedure Call</h2>
 275  <p>Now that you have the XML message, you need to post it to an RPC server. There are a number of ways to do this. The xmlrpc-socket PHP script allows you to post a message to a remote server and return the response as a JavaScript string to the browser.</p>
 276  
 277  <p>Depending upon your implementation, you may need to remove line breaks from, escape or otherwise encode the content of the message before posting it.</p>
 278  
 279  <p>The response is also XML-formatted.  Once you receive the response string, you can parse it or load it into a DOM object to walk through its elements.</p>
 280  
 281  <a name="rpc-socket"></a>
 282  <h3>Using xmlrpc-socket</h3>
 283  
 284  <p>xmlrpc-socket utilizes Brent Ashley's <a href="http://www.ashleyit.com/rs">JavaScript Remote Scripting</a> library to facilitate communication between the browser and the PHP script, and a modified version of Alan van den Bosch's HTTP Post utility to create the POST request from your server to a remote XML-RPC server via PHP.</p>
 285  
 286  <p>You can see it in action <a href="test-rs.html">here</a>.</p>
 287  
 288  <p>Because xmlrpc-socket serves as a proxy between your browser and the remote RPC server, it helps sidestep JavaScript security in the browser and allow the response to be returned as a JavaScript string.  What you decide to do with this string depends on your web application. xmlrpc-socket strips the header information, leaving only the XML response.</p>
 289  
 290  <a name="rpc-download"></a>
 291  <h2>Download</h2>
 292  <p>The download is avaliable as a <a href="xml-rpc.zip">ZIP file</a> (9K) which contains:</p>
 293  <ul>
 294  <li>index.html - this about page.</li>
 295  <li>xmlrpc.js - the XML-RPC message builder script</li>
 296  <li>xmlrpc-socket.php - the PHP proxy</li>
 297  <li>http_post.util - the modifed version of http_post needed by xmlrpc-socket.</li>
 298  <li>all three demo pages</li>
 299  </ul>
 300  
 301  <p>You'll also need to grab a copy of the JavaScript Remote Scripting library from <a href="http://www.ashleyit.com/rs">http://www.ashleyit.com/rs</a></p>
 302  
 303  <p><a href="mailto:xmlrpc@scottandrew.com">Comments?</a></p>
 304  <p><a href="http://www.scottandrew.com">s c o t t a n d r e w . c o m</a></p>
 305  </body>
 306  </html>