XML-RPC HOWTO Eric Kidd Source Builders Charles Cook Cook Computing And Other Contributors Copyright © 2001 Eric Kidd, Charles Cook 0.8.0, 2001-04-12 Revision History Revision 0.9.0 2001-05-13 Merged in Charles Cook's chapter on XML-RPC.Net. Revision 0.8.0 2001-04-12 Updated section on common interfaces. Added pointer to XML-RPC.Net information. Revision 0.7.0 2001-04-03 Added section on C++ proxy classes. Revision 0.6.0 2001-02-02 Added sections on Ruby, K and common interfaces. Revision 0.5.0 2001-01-23 Initial version. Abstract Describes how to use XML-RPC to implement clients and servers in a variety of languages. Provides example code in Perl, Python, C, C++, Java, PHP, XML- RPC.Net and other languages. Includes sections on Zope and KDE 2.0. Applies to all operating systems with XML-RPC support. ------------------------------------------------------------------------------- Table of Contents 1._Legal_Notice 2._What_is_XML-RPC? 2.1._How_it_Works 2.2._Supported_Data_Types 2.3._The_History_of_XML-RPC 3._XML-RPC_vs._Other_Protocols 3.1._XML-RPC_vs._CORBA 3.2._XML-RPC_vs._DCOM 3.3._XML-RPC_vs._SOAP 4._Common_XML-RPC_Interfaces 4.1._Introspection:_Discovering_Server_APIs 4.2._Boxcarring:_Sending_Multiple_Requests_at_Once 5._A_Sample_API:_sumAndDifference 6._Using_XML-RPC_with_Perl 6.1._A_Perl_Client 6.2._A_Stand-Alone_Perl_Server 6.3._A_CGI-Based_Perl_Server 7._Using_XML-RPC_with_Python 7.1._A_Python_Client 8._Using_XML-RPC_with_C_and_C++ 8.1._A_C_Client 8.2._A_C++_Client 8.3._A_C++_Client_with_Proxy_Classes 8.4._A_CGI-Based_C_Server 9._Using_XML-RPC_with_Java 9.1._A_Java_Client 9.2._A_Stand-Alone_Java_Server 10._Using_XML-RPC_with_PHP 10.1._A_PHP_Client 10.2._A_PHP_Server 11._Using_XML-RPC_with_Microsoft_.NET 11.1._A_C#_Client 11.2._A_Visual_Basic_.NET_Client 11.3._A_C#_Server 11.4._A_Visual_Basic_.NET_Server 12._Using_XML-RPC_with_Ruby 12.1._A_Ruby_Client 12.2._A_Ruby_Server 13._Using_XML-RPC_with_Proprietary_Languages 13.1._Using_XML-RPC_with_K 14._Applications_with_Built-in_XML-RPC_Support 14.1._Zope 14.2._KDE_2.0 15._About_This_Document 15.1._New_Versions_of_This_Document 15.2._Contributors_to_the_XML-RPC_HOWTO 15.3._Submitting_Other_Snippets 1. Legal Notice Permission 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.) use Frontier::Client; $server = Frontier::Client->new(url => 'http://betty.userland.com/RPC2'); $name = $server->call('examples.getStateName', 41); print "$name\n"; 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.) python> import xmlrpclib python> server = xmlrpclib.Server("http://betty.userland.com/RPC2") python> server.examples.getStateName(41) 'South Dakota' 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 Works XML-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: sample.sumAndDifference 5 3 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 Types XML-RPC supports the following data types: int A signed, 32-bit integer. string An ASCII string, which may contain NULL bytes. (Actually, several XML-RPC implementations support Unicode, thanks to the underlying features of XML.) boolean Either true or false. double A double-precision floating point number. (Accuracy may be limited in some implementations.) dateTime.iso8601 A date and time. Unfortunately, since XML-RPC forbids the use of timezones, this is very nearly useless. base64 Raw binary data of any length; encoded using Base64 on the wire. Very useful. (Some implementations don't like to receive zero bytes of data, though.) array An one-dimensional array of values. Individual values may be of any type. struct A collection of key-value pairs. The keys are strings; the values may be of any type. 2.3. The History of XML-RPC XML-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 Protocols XML-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. CORBA CORBA 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. DCOM DCOM 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. SOAP SOAP 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 Interfaces Several 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 APIs Edd Dumbill proposed the following set of methods: array system.listMethods () string system.methodHelp (string methodName) array system.methodSignature (string methodName) If a server supports these methods, you can ask it to print out some documentation: import xmlrpclib server = xmlrpclib.Server("http://xmlrpc-c.sourceforge.net/api/sample.php") for method in server.system.listMethods(): print method print server.system.methodHelp(method) print 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 Once If 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: array system.multicall (array calls) 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: sumAndDifference To demonstrate XML-RPC, we implement the following API in as many languages as possible. struct sample.sumAndDifference (int x, int y) This function takes two integers as arguments, and returns an XML-RPC containing two elements: sum The sum of the two integers. difference The difference between the two integers. 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 Perl Ken 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: bash$ gunzip -c Frontier-RPC-0.07b1.tar.gz | tar xvf - bash$ cd Frontier-RPC-0.07b1 bash$ perl Makefile.PL bash$ make bash$ make test bash$ su -c 'make install' (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 Client The following program shows how to call an XML-RPC server from Perl: use Frontier::Client; # Make an object to represent the XML-RPC server. $server_url = 'http://xmlrpc-c.sourceforge.net/api/sample.php'; $server = Frontier::Client->new(url => $server_url); # Call the remote server and get our result. $result = $server->call('sample.sumAndDifference', 5, 3); $sum = $result->{'sum'}; $difference = $result->{'difference'}; print "Sum: $sum, Difference: $difference\n"; 6.2. A Stand-Alone Perl Server The following program shows how to write an XML-RPC server in Perl: use Frontier::Daemon; sub sumAndDifference { my ($x, $y) = @_; return {'sum' => $x + $y, 'difference' => $x - $y}; } # Call me as http://localhost:8080/RPC2 $methods = {'sample.sumAndDifference' => \&sumAndDifference}; Frontier::Daemon->new(LocalPort => 8080, methods => $methods) or die "Couldn't start HTTP server: $!"; 6.3. A CGI-Based Perl Server Frontier::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.) #!/usr/bin/perl -w use strict; use Frontier::RPC2; sub sumAndDifference { my ($x, $y) = @_; return {'sum' => $x + $y, 'difference' => $x - $y}; } process_cgi_call({'sample.sumAndDifference' => \&sumAndDifference}); #========================================================================== # CGI Support #========================================================================== # Simple CGI support for Frontier::RPC2. You can copy this into your CGI # scripts verbatim, or you can package it into a library. # (Based on xmlrpc_cgi.c by Eric Kidd .) # Process a CGI call. sub process_cgi_call ($) { my ($methods) = @_; # Get our CGI request information. my $method = $ENV{'REQUEST_METHOD'}; my $type = $ENV{'CONTENT_TYPE'}; my $length = $ENV{'CONTENT_LENGTH'}; # Perform some sanity checks. http_error(405, "Method Not Allowed") unless $method eq "POST"; http_error(400, "Bad Request") unless $type eq "text/xml"; http_error(411, "Length Required") unless $length > 0; # Fetch our body. my $body; my $count = read STDIN, $body, $length; http_error(400, "Bad Request") unless $count == $length; # Serve our request. my $coder = Frontier::RPC2->new; send_xml($coder->serve($body, $methods)); } # Send an HTTP error and exit. sub http_error ($$) { my ($code, $message) = @_; print <<"EOD"; Status: $code $message Content-type: text/html $code $message

