forked from extern/egroupware
307 lines
9.0 KiB
HTML
307 lines
9.0 KiB
HTML
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<title>XML-RPC Message Builder</title>
|
||
|
|
|
||
|
|
<style type="text/css">
|
||
|
|
.code {
|
||
|
|
font-family:courier,monospace;
|
||
|
|
font-size:12px;
|
||
|
|
}
|
||
|
|
body,td {
|
||
|
|
font-family: verdana;
|
||
|
|
font-size:12px;
|
||
|
|
}
|
||
|
|
h2 {
|
||
|
|
border-bottom:1px solid #c0c0c0;
|
||
|
|
}
|
||
|
|
</style>
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body>
|
||
|
|
<p><a href="http://www.scottandrew.com">s c o t t a n d r e w . c o m</a></p>
|
||
|
|
<p><i>Last updated: 08/20/2001</i></p>
|
||
|
|
|
||
|
|
<h2>What is this?</h2>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p>You can see a live demo of it <a href="test-rs.html">here</a>.</p>
|
||
|
|
|
||
|
|
<p>Download the library <a href="#rpc-download">here</a>.</p>
|
||
|
|
|
||
|
|
<p>You can read more about the XML-RPC specification <a href="http://www.xmlrpc.com">here</a>.</p>
|
||
|
|
|
||
|
|
<p><a href="mailto:xmlrpc@scottandrew.com">Comments?</a></p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<ol>
|
||
|
|
<li><a href="#rpc-create">Creating an XML-RPC Message</a></li>
|
||
|
|
<ol type="A">
|
||
|
|
<li><a href="#rpc-methods">Object Methods</a></li>
|
||
|
|
<li><a href="#rpc-dtypes">Supported Data Types</a></li>
|
||
|
|
</ol>
|
||
|
|
<li><a href="#rpc-sample">A Sample XML-RPC Message</a></li>
|
||
|
|
<li><a href="#rpc-use">Making the Procedure Call</a></li>
|
||
|
|
<ol type="A">
|
||
|
|
<li><a href="#rpc-socket">Using xmlrpc-socket</a></li>
|
||
|
|
</ol>
|
||
|
|
<li><a href="#rpc-download">Download</a></li>
|
||
|
|
</ol>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<a name="rpc-create"></a>
|
||
|
|
<h2>Creating an XML-RPC Message</h2>
|
||
|
|
|
||
|
|
<p>First, create a new instance of the XMLRPCMessage object. The syntax is:</p>
|
||
|
|
|
||
|
|
<p><code>var msg = new XMLRPCMessage([string methodName]);</code></p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<a name="rpc-methods"></a>
|
||
|
|
<h3>Object Methods</h3>
|
||
|
|
<p>The XMLRPCMessage object has three methods:</p>
|
||
|
|
|
||
|
|
<table cellspacing="0" cellpadding="4" border="1" width="600">
|
||
|
|
<tr>
|
||
|
|
<td class="code" valign="top">void addParameter(object variant)</td>
|
||
|
|
<td valign="top">Accepts a JavaScript data type and adds a matching XML-RPC data type to the message</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="code" valign="top">void setMethod(string methodName)</td>
|
||
|
|
<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>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td class="code" valign="top">string xml()</td>
|
||
|
|
<td valign="top">Returns a string of XML containing the message contents.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<h3>Supported Data Types</h3>
|
||
|
|
<a name="rpc-dtypes"></a>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p>The following data types are supported:</p>
|
||
|
|
|
||
|
|
<table cellspacing="0" cellpadding="6" border="1" width="600">
|
||
|
|
<tr>
|
||
|
|
<th>JavaScript Data Type</th>
|
||
|
|
<th>Example</th>
|
||
|
|
<th>XML-RPC equivalent</th>
|
||
|
|
<th>Notes</th>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>Boolean</td>
|
||
|
|
<td>true</td>
|
||
|
|
<td><xmp><boolean>1</boolean></xmp></td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>four-byte signed integer</td>
|
||
|
|
<td>7</td>
|
||
|
|
<td><xmp><i4>7</i4></xmp></td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>double-precision signed floating point number</td>
|
||
|
|
<td>-3.14</td>
|
||
|
|
<td><xmp><double>-3.14</double></xmp></td>
|
||
|
|
<td>The script automagically determines whether a number is an integer or double.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>string</td>
|
||
|
|
<td><xmp>"scottandrew"</xmp></td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
<string>
|
||
|
|
scottandrew
|
||
|
|
</string>
|
||
|
|
</xmp></td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>Date object</td>
|
||
|
|
<td><xmp>d = new Date();</xmp></td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
<dateTime.iso8601>
|
||
|
|
20010716T18:16:18
|
||
|
|
</dateTime.iso8601>
|
||
|
|
</xmp></td>
|
||
|
|
<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>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>array</td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
a = [
|
||
|
|
"one",
|
||
|
|
"two",
|
||
|
|
"three"
|
||
|
|
];</xmp></td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
<array>
|
||
|
|
<data>
|
||
|
|
<value>
|
||
|
|
<string>one</string>
|
||
|
|
</value>
|
||
|
|
<value>
|
||
|
|
<string>two</string>
|
||
|
|
</value>
|
||
|
|
<value>
|
||
|
|
<string>three</string>
|
||
|
|
</value>
|
||
|
|
</data>
|
||
|
|
</array>
|
||
|
|
</xmp></td>
|
||
|
|
<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>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>object</td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
obj = new Object();
|
||
|
|
obj.a = "hello";
|
||
|
|
obj.b = 7.22;
|
||
|
|
obj.c = 100;
|
||
|
|
</xmp></td>
|
||
|
|
<td>
|
||
|
|
<xmp>
|
||
|
|
<struct>
|
||
|
|
<member>
|
||
|
|
<name>a</name>
|
||
|
|
<value>
|
||
|
|
<string>hello</string>
|
||
|
|
</value>
|
||
|
|
</member>
|
||
|
|
<member>
|
||
|
|
<name>b</name>
|
||
|
|
<value>
|
||
|
|
<double>7.22</double>
|
||
|
|
</value>
|
||
|
|
</member>
|
||
|
|
<member>
|
||
|
|
<name>c</name>
|
||
|
|
<value>
|
||
|
|
<i4>100</i4>
|
||
|
|
</value>
|
||
|
|
</member>
|
||
|
|
</struct>
|
||
|
|
</xmp></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>This library does not currently support the base64 data type.</p>
|
||
|
|
|
||
|
|
<a name="rpc-sample"></a>
|
||
|
|
<h2>A Sample Message</h2>
|
||
|
|
<p>Here is an example of using the XMLRPCMessage object to create a message:</p>
|
||
|
|
<p><pre>
|
||
|
|
var a = ["chicken","duck","goose"];
|
||
|
|
|
||
|
|
var obj = new Object();
|
||
|
|
obj.x = 20;
|
||
|
|
obj.y = "cow";
|
||
|
|
obj.z = 3.14;
|
||
|
|
|
||
|
|
var date = new Date();
|
||
|
|
|
||
|
|
var msg = new XMLRPCMessage("system.myMethod");
|
||
|
|
msg.addParameter("mississippi");
|
||
|
|
msg.addParameter(7);
|
||
|
|
msg.addParameter(false);
|
||
|
|
msg.addParameter(a);
|
||
|
|
msg.addParameter(obj);
|
||
|
|
msg.addParameter(date);
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This will create the following XML-RPC message:</p>
|
||
|
|
<p>
|
||
|
|
<xmp>
|
||
|
|
<?xml version="1.0"?>
|
||
|
|
<methodCall>
|
||
|
|
<methodName>system.myMethod</methodName>
|
||
|
|
<params>
|
||
|
|
<param>
|
||
|
|
<value><string>mississippi</string></value>
|
||
|
|
</param>
|
||
|
|
<param>
|
||
|
|
<value><i4>7</i4></value>
|
||
|
|
</param>
|
||
|
|
<param>
|
||
|
|
<value><boolean>0</boolean></value>
|
||
|
|
</param>
|
||
|
|
<param>
|
||
|
|
<value>
|
||
|
|
<array><data>
|
||
|
|
<value><string>chicken</string></value>
|
||
|
|
<value><string>duck</string></value>
|
||
|
|
<value><string>goose</string></value>
|
||
|
|
</data></array>
|
||
|
|
</value>
|
||
|
|
</param>
|
||
|
|
<param>
|
||
|
|
<value>
|
||
|
|
<struct>
|
||
|
|
<member>
|
||
|
|
<name>x</name>
|
||
|
|
<value><i4>20</i4></value>
|
||
|
|
</member>
|
||
|
|
<member>
|
||
|
|
<name>y</name>
|
||
|
|
<value><string>cow</string></value>
|
||
|
|
</member>
|
||
|
|
<member>
|
||
|
|
<name>z</name>
|
||
|
|
<value><double>3.14</double></value>
|
||
|
|
</member>
|
||
|
|
</struct>
|
||
|
|
</value>
|
||
|
|
</param>
|
||
|
|
<param>
|
||
|
|
<value><dateTime.iso8601>20010720T14:48:10</dateTime.iso8601></value>
|
||
|
|
</param>
|
||
|
|
</params>
|
||
|
|
</methodCall>
|
||
|
|
</xmp>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<a name="rpc-use"></a>
|
||
|
|
<h2>Making The Procedure Call</h2>
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<a name="rpc-socket"></a>
|
||
|
|
<h3>Using xmlrpc-socket</h3>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p>You can see it in action <a href="test-rs.html">here</a>.</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<a name="rpc-download"></a>
|
||
|
|
<h2>Download</h2>
|
||
|
|
<p>The download is avaliable as a <a href="xml-rpc.zip">ZIP file</a> (9K) which contains:</p>
|
||
|
|
<ul>
|
||
|
|
<li>index.html - this about page.</li>
|
||
|
|
<li>xmlrpc.js - the XML-RPC message builder script</li>
|
||
|
|
<li>xmlrpc-socket.php - the PHP proxy</li>
|
||
|
|
<li>http_post.util - the modifed version of http_post needed by xmlrpc-socket.</li>
|
||
|
|
<li>all three demo pages</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|
||
|
|
<p><a href="mailto:xmlrpc@scottandrew.com">Comments?</a></p>
|
||
|
|
<p><a href="http://www.scottandrew.com">s c o t t a n d r e w . c o m</a></p>
|
||
|
|
</body>
|
||
|
|
</html>
|