RB XML-RPC

SourceForge.net Logo

Introduction

XML-RPC is a simple, lightweight, platform and language-agnostic form of inter-application communication. So if you want to make a quick and easy client-server application, this could be for you. If you want to make a simple peer-to-peer application, this could also be for you. Or if you want to connect to tools written in Java, perl, .NET, PHP, or any of many other languages you can do that easily with XML-RPC. Check out Dave Winer's site: www.xmlrpc.com for more info

Features

This RB 3.5 client implementation of XML-RPC for Real Basic has been tested with PPC Mac OS 9, Mac OS X, and Win32. It is grown from Sam Devore's original implementation, and now has full support for auto-type mapping. This means that when you communicate with other apps, you always deal with simple RB objects. The architecture is also fully revamped, letting you deal with client, request, and response objects. All the latest versions of httpsocket and XML Toolkit are used.

You should also be able to catch xmlrpcexceptions, using the provided class, and also see the xml-rpc source messages as they come and go over the wire. See the demo app for an example.

There really isn't much more to it than that. Enjoy.

History

I first started using Sam Devore's original XML-RPC implementation in October of 2001 <http://realbasicprinting.weblogs.com/xmlrpc/>. It was a great start, and worked perfectly. I needed to integrate this communication into a fairly large project, for which we were using XML-RPC as the method of interapp communication. For the curious, the project consists of a fully searchable object database implemented in a RDBMS (ie you can store any XML document you want, and you can search by any field or through all fields to retrieve your document). Maybe I will be allowed to release that too one day. Anyway, we needed a more complete implementation of XML-RPC for RB, so we spent a few days and came up with a pretty decent, transparent implementation. Now, RB XML-RPC is moving to sourceforge, to let other developers contribute to the upkeep of the library, ensuring its compatibility with the latest versions of REALbasic, OS's, and libraries.

Download

You'll want to head over to the project summary for info on how to download the latest RB XML-RPC from sourceforge.

You can download the 1.0.4 source distribution here. This will be the last distribution from this site, as this project is transitioned to sourceforge. RealBasic 4 and 5 have replaced some of the included libraries (hash and socket), and OS X 10.2.6 don't run the demo properly. The sourceforge site uses the latest OS and RealBasic versions.

Project Installation

All dependencies required for RB XML-RPC are included in the distribution. You don't have to download anything else. The demo app shows how all dependencies should be included.

Install the XML Toolkit (Amar Sagoo asagoo@gmx.net) first by dragging the XMLElement class onto your project, followed by all the remaining classes. Place these all in a project folder if desired.

There is a patch to XML Toolkit 2.01 that you will need in order to run on Windows. Replace the XMLToolkitGlobals module that came with the kit with XMLToolkitGlobalsPatch by dragging it onto your project. This patch also fixes a problem whereby no tag greater than 1024 bytes can be processed.

Install the dynamic sockets version of httpSocket (Dan Vanderkam dantheox@aol.com) by dragging the httpmodule and httpsocket (small) class onto your project.

Install the base64 methods (Doug Holton doug.holton@vanderbilt.edu) by dragging that module onto your project.

Install XML-RPC by dragging the class files in that folder onto your project. Much credit is given to Sam DeVore sdevore@teachesme.com for his initial work with XMLRPC in RealBasic.

Quick Docs

Hash is a quick class implementing associative arrays. This version extends the collection class, so anything can be stored in them (as variants), and is accessed either by an integer index or a string key (RB collection keys can't be accessed, thus the reason for this class). Do not use the add, item or remove methods of the collection super class. Use the ones provided with this class ( set, get, getAt, and getKeyAt).

Make sure you call initHTTPmodule before you start any XML-RPC calls (usually in the Open event of your app). This initiallizes the httpSocket. Begin an XML-RPC session by instantiating an XMLRPC client with the server name, port and path.

Set up an xmlrpc request by instantiating a request object and then adding parameters to it. All XML-RPC types are supported. Look at the mapping below for more info.

Then, execute the request by passing the request object to the execute method of the XML-RPC client. This will return a response object. Typically, you will then assign the value from the response object to a variable that you have predeclared. Here is a simple example:

 dim c as xmlrpcclient
 dim req as request
 dim res as response

 dim users as collection

 dim i, ct as integer

 c = new xmlrpcclient("cool.host.com", 80, "path/to/cgi")
 req = new request("member.getAllUsers")
 res = c.execute(req)

 if res.faultcode > 0 then 
   msgBox ("Error " + str(res.faultCode) + ": " + res.faultString)
 else
   users = res.getValue()
   ct = users.count
   for i = 1 to ct
     msgBox users.item(i)
   next
 end if

Look at the mapping below for more info, and check out the demo app for an example of how to create/map each XML-RPC type. The demo app has been tested successfully on OS 9.1, OS X and Win32.

XML-RPC to RB Mapping

XML-RPC
RealBasic
string string
int / i4 integer
double double
boolean boolean
dateTime.iso8601 date
base64 string
array collection
struct hash (via provided class)

History

June 13, 2003 (1.0.4)
- moved RB XML-RPC to sourceforge, start on 1.1 release
August 12, 2002 (1.0.4)
- updated demo app with new server location
April 16, 2002 (1.0.3)
- change boolean values to 1/0 from true/false (Ward Clark)
April 10, 2002 (1.0.2)
- handle RB4 object type (thanks to Ward Clark)
- handle <value> tag with no type specification (thanks to Ward Clark for pointing this out)
April 4, 2002 (1.0.1)
- handle http socket errors and timeouts
December 14, 2001 (1.0b1)
- first public release
October 15, 2001 (0.9)
- first internal alpha

Credit

RB XML-RPC is released under the artistic license. If you use RB XML-RPC, please give me and others credit :-)

Don't hesitate to email me any questions, suggestions, etc.

If you make any changes to the code, and you think they would be useful additions to the codebase, let me know! We can add you as a developer so you can contribute.

Julian Wood woodj@ucalgary.ca
University of Calgary