s c o t t a n d r e w . c o m

Last updated: 08/20/2001

## What is this?

It's an XML-RPC message builder, written in JavaScript. It takes JavaScript data objects and converts them into an XML-RPC message.

There are actually two components available here. One is the message builder, the other a PHP gateway called xmlrpc-socket that forwards XML-RPC requests to remote servers over the Internet. Together they turn your browser into an XML-RPC client.

You can see a live demo of it here.

Download the library here.

You can read more about the XML-RPC specification here.

Comments?

1. Creating an XML-RPC Message

1. Object Methods
2. Supported Data Types

2. A Sample XML-RPC Message
3. Making the Procedure Call

1. Using xmlrpc-socket

4. Download

## Creating an XML-RPC Message

First, create a new instance of the XMLRPCMessage object. The syntax is:

`var msg = new XMLRPCMessage([string methodName]);`

`methodName` 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 `system.listMethods`

### Object Methods

The XMLRPCMessage object has three methods:

void addParameter(object variant) | Accepts a JavaScript data type and adds a matching XML-RPC data type to the message
void setMethod(string methodName) | 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.
string xml() | Returns a string of XML containing the message contents.

### Supported Data Types

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 `addParameter` method and it will be converted to the proper format and value.

The following data types are supported:

JavaScript Data Type | Example | XML-RPC equivalent | Notes
--- | --- | --- | ---
Boolean | true |
    <boolean>1</boolean>
four-byte signed integer | 7 |
    <i4>7</i4>
double-precision signed floating point number | -3.14 |
    <double>-3.14</double>
| The script automagically determines whether a number is an integer or double.
string |
    "scottandrew"
    <string>
     scottandrew
    </string>
Date object |
    d = new Date();
    <dateTime.iso8601>
     20010716T18:16:18
    </dateTime.iso8601>
| 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.
array |
    a = [
     "one",
     "two",
     "three"
    ];
    <array>
     <data>
      <value>
       <string>one</string>
      </value>
      <value>
       <string>two</string>
      </value>
      <value>
       <string>three</string>
      </value>
     </data>
    </array>
| 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. 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).
object |
    obj = new Object();
    obj.a = "hello";
    obj.b = 7.22;
    obj.c = 100;
    <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>

This library does not currently support the base64 data type.

## A Sample Message

Here is an example of using the XMLRPCMessage object to create a message:

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

This will create the following XML-RPC message:

    <?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>

## Making The Procedure Call

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.

Depending upon your implementation, you may need to remove line breaks from, escape or otherwise encode the content of the message before posting it.

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.

### Using xmlrpc-socket

xmlrpc-socket utilizes Brent Ashley's JavaScript Remote Scripting 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.

You can see it in action here.

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.

## Download

The download is avaliable as a ZIP file (9K) which contains:

- index.html - this about page.
- xmlrpc.js - the XML-RPC message builder script
- xmlrpc-socket.php - the PHP proxy
- http_post.util - the modifed version of http_post needed by xmlrpc-socket.
- all three demo pages

You'll also need to grab a copy of the JavaScript Remote Scripting library from http://www.ashleyit.com/rs

Comments?

s c o t t a n d r e w . c o m