![]() | ![]() |
|
XML-RPC HOWTOCopyright © 2001 by Eric Kidd 0.8.0, 2001-04-12
1. Legal NoticePermission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. This manual contains short example programs ("the Software"). Permission is hereby granted, free of charge, to any person obtaining a copy of the Software, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following condition: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 2. What is XML-RPC?XML-RPC is a simple, portable way to make remote procedure calls over HTTP. It can be used with Perl, Java, Python, C, C++, PHP and many other programming languages. Implementations are available for Unix, Windows and the Macintosh. Here's a short XML-RPC client written in Perl. (We use Ken MacLeod's Frontier::Client module.)
When run, this program will connect to the remote server, get the state name, and print it. (State #41 should be South Dakota in this example.) Here's the same program in Python. (This time, we use Fredrik Lundh's xmlrpclib.)
In the following chapters, you'll learn how to write XML-RPC clients and servers in a variety of programming languages. 2.1. How it WorksXML-RPC is described fully in Dave Winer's official specification. If you're curious, go ahead and take a look—it's a quick and straight-forward read. On the wire, XML-RPC values are encoded as XML:
This is verbose, but compresses readily. It's also faster than you might expect—according to measurements by Rick Blair, a round-trip XML-RPC call takes 3 milliseconds using Hannes Wallnöfer's Java implementation. 2.2. Supported Data TypesXML-RPC supports the following data types:
2.3. The History of XML-RPCXML-RPC was inspired by two earlier protocols. The first is an anonymous RPC protocol designed by Dave Winer and announced in an old DaveNet essay. (This is why XML-RPC servers are often installed under /RPC2.) The other, more important inspiration was an early draft of the SOAP protocol. A longer history of XML-RPC has been generously provided by Dave Winer. This also explains the relationship between XML-RPC and SOAP. 3. XML-RPC vs. Other ProtocolsXML-RPC is not the only way to make remote procedure calls. Other popular protocols include CORBA, DCOM and SOAP. Each of these protocols has advantages and disadvantages. The opinions in the section are obviously biased; please take them with a grain of salt. 3.1. XML-RPC vs. CORBACORBA is a popular protocol for writing distributed, object-oriented applications. It's typically used in multi-tier enterprise applications. Recently, it's also been adopted by the Gnome project for interapplication communication. CORBA is well-supported by many vendors and several free software projects. CORBA works well with Java and C++, and is available for many other languages. CORBA also provides an excellent interface definition language (IDL), allowing you to define readable, object-oriented APIs. Unfortunately, CORBA is very complex. It has a steep learning curve, requires significant effort to implement, and requires fairly sophisticated clients. It's better-suited to enterprise and desktop applications than it is to distributed web applications. 3.2. XML-RPC vs. DCOMDCOM is Microsoft's answer to CORBA. It's great if you're already using COM components, and you don't need to talk to non-Microsoft systems. Otherwise, it won't help you very much. 3.3. XML-RPC vs. SOAPSOAP is very similar to XML-RPC. It, too, works by marshaling procedure calls over HTTP as XML documents. Unfortunately, SOAP appears to be suffering from specification creep. SOAP was originally created as a collaboration between UserLand, DevelopMentor and Microsoft. The initial public release was basically XML-RPC with namespaces and longer element names. Since then, however, SOAP has been turned over a W3C working group. Unfortunately, the working group has been adding a laundry-list of strange features to SOAP. As of the current writing, SOAP supports XML Schemas, enumerations, strange hybrids of structs and arrays, and custom types. At the same time, several aspects of SOAP are implementation defined. Basically, if you like XML-RPC, but wish the protocol had more features, check out SOAP. :-) 4. Common XML-RPC InterfacesSeveral XML-RPC servers provide built-in methods. These aren't part of XML-RPC itself, but they make handy add-ons. 4.1. Introspection: Discovering Server APIsEdd Dumbill proposed the following set of methods:
If a server supports these methods, you can ask it to print out some documentation:
These methods are currently supported by servers written in PHP, C and Microsoft .NET. Partial introspection support is included in recent updates to UserLand Frontier. Introspection support for Perl, Python and Java is available at the XML-RPC Hacks page. Please feel free to add introspection support to other XML-RPC servers! Various client-side tools (documentation generators, wrapper generators, and so on) can be found at the XML-RPC Hacks page as well. 4.2. Boxcarring: Sending Multiple Requests at OnceIf you're writing an XML-RPC client which makes lots of small function calls, you may discover that your round-trip time is fairly high, thanks to Internet backbone latency. Some servers allow you to batch up multiple requests using the following function:
You can find more information in the system.multicall RFC. This method is currently supported by servers written in C and UserLand Frontier. Servers written in Python and Perl can use the code at the XML-RPC Hacks page. 5. A Sample API: sumAndDifferenceTo demonstrate XML-RPC, we implement the following API in as many languages as possible.
This function takes two integers as arguments, and returns an XML-RPC <struct> containing two elements:
It's not very useful, but it makes a nice example. :-) This function (and others) are available using the URL http://xmlrpc-c.sourceforge.net/api/sample.php. (This URL won't do anything in a browser; it requires an XML-RPC client.) 6. Using XML-RPC with PerlKen MacLeod has implemented XML-RPC for Perl. You can find his Frontier::RPC module at his website or through CPAN. To install Frontier::RPC, download the package and compile it in the standard fashion:
(The process will be slightly different on Windows systems, or if you don't have root access. Consult your Perl documentation for details.) 6.1. A Perl ClientThe following program shows how to call an XML-RPC server from Perl:
6.2. A Stand-Alone Perl ServerThe following program shows how to write an XML-RPC server in Perl:
6.3. A CGI-Based Perl ServerFrontier::RPC2 doesn't provide built-in support for CGI-based servers. It does, however, provide most of the pieces you'll need. Save the following code as sumAndDifference.cgi in your web server's cgi-bin directory. (On Unix systems, you'll need to make it executable by typing chmod +x sumAndDifference.cgi.)
You can copy the utility routines into your own CGI scripts. 7. Using XML-RPC with PythonFredrik Lundh has provided an excellent XML-RPC library for Python. To install, download the latest version. You can either stick the *.py files in the same directory as your Python code, or you can install them in your system's Python directory. RedHat 6.2 users can type the following:
We import two of the *.py files to trick Python into compiling them. Users of other platforms should consult their Python documentation. For more Python examples, see the article XML-RPC: It Works Both Ways on the O'Reilly Network. 7.1. A Python ClientThe following program shows how to call an XML-RPC server from Python:
8. Using XML-RPC with C and C++To get a copy of XML-RPC for C/C++, see the xmlrpc-c website. You can either download everything in RPM format, or you can build it from source. 8.1. A C ClientSave the following code in a file called getSumAndDifference.c:
To compile it, you can type:
You may need to replace gcc with the name of your system's C compiler. 8.2. A C++ ClientSave the following code in a file called getSumAndDifference2.cc:
To compile it, you can type:
You'll need a reasonably modern C++ compiler for this to work. 8.3. A C++ Client with Proxy ClassesIf your XML-RPC server supports the Introspection API, you can automatically generate C++ proxy classes for it. To generate a proxy class, type the following command and save the output to a file:
This will generate a proxy class named SampleProxy containing wrappers for all the methods beginning with sample. You can edit this class in any fashion you'd like. 8.4. A CGI-Based C ServerSave the following code in a file called sumAndDifference.c:
To compile it, you can type:
Once this is done, copy sumAndDifference.cgi into your webserver's cgi-bin directory. 9. Using XML-RPC with JavaHannes Wallnöfer has provided an excellent implementation of XML-RPC for Java. To install it, download the distribution, unzip it, and add the *.jar files to your CLASSPATH. On a Unix system, you can do this by typing:
9.1. A Java ClientSave the following program in a file named JavaClient.java.
9.2. A Stand-Alone Java ServerSave the following program in a file named JavaServer.java.
10. Using XML-RPC with PHPEdd Dumbill has implemented XML-RPC for PHP. You can download it from the UsefulInc XML-RPC website. To install the distribution, decompress it and copy xmlrpc.inc and xmlrpcs.inc into the same directory as your PHP scripts. 10.1. A PHP ClientThe following script shows how to embed XML-RPC calls into a web page.
If your webserver doesn't run PHP scripts, see the PHP website for more information. 10.2. A PHP ServerThe following script shows how to implement an XML-RPC server using PHP.
You would normally invoke this as something like http://localhost/path/sumAndDifference.php. 11. Using XML-RPC with Microsoft .NETCharles Cook is writing an excellent new chapter for this HOWTO. You can find a draft online. If that page disappears, look for a new version of the XML-RPC HOWTO at the Linux Documentation Project. 12. Using XML-RPC with Ruby(This section of the XML-RPC HOWTO was generously provided by Michael Neumann.) Ruby is an object-oriented scripting language. It already has a major following in Japan, and it's becoming popular elsewhere. To use XML-RPC with Ruby, you must first install Yoshida Masato's xmlparser module (a wrapper for James Clark's expat parser). This can be found at the Ruby Application Archive. Then, you must install xmlrpc4r using the following commands:
12.1. A Ruby ClientHere's a simple Ruby client:
12.2. A Ruby ServerHere's a simple Ruby server:
This could also have been written as follows:
To run either server in standalone mode, replace the second line of code with the following:
13. Using XML-RPC with Proprietary LanguagesImplementations of XML-RPC are available for the following proprietary programming languages and environments. 13.1. Using XML-RPC with K(This section of the XML-RPC HOWTO was generously provided by Christian Langreiter.) K is a language used in finance and database development. To install XML-RPC for K, download it from the Kx website. Uncompress and copy the files into the directory in which you keep your .k programs. Here's a short client:
And here's a server:
More examples are included in the distribution. 14. Applications with Built-in XML-RPC SupportSeveral popular Linux applications include support for XML-RPC. These have already been described elsewhere, so we mostly provide pointers to articles. 14.1. ZopeArticles on using XML-RPC with Zope are available elsewhere on the web:
14.2. KDE 2.0KDE 2.0 includes Kurt Ganroth's kxmlrpc daemon, which allows you to script KDE applications using XML-RPC. Here's a short sample application in Python. It shows you how to connect to kxmlrpc, manipulate your KDE address book, and query the KDE trader. If you have any other articles or example code, please see Section 15.3. We'd like to have more information on scripting KDE. 15. About This DocumentThis document is part of the Linux Documentation Project. Thanks go to Dave Winer and maintainers of all the various XML-RPC libraries. 15.1. New Versions of This DocumentNew versions of this document are available at the Linux Documentation Project website. They also provide this manual in alternate formats, including PDF, gzipped HTML and ASCII text. 15.2. Contributors to the XML-RPC HOWTOThe section on Ruby was contributed by Michael Neumann (neumann AT s-direktnet DOT de). The section on K was contributed by Christian Langreiter (c DOT langreiter AT synerge DOT at). These contributors are all credited at the beginning of their sections. 15.3. Submitting Other SnippetsIf you have a sample client or server in another language or environment, we'd love to include it in this manual. To add a new entry, we need the following information:
E-mail your example to the xmlrpc-c-devel mailing list or directly to Eric Kidd. Thank you for your help! |