XML-RPC

I l @ ve RuBoard

XML-RPC, as defined on its official web site, is ". . . a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet . . ." [1] It was created in 1998 to provide a simple portable framework for transmitting procedure calls and receiving responses over the Internet.

[1] UserLand Software, Inc. "XML-RPC Home Page." Available from the Internet: http://www.xmlrpc.org/. Last updated: November 5, 2001 .

As the preceding definition states, XML-RPC actually consists of two parts : the XML-RPC specification itself, which defines the structure and format of XML-RPC procedure calls and responses; and a set of implementations for different platforms. Because XML-RPC was designed from the get-go to be easily portable, it won't surprise you to hear that it has spawned a diverse array of implementations. As of this writing, the official web site lists more than 50 different implementations in languages such as Lisp, AppleScript, JavaScript, C, Perl, Python, and PHP.

D ja Vu

If some of this sounds familiar, give yourself 10 points for attentiveness ”because it should. Though the two specifications address different problems, XML-RPC shares a number of important traits with Web Distributed Data eXchange (WDDX) that was last seen in Chapter 5, "PHP and Web Distributed Data eXchange(WDDX)." Here's a brief list:

  • Neither WDDX nor XML-RPC is an official standard per se; they're both open specifications created by one company and popularized via the developer community.

  • Both specifications provide an open, extensible architecture for information exchange.

  • Both specifications use XML as their encoding toolkit. XML-RPC requires HTTP exclusively as its transmission layer, whereas WDDX can be transmitted over any protocol that supports text (HTTP, POP, FTP, SMTP, and so on).

  • Both specifications use similar data structures to represent native data types.

  • Both specifications' implementations are available for a wide variety of different languages and platforms.

An XML-RPC procedure call is encoded as a well- formed XML document, with both procedure name and arguments enclosed within a <methodCall> document element. This procedure call is transmitted to the XML-RPC server as a standard HTTP POST request.

Listing 6.1 demonstrates an XML-RPC request to the server some.quote.server ; the request itself is equivalent to calling the function getRandomQuote("Shakespeare") .

Listing 6.1 An XML-RPC Request
 POST /RPC2 HTTP/1.0  User-Agent: Mozilla/4.0 (compatible; MSIE 5.0; Windows 95)  Host: some.quote.server  Content-Type: text/xml  Content-Length: 287  <?xml version="1.0" ?>      <methodCall>          <methodName>getRandomQuote</methodName>          <params>              <param>                  <value>                     <string>Shakespeare</string>                  </value>              </param>          </params>  </methodCall> 

As you can see, the XML-RPC request body is clearly demarcated into two sections.The <methodName> element contains the name of the procedure to be invoked on the remote server, whereas the <params> element encloses a list of arguments to be passed to the remote procedure. Individual arguments are represented by individual <param> elements, which in turn enclose a data-typed value (take a look at the following sidebar entitled "Atypically Yours" for a list of the various data types supported by XML-RPC).

The server decodes and interprets the request, processes it, and returns the result to the requesting client, again as an XML-encoded HTTP POST response. Listing 6.2 demonstrates what it might look like.

Listing 6.2 An XML-RPC Response to a Successful RPC Request
 HTTP/1.0 200 OK  Server: QuoteServer/RPC  Connection: close  Content-Type: text/xml  Content-Length: 270  <?xml version="1.0"?>  <methodResponse>        <params>          <param>              <value>                  <string>Good night, sweet prince, and flights of angels sing thee to thy graphics/ccc.gif rest.</string>              </value>          </param>      </params>  </methodResponse> 

Atypically Yours

The XML-RPC specification currently defines the following data types:

  • Boolean values, represented by the <boolean> element

  • Signed 32-bit integers, represented by the <int> or <i4> element

  • Signed floating-point numbers , represented by the <double> element

  • ASCII strings, represented by the <string> element (this is the default type)

  • Date/time values, represented by the <dateTime.iso8601> element (these values must be encoded in ISO8601 format, but the XML-RPC specification does not make any assumption about the time zone offset used)

  • Binary data encoded with BASE64, represented by the <base64> element

  • Integer-indexed arrays, represented by the <array> element

  • Structures, or string-indexed arrays, represented by the <struct> element

Every XML-RPC response must return an HTTP status code of 200 OK ; however, the content of the response differs , depending on whether or not an error occurred while processing the XML-RPC request. The response to a successful RPC invocation looks like Listing 6.2: a document element named <methodResponse> that contains one <params> element enclosing the value returned by the procedure.

An unsuccessful RPC invocation generates an error, which looks like Listing 6.3.

Listing 6.3 An XML-RPC Response to an Unsuccessful RPC Request
 HTTP/1.0 200 OK  Server: QuoteServer/RPC  Connection: close  Content-Type: text/xml  Content-Length: 585  <?xml version="1.0"?>  <methodResponse>      <fault>          <value>              <struct>                 <member>                     <name>faultCode</name>                     <value>                          <int>2</int>                      </value>                 </member>                 <member>                     <name>faultString</name>                     <value>                        <string>No quotes by that author</string>                      </value>                 </member>             </struct>          </value>      </fault>  </methodResponse> 

In this case, though the document element remains the same, the <params> element is replaced by a <fault> element, which is itself a <struct> containing an error code and a human-friendly error string.

That pretty much covers the basics of XML-RPC. For more information and examples, you should refer to the official web site at http://www.xmlrpc.org/, which contains the complete XML-RPC specification (with examples and code samples), a list of implementations for different platforms, tutorials, FAQs, and a discussion forum.

I l @ ve RuBoard


XML and PHP
XML and PHP
ISBN: 0735712271
EAN: 2147483647
Year: 2002
Pages: 84

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net