<abstract>This specification defines an XMPP protocol extension for transporting XML-RPC encoded requests and responses between two XMPP entities. The protocol supports all syntax and semantics of XML-RPC except that it uses XMPP instead of HTTP as the underlying transport.</abstract>
<remark>Per a vote of the Jabber Council, changed status to Final.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2001-09-27</date>
<initials>psa</initials>
<remark>Changed status to Draft</remark>
</revision>
<revision>
<version>0.1</version>
<date>2001-09-14</date>
<initials>dja</initials>
<remark>Initial version</remark>
</revision>
</header>
<section1topic='Introduction'>
<p>&xmlrpc; is a method of encoding RPC requests and responses in XML. The original specification defines HTTP (see &rfc2068;) as the only valid transport for XML-RPC payloads.</p>
<p>Various initiatives exist already to transport XML-RPC payloads over Jabber. These initiatives were independent of each other and used slightly differing methods (e.g. carrying the payload in a <message/> element as opposed to an &IQ; stanza), resulting in potential interoperability problems.</p>
<p>A working session during JabberCon 2001 resulted in a <linkurl="http://www.pipetree.com/jabber/jrpc.html">formalisation</link> of a single method. This document describes that method, which is labelled as Jabber-RPC to differentiate it from XML-RPC itself.</p>
<p>The &IQ; stanza is used to transport XML-RPC payloads. XML-RPC requests are transported using an &IQ; stanza of type "set", and XML-RPC responses are transported using an &IQ; stanza of type "result". An &IQ; stanza MUST NOT contain more than one request or response.</p>
<p>The &IQ; stanza contains a single &QUERY; sub-element in the jabber:iq:rpc namespace. The direct child of the &QUERY; element will be either a single <methodCall/> element (in the case of a request) or a single <methodResponse/> element (in the case of a response). This child element will contain the XML-RPC payload. Note that the XML declaration that normally appears at the head of an XML-RPC request or response when transported as the payload of an HTTP POST request MUST BE omitted when it is transported via a Jabber &IQ; stanza.</p>
<p>The encoding of the Jabber XML stream is UTF-8. It is assumed that the encoding of the XML-RPC payload is also UTF-8.</p>
<p>Application-level errors will be indicated within the XML-RPC payload (as is the case with the traditional HTTP-based XML-RPC mechanism). Transport level errors will be indicated in the normal way for &IQ; stanzas -- namely, by an &IQ; stanza of type "error" and the addition of an <error/> tag as a direct child of the &IQ; stanza. There are no specific XML-RPC-related, transport-level errors.</p>
</section1>
<section1topic='Examples'>
<examplecaption='A typical request'><![CDATA[
<iqtype='set'
from='requester@company-b.com/jrpc-client'
to='responder@company-a.com/jrpc-server'
id='rpc1'>
<queryxmlns='jabber:iq:rpc'>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>6</i4></value>
</param>
</params>
</methodCall>
</query>
</iq>
]]></example>
<examplecaption='A typical response'><![CDATA[
<iqtype='result'
from='responder@company-a.com/jrpc-server'
to='requester@company-b.com/jrpc-client'
id='rpc1'>
<queryxmlns='jabber:iq:rpc'>
<methodResponse>
<params>
<param>
<value><string>Colorado</string></value>
</param>
</params>
</methodResponse>
</query>
</iq>
]]></example>
<p>If the requesting entity does not have sufficient permissions to perform remote procedure calls, the responding entity MUST return a &forbidden; error:</p>
<examplecaption='Requesting entity is forbidden to perform remote procedure calls'><![CDATA[
<p>If an entity supports the Jabber-RPC protocol, it SHOULD advertise that fact in response to &xep0030; information ("diso#info") requests by returning an identity of "automation/rpc" and a feature of "jabber:iq:rpc":</p>
<p>An entity that supports Jabber-RPC SHOULD establish a "whitelist" of entities that are allowed to perform remote procedure calls and MUST return a &forbidden; error if entities with insufficient permissions attempt such calls.</p>