XML-RPC Protocol

Part:   1  2  

(Continued from previous part...)

From the XML schema, we can see that:

• A "methodCall" element will have a required "methodName" element and an optional "params" element.
• A "methodName" element specifies the name of the method.
• A "params" element specifies a list of "param" elements as parameters for the method.
• A "param" element will have a "value" element.
• A "value" element will have a value type element, which contains the actual value of the parameter.
• There are 7 value type elements: "int", "boolean", "string", "double", "dateTime.iso8601", "base64", "struct" and "array". The first 6 are simple elements and the last 2 are complex elements.
• A "struct" element will have a list of "member" elements. A "memeber" element will have a "name" element and a "value" element.
• An "array" element will have a "data" elements, which will have a list of "value" elements.

The following is an example of "methodCall":

<methodCall>
 <methodName>somePackage.someSort</methodName>
 <params>
  <param><value><int>3</int></value></param>
  <param><value><string>Descending</string></value></param>
  <param><value><struct>
   <member><name>Yang</name><value><int>9647</int></value></member>
   <member><name>Bush</name><value><int>3014</int></value></member>
   <member><name>Gate</name><value><int>6618</int></value></member>
  </struct></value></param>
 </params>
</methodCall>

2. Sending a method call as a HTTP request. XML-RPC defines that a method call must be delivered to the remote host as a HTTP request with the following rules:

• The request must use the POST method.
• Header lines, "User-Agent" and "Host", are is required.
• Header line, "Content-Type", is required and must have "text/xml" as the value.
• Header line, "Content-length", is required and must give accurate value.
• The request body must be an XML file with a single "mechodCall" element.

Here is an example of an XML-RPC request:

POST /pathName/progName HTTP/1.0
User-Agent: MyAgent/1.0.0 (Linux)
Host: kermit.dot.com
Content-Type: text/xml
Content-length: 300

<methodCall>
 <methodName>somePackage.someSort</methodName>
 <params>
  ......
 </params>
</methodCall>

3. Defining returning values in XML. XML-RPC defines returning values of a method call as an XML element called "methodResponse". The structure of "methodResponse is very similar to "methodCall". But only one "param" is allowed inside "params" as shown in the following XSD file:

<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!-- xmlRpcMethodResponse.xsd
     Copyright (c) 2005 by Dr. Herong Yang
-->
 <xsd:element name="methodResponse" type="methodResponseType"/>
 <xsd:complexType name="methodResponseType">
  <xsd:sequence>
   <xsd:element name="params" type="paramsType" 
      minOccurs="0"/>
  </xsd:sequence>
 </xsd:complexType>
 <xsd:complexType name="paramsType">
  <xsd:sequence>
   <xsd:element name="param" type="paramType" 
      minOccurs="1" maxOccurs="1"/>
  </xsd:sequence>
 </xsd:complexType>
 ......
</xsd:schema>

Here is an example of "methodResponse":

<methodResponse>
 <params>
  <param><value><array><data>
   <value><string>Bush</string></value>
   <value><string>Gate</string></value>
   <value><string>Yang</string></value>
  </data></struct></value></param>
 </params>
</methodResponse>

3. Receiving return values as a HTTP response. XML-RPC defines that the returning values must be delivered as a HTTP response back to the local host with the following rules:

• Header line, "Content-Type", is required and must have "text/xml" as the value.
• Header line, "Content-length", is required and must give accurate value.
• The response body must be an XML file with a single "mechodResponse" element.

Here is an example of an XML-RPC response:

HTTP/1.1 200 OK
Connection: close
Content-Length: 200
Content-Type: text/xml

<?xml version="1.0"?>
<methodResponse>
 <params>
  ......
 </params>
</methodResponse>

Conclusion

• XML-RPC is indeed a simple protocol for remote procedure calls using XML as the data format and HTTP as the communication method.

Part:   1  2