$code $message

Unexpected error processing XML-RPC request.

EOD exit 0; } # Send an XML document (but don't exit). sub send_xml ($) { my ($xml_string) = @_; my $length = length($xml_string); print <<"EOD"; Status: 200 OK Content-type: text/xml Content-length: $length EOD # We want precise control over whitespace here. print $xml_string; } You can copy the utility routines into your own CGI scripts. 7. Using XML-RPC with Python Fredrik 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: bash$ mkdir xmlrpclib-0.9.8 bash$ cd xmlrpclib-0.9.8 bash$ unzip ../xmlrpc-0.9.8-990621.zip bash$ python python> import xmlrpclib python> import xmlrpcserver python> Control-D bash$ su -c 'cp *.py *.pyc /usr/lib/python1.5/' 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 Client The following program shows how to call an XML-RPC server from Python: import xmlrpclib # Create an object to represent our server. server_url = 'http://xmlrpc-c.sourceforge.net/api/sample.php'; server = xmlrpclib.Server(server_url); # Call the server and get our result. result = server.sample.sumAndDifference(5, 3) print "Sum:", result['sum'] print "Difference:", result['difference'] 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 Client Save the following code in a file called getSumAndDifference.c: #include #include #include #define NAME "XML-RPC getSumAndDifference C Client" #define VERSION "0.1" #define SERVER_URL "http://xmlrpc-c.sourceforge.net/api/sample.php" void die_if_fault_occurred (xmlrpc_env *env) { /* Check our error-handling environment for an XML-RPC fault. */ if (env->fault_occurred) { fprintf(stderr, "XML-RPC Fault: %s (%d)\n", env->fault_string, env->fault_code); exit(1); } } int main (int argc, char** argv) { xmlrpc_env env; xmlrpc_value *result; xmlrpc_int32 sum, difference; /* Start up our XML-RPC client library. */ xmlrpc_client_init(XMLRPC_CLIENT_NO_FLAGS, NAME, VERSION); xmlrpc_env_init(&env); /* Call our XML-RPC server. */ result = xmlrpc_client_call(&env, SERVER_URL, "sample.sumAndDifference", "(ii)", (xmlrpc_int32) 5, (xmlrpc_int32) 3); die_if_fault_occurred(&env); /* Parse our result value. */ xmlrpc_parse_value(&env, result, "{s:i,s:i,*}", "sum", &sum, "difference", &difference); die_if_fault_occurred(&env); /* Print out our sum and difference. */ printf("Sum: %d, Difference: %d\n", (int) sum, (int) difference); /* Dispose of our result value. */ xmlrpc_DECREF(result); /* Shutdown our XML-RPC client library. */ xmlrpc_env_clean(&env); xmlrpc_client_cleanup(); return 0; } To compile it, you can type: bash$ CLIENT_CFLAGS=`xmlrpc-c-config libwww-client --cflags` bash$ CLIENT_LIBS=`xmlrpc-c-config libwww-client --libs` bash$ gcc $CLIENT_CFLAGS -o getSumAndDifference getSumAndDifference.c $CLIENT_LIBS You may need to replace gcc with the name of your system's C compiler. 8.2. A C++ Client Save the following code in a file called getSumAndDifference2.cc: #include #include #define NAME "XML-RPC getSumAndDifference C++ Client" #define VERSION "0.1" #define SERVER_URL "http://xmlrpc-c.sourceforge.net/api/sample.php" static void get_sum_and_difference () { // Build our parameter array. XmlRpcValue param_array = XmlRpcValue::makeArray(); param_array.arrayAppendItem(XmlRpcValue::makeInt(5)); param_array.arrayAppendItem(XmlRpcValue::makeInt(3)); // Create an object to resprent the server, and make our call. XmlRpcClient server (SERVER_URL); XmlRpcValue result = server.call("sample.sumAndDifference", param_array); // Extract the sum and difference from our struct. XmlRpcValue::int32 sum = result.structGetValue("sum").getInt(); XmlRpcValue::int32 diff = result.structGetValue("difference").getInt(); cout << "Sum: " << sum << ", Difference: " << diff << endl; } int main (int argc, char **argv) { // Start up our client library. XmlRpcClient::Initialize(NAME, VERSION); // Call our client routine, and watch out for faults. try { get_sum_and_difference(); } catch (XmlRpcFault& fault) { cerr << argv[0] << ": XML-RPC fault #" << fault.getFaultCode() << ": " << fault.getFaultString() << endl; XmlRpcClient::Terminate(); exit(1); } // Shut down our client library. XmlRpcClient::Terminate(); return 0; } To compile it, you can type: bash$ CLIENT_CFLAGS=`xmlrpc-c-config c++ libwww-client --cflags` bash$ CLIENT_LIBS=`xmlrpc-c-config c++ libwww-client --libs` bash$ c++ $CLIENT_CFLAGS -o getSumAndDifference2 getSumAndDifference2.cc $CLIENT_LIBS You'll need a reasonably modern C++ compiler for this to work. 8.3. A C++ Client with Proxy Classes If 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: bash$ xml-rpc-api2cpp \ > http://xmlrpc-c.sourceforge.net/api/sample.php sample SampleProxy 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 Server Save the following code in a file called sumAndDifference.c: #include #include xmlrpc_value * sumAndDifference (xmlrpc_env *env, xmlrpc_value *param_array, void *user_data) { xmlrpc_int32 x, y; /* Parse our argument array. */ xmlrpc_parse_value(env, param_array, "(ii)", &x, &y); if (env->fault_occurred) return NULL; /* Return our result. */ return xmlrpc_build_value(env, "{s:i,s:i}", "sum", x + y, "difference", x - y); } int main (int argc, char **argv) { /* Set up our CGI library. */ xmlrpc_cgi_init(XMLRPC_CGI_NO_FLAGS); /* Install our only method (with a method signature and a help string). */ xmlrpc_cgi_add_method_w_doc("sample.sumAndDifference", &sumAndDifference, NULL, "S:ii", "Add and subtract two integers."); /* Call the appropriate method. */ xmlrpc_cgi_process_call(); /* Clean up our CGI library. */ xmlrpc_cgi_cleanup(); } To compile it, you can type: bash$ CGI_CFLAGS=`xmlrpc-c-config cgi-server --cflags` bash$ CGI_LIBS=`xmlrpc-c-config cgi-server --libs` bash$ gcc $CGI_CFLAGS -o sumAndDifference.cgi sumAndDifference.c $CGI_LIBS Once this is done, copy sumAndDifference.cgi into your webserver's cgi-bin directory. 9. Using XML-RPC with Java Hannes 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: bash$ unzip xmlrpc-java.zip bash$ cd xmlrpc-java/lib bash$ CLASSPATH=`pwd`/openxml-1.2.jar:`pwd`/xmlrpc.jar:$CLASSPATH 9.1. A Java Client Save the following program in a file named JavaClient.java. import java.util.Vector; import java.util.Hashtable; import helma.xmlrpc.*; public class JavaClient { // The location of our server. private final static String server_url = "http://xmlrpc-c.sourceforge.net/api/sample.php"; public static void main (String [] args) { try { // Create an object to represent our server. XmlRpcClient server = new XmlRpcClient(server_url); // Build our parameter list. Vector params = new Vector(); params.addElement(new Integer(5)); params.addElement(new Integer(3)); // Call the server, and get our result. Hashtable result = (Hashtable) server.execute("sample.sumAndDifference", params); int sum = ((Integer) result.get("sum")).intValue(); int difference = ((Integer) result.get("difference")).intValue(); // Print out our result. System.out.println("Sum: " + Integer.toString(sum) + ", Difference: " + Integer.toString(difference)); } catch (XmlRpcException exception) { System.err.println("JavaClient: XML-RPC Fault #" + Integer.toString(exception.code) + ": " + exception.toString()); } catch (Exception exception) { System.err.println("JavaClient: " + exception.toString()); } } } 9.2. A Stand-Alone Java Server Save the following program in a file named JavaServer.java. import java.util.Hashtable; import helma.xmlrpc.*; public class JavaServer { public JavaServer () { // Our handler is a regular Java object. It can have a // constructor and member variables in the ordinary fashion. // Public methods will be exposed to XML-RPC clients. } public Hashtable sumAndDifference (int x, int y) { Hashtable result = new Hashtable(); result.put("sum", new Integer(x + y)); result.put("difference", new Integer(x - y)); return result; } public static void main (String [] args) { try { // Invoke me as . WebServer server = new WebServer(8080); server.addHandler("sample", new JavaServer()); } catch (Exception exception) { System.err.println("JavaServer: " + exception.toString()); } } } 10. Using XML-RPC with PHP Edd 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 Client The following script shows how to embed XML-RPC calls into a web page. XML-RPC PHP Demo

XML-RPC PHP Demo

send($message); // Process the response. if (!$result) { print "

Could not connect to HTTP server.

"; } elseif ($result->faultCode()) { print "

XML-RPC Fault #" . $result->faultCode() . ": " . $result->faultString(); } else { $struct = $result->value(); $sumval = $struct->structmem('sum'); $sum = $sumval->scalarval(); $differenceval = $struct->structmem('difference'); $difference = $differenceval->scalarval(); print "

Sum: " . htmlentities($sum) . ", Difference: " . htmlentities($difference) . "

"; } ?> If your webserver doesn't run PHP scripts, see the PHP_website for more information. 10.2. A PHP Server The following script shows how to implement an XML-RPC server using PHP. getParam(0); $x = $xval->scalarval(); $yval = $params->getParam(1); $y = $yval->scalarval(); // Build our response. $struct = array('sum' => new xmlrpcval($x + $y, 'int'), 'difference' => new xmlrpcval($x - $y, 'int')); return new xmlrpcresp(new xmlrpcval($struct, 'struct')); } // Declare our signature and provide some documentation. // (The PHP server supports remote introspection. Nifty!) $sumAndDifference_sig = array(array('struct', 'int', 'int')); $sumAndDifference_doc = 'Add and subtract two numbers'; new xmlrpc_server(array('sample.sumAndDifference' => array('function' => 'sumAndDifference', 'signature' => $sumAndDifference_sig, 'docstring' => $sumAndDifference_doc))); ?> You would normally invoke this as something like http://localhost/path/ sumAndDifference.php. 11. Using XML-RPC with Microsoft .NET (This section of the XML-RPC HOWTO was generously provided by Charles Cook.) Charles Cook has implemented XML-RPC for Microsoft's .NET environment. You can find his XML-RPC.Net library at the_Cook_Computing_website. The following code requires the .NET SDK to be installed. To build and run XML- RPC.Net client and server applications, unzip cookcomputing.xmlrpc.dll from the XML-RPC.Net distribution and copy to the required directories. XML-RPC.Net is compliant with the Common Language Specification and so can be used to build XML-RPC clients and servers using any CLS-compliant programming language. At the time of writing this means the languages provided by Microsoft—C#, VB.Net, JScript, and Managed C++—but in the future will include other languages such as Eiffel, Perl and Python. sample.sumAndDifference client and server samples are presented here in both C# and VB.Net. The client samples make synchronous calls but it is also possible to make asynchronous calls—refer to the XML-RPC.Net documentation for further information. 11.1. A C# Client Save the following code in a file called getSumAndDiffCS.cs: using System; using CookComputing.XmlRpc; public struct Result { public int sum; public int difference; } [XmlRpcUri( "http://aspx.securedomains.com/cookcomputing/sumanddiffvb.aspx")] class Proxy : XmlRpcClientProtocol { [XmlRpcMethod("sample.sumAndDifference")] public Result SumAndDifference(int x, int y) { return (Result)Invoke("SumAndDifference", new Object[]{x,y})[0]; } } public class App { public static int Main(string[] args) { try { Proxy theProxy = new Proxy(); Result ret = theProxy.SumAndDifference(5, 3); Console.WriteLine("5 + 3 = {0}", ret.sum); Console.WriteLine("5 - 3 = {0}", ret.difference); } catch(XmlRpcClientException cex) { Console.WriteLine("Client exception: {0} {1}", cex.FaultCode, cex.FaultString); } catch(XmlRpcFaultException fex) { Console.WriteLine("Server exception: {0} {1}", fex.FaultCode, fex.FaultString); } return 0; } } Use the following command to build the client: csc /r:cookcomputing.xmlrpc.dll getSumAndDiffCS.cs 11.2. A Visual Basic .NET Client Save the following code in a file called getSumAndDiffVB.vb: Imports CookComputing.XmlRpc Module Module1 Structure Result Dim sum, difference As Integer End Structure Class _ Proxy : Inherits XmlRpcClientProtocol Public Function _ SumAndDifference(ByVal x As Integer, ByVal y As Integer) As Result Dim results As Object() = Me.Invoke("SumAndDifference", _ New Object() {x,y}) Return CType(results(0), Result) End Function End Class Sub Main() Dim theProxy As New Proxy() Try Dim ret As Result = theProxy.SumAndDifference(5, 3) Console.WriteLine("5 + 3 = {0}", ret.sum) Console.WriteLine("5 - 3 = {0}", ret.difference) Catch cex As XmlRpcClientException Console.WriteLine("Client exception: {0} {1}", _ cex.FaultCode, cex.FaultString) Catch fex As XmlRpcFaultException Console.WriteLine("Server exception: {0} {1}", _ fex.FaultCode, fex.FaultString) End Try End Sub End Module Use the following command to build the client: vbc /r:cookcomputing.xmlrpc.dll getSumAndDiffVB.vb 11.3. A C# Server XML-RPC.Net enables the implementation of XML-RPC Services running in the IIS 5 web server environment. Save the following code in a file called SumAndDiffCS.cs: using System; using CookComputing.XmlRpc; public struct Result { public int sum; public int difference; } [XmlRpcService(Description= "Sample XML-RPC.Net Service implemented in C#")] public class SumAndDiffService : XmlRpcService { [XmlRpcMethod("sample.sumAndDifference", Description= "This function takes two integers as arguments and returns an "+ "XML-RPC struct containing two elements: sum, the sum of the "+ "two integers, and difference, the difference between the two "+ "integers")] public Result SumAndDifference(int x, int y) { Result ret; ret.sum = x + y; ret.difference = x - y; return ret; } } Use the following to build the client: csc /r:System.Web.dll,cookcomputing.xmlrpc.dll /target:library SumAndDiffCS.cs Create an IIS virtual root, say cookcomputing for this example, and a bin directory underneath it. Place the assembly (SumAndDiffCS.dll) and the XML- RPC.Net assembly (cookcomputing.xmlrpc.dll) in the bin directory. Create a text file called config.web in the cookcomputing root directory with the following contents: The Service is now installed and configured. To check this navigate your browser to the URL of the Service where you will see an automatically generated documentation page. 11.4. A Visual Basic .NET Server Save the following code in a file called SumAndDiffVB.cs: Imports System Imports CookComputing.XmlRpc Public Structure Result Dim sum, difference As Integer End Structure Public Class _ SumAndDiffService : Inherits XmlRpcService Public Function _ SumAndDifference(ByVal x As Integer, ByVal y As Integer) As Result Dim ret As Result ret.sum = x + y ret.difference = x - y Return ret End Function End Class Use the following to build the client: vbc /r:System.Web.dll,cookcomputing.xmlrpc.dll /target:library SumAndDiffVB.vb Create an IIS virtual root, say cookcomputing for this example, and a bin directory underneath it. Place the assembly (SumAndDiffVB.dll) and the XML- RPC.Net assembly (cookcomputing.xmlrpc.dll) in the bin directory. Create a text file called config.web in the cookcomputing root directory with the following contents (note that the entries are case sensitive): The Service is now installed and configured. To check this navigate your browser to the URL of the Service where you will see an automatically generated documentation page. 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: bash$ tar -xvzf xmlrpc4r-1_2.tar.gz bash$ cd xmlrpc4r-1_2 bash$ su root -c "ruby install.rb" 12.1. A Ruby Client Here's a simple Ruby client: require "xmlrpc/client" # Make an object to represent the XML-RPC server. server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") # Call the remote server and get our result result = server.call("sample.sumAndDifference", 5, 3) sum = result["sum"] difference = result["difference"] puts "Sum: #{sum}, Difference: #{difference}" 12.2. A Ruby Server Here's a simple Ruby server: require "xmlrpc/server" s = XMLRPC::CGIServer.new s.add_hanlder("sample.sumAndDifference") do |a,b| { "sum" => a + b, "difference" => a - b } end s.serve This could also have been written as follows: require "xmlrpc/server" s = XMLRPC::CGIServer.new class MyHandler def sumAndDifference(a, b) { "sum" => a + b, "difference" => a - b } end end s.add_handler("sample", MyHandler.new) s.serve To run either server in standalone mode, replace the second line of code with the following: s = XMLRPC::Server.new(8080) 13. Using XML-RPC with Proprietary Languages Implementations 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: \l kxr server:("localhost";"/cgi-bin/sumAndDifference.cgi"); .kxr.c[server;"sumAndDifference";2 3] And here's a server: \l kxrsc .kxr.sm: ,("sumAndDifference";{.((`sum;+/x);(`difference;-/x))}) More examples are included in the distribution. 14. Applications with Built-in XML-RPC Support Several popular Linux applications include support for XML-RPC. These have already been described elsewhere, so we mostly provide pointers to articles. 14.1. Zope Articles on using XML-RPC with Zope are available elsewhere on the web: * XML-RPC_Programming_with_Zope by Jon Udell * Zope_XML-RPC at UserLand.Com 14.2. KDE 2.0 KDE 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, “Submitting_Other_Snippets”. We'd like to have more information on scripting KDE. 15. About This Document This 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 Document New 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 HOWTO The 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 Snippets If 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: * The URL of the XML-RPC implementation used. * Installation instructions. * A complete, runnable program. * Compilation instructions, if applicable. E-mail your example to the xmlrpc-c-devel_mailing_list or directly to Eric Kidd. Thank you for your help!