API¶

The following API is exposed in case you need to extend this library. You should not have to use this API in everyday use of the library.

$.xmlrpc()¶

Call a remote procedure. This is a small wrapper around jQuery.ajax() so see the documentation for that for more information. It takes the following arguments:

url

The URL of the service to call. Optional. If not specified, this is pulled from the options dict

options

Options for the request. Most options are passed straight through to jQuery.ajax(), with the exception of two keys.

The methodName key must always be supplied, and must be a string. It is used as the <methodName> for the call

The params key can be used to send parameters. This must be an array of values. Leave this blank, or supply and empty array to send no parameters.

See Types for more information on how JavaScript types are translated to XML-RPC types

Getting data back¶

When the XML-RPC call returns, the contents of the <params> element are parsed into JSON and supplied to the success callback of the AJAX call as the first parameter, much like a JSON request.

Handling errors¶

If any HTTP errors occur during transport, the normal jQuery AJAX error handling will be used. If the XML-RPC service successfully replies, but replies with a <fault> response, an $.xmlrpc.XmlRpcFault is thrown. This error will be sent as the third parameter to the error callback of the AJAX call, as with other errors.

$.xmlrpc.document()¶

Make an XML-RPC document from a method name and a set of parameters. It takes the following arguments:

methodName: This is method put in the <methodName> element from XML-RPC. It should be a string. The XML-RPC service you are communicating with will determine valid method names you can call.
params: An array of parameters to send. Specify an empty array if you do not want to send any parameters.

Example¶

The JavaScript call:

$.xmlrpc.document('foo', ['bar, true, [1, 2, 3]]);

produces the following XML document (with out the whitespace):

<methodCall>
    <methodName>foo</methodName>
    <params>
        <param>
            <value><string>bar</string></value>
        </param>
        <param>
            <value><boolean>1</boolean></value>
        </param>
        <param>
            <value><array><data>
                <value><int>1</int></value>
                <value><int>2</int></value>
                <value><int>3</int></value>
            </data></array></value>
        </param>
    </params>
</methodCall>

$.xmlrpc.toXmlRpc()¶

Take a value, and encode it as an XML-RPC node. Because the XML nodes must be created by the XML documents own createElement, this can not be used outside of a call to $.xmlrpc.document. It takes the following arguments:

value: The value to encode
$xml: A helper function to create an XML node on the document. It is then returned, wrapped by jQuery.

$.xmlrpc.parseDocument()¶

Parse an XML-RPC document, and return its contents. If the document represents an XML-RPC fault, an $.xmlrpc.XmlRpcFault is thrown. It takes the following arguments:

Example¶

The following XML document:

<?xml version="1.0"?>
<methodResponse>
    <params>
        <param>
            <value><string>foo</string></value>
        </param>
        <param>
            <value><int>3</int></value>
        </param>
        <param>
            <value><struct>
                <member>
                    <name>foo</name>
                    <value><i4>1</i4></value>
                </member>
                <member>
                    <name>bar</name>
                    <value><i4>2</i4></value>
                </member>
            </struct></value>
        </param>
    </params>
</methodResponse>

parsed by:

$.xmlrpc.parseDocument(doc);

would result in the JSON document:

[
    'foo',
    3,
    {
        foo: 1,
        bar: 2
    }
]

$.xmlrpc.parseNode()¶

Take a single XML element, and return the JSON equivalent of it. It takes one argument:

node: The XML node to decode. It should be be one of the types registered with $.xmlrpc.makeType(). If the type can not be found, and error is thrown.

Example¶

The XML element:

<struct>
    <member>
        <name>foo</name>
        <value><i4>1</i4></value>
    </member>
    <member>
        <name>bar</name>
        <value><i4>2</i4></value>
    </member>
</struct>

would be parsed by calling:

$.xmlrpc.parseNode(node)

resulting in the JSON:

{
    foo: 1,
    bar: 2
}

$.xmlrpc.makeType()¶

Add a XML-RPC type to the library. The library will then know how to decode elements of this type when they are returned. It takes the following arguments:

tag

The name of the XML-RPC element this represents. Example: 'boolean'

simple

If the element is a simple type or not. All standard elements except <struct> and <array> are simple types. The encoding a decoding functions of simple types are simplified, as they just deal with the text content of the elements.

encode

Take a JavaScript value, and encode it to an XML-RPC element. Receives the value to be encoded, and a helper function used to create XML nodes on the correct document - This helper MUST be used to create XML nodes for child elements.

Simple types need only return the text of the node, creating the node is handled for you.

decode

Take an XML element, and decode it to a JavaScript representation.

Simple types receive the text of the node instead of the node itself.

Example¶

A simple boolean node:

// Boolean type. True == '1', False == '0'
$.xmlrpc.makeType('boolean', true, function(value) {
    return value ? '1' : '0';
}, function(text) {
    return text == '1';
});

A complex, custom element:

/**
 * Convert
 *     {foo: 1, bar: "hello"}
 * into
 *     <custom><foo>1</foo><bar><string>hello</string></bar></custom>
 * Note the call to `$.xmlrpc.toXmlRpc`` to recursively encode the `bar` element.
 */
$.xmlrpc.makeType('custom', false, function(value, $xml) {
    return $xml('custom').append([
        $xml('foo').text($.xmlrpc.toXmlRpc(value.foo, $xml)),
        $xml('bar').text($.xmlrpc.toXmlRpc(value.foo, $xml))
    ]);
}, function(node) {
    return {
        foo: parseInt($(node).find('> foo').text()),
        bar: fromXmlRpc($(node).find('> bar > *').get(0)),
    }
});

$.xmlrpc.force()¶

Force a value to be encoded as a certain type in XML-RPC. It takes the following arguments:

type: The type to force the value to. One of the XML-RPC types named in the [types documentation][types], or one of the custom types added with $.xmlrpc.makeType.
value: Any value that will be encoded as the type.

Example¶

Force a float to be encoded as an i8, to send as a parameter:

var forcedValue = $.xmlrpc.force('i8', 4.5)

$.xmlrpc({
    url: '/RPC2',
    methodName: 'foo',
    params: [forcedValue]
});