◈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 Method

The XMLRPCMessage object has tree methods :

void addParameter    Accepts a Javascript data type and adds a matching XML-RPC data type

(object variant)         to the message.

void setMethod         Declares the XML-RPC method you wish to call on the remote server.

(string                      You only need to use this if you haven't specified a method name when

    methodName)        creating the XMLRPCMessage object.

string xml()               Return 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        Example               XML-RPC                        Notes

Data Type                                   equivalent

----------------------------------------------------------------------------------------

Boolean           true                     <boolean>1</boolean>

four-byte

signed               7                       <i4>7</i4>

integer

double                                                                               The script automagically

-precision                                                                          determines whether a

signed             -3.14                    <double>-3.14</double>    number is an integer or

floating point                                                                       double.

number

string               "scottandrew"       <string>scottandrew

                                                            </string>

Date object       d=new Date();       <dateTime.iso8601>           Date objects are automatically

                                                  20040430T09:49:20              converted into the ISO8601

                                                  </dateTime.iso8601>         format. You cannot pass date

                                                                                        strings here; those will remain

                                                                                        string. Instead create a new

                                                                                        Date object and use that.

array                a=["one",             <array>

                            "two",              <data>

                            "three"];            <value>

                                                     <string>one</string>

                                                    </value>

                                                    <value>                         You don't have to worry if na

                                                     <string>two</string>     Array or Object has a varienty

                                                    </value>                       of data types as members;

                                                    <value>                         the script identifies the data

                                                     <string>three</string>    types of each member and

                                                    </value>                        includes it in the message.

                                                   </data>

                                                  </array>                          Both array and structs can

                                                                                         contain other arrays and

object              obj = new Object();<struct>                           structs as member, so it's

                       obj.a = "hello";       <member>                       possible to take a complex

                       obj.b = 7.22;            <name>a</name>          Object and describe it in XML

                       obj.c = 100;             <value>                         by passing it to addParameter

                                                     <string>hello</string>    (this recursive feature is still

                                                    </value>                        being tested, though)

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

                    </scruct>

                </value>

            </param>

            <param>

                <value><dateTime.iso8601>20040430T10:29:30</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 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 postring it.

The response is also XML-formatted. Once you receive the response string, you can parse it orload it into a DOM object to walk through its elements.

  Using xmlrpc-socket

xmlrpc-socket utilzes 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.

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.