Welcome to jQuery XML-RPC’s documentation!¶

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.

Encoding and Decoding XML-RPC Documents¶

Use the following table to see how XML-RPC types are mapped to JavaScript types:

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

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

Adding and Extending Types¶

You can add your own types to XML-RPC by adding a member to $.xmlrpc.types, combined with the $.xmlrpc.makeType function. See $.xmlrpc.makeType() for more information

$.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

$.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.

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

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

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

$.xmlrpc.parseDocument(doc);

[
    '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.

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

$.xmlrpc.parseNode(node)

{
    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.

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

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

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

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