Current Version: 1.02

Demo online here(download below).

Index:

1. Introduction
2. Web Services
   • XML-RPC, one possible solution.
3. The Class
   • The Properties
   • The Methods
   • The Native Object
   • How to use it
4. Download
5. Credits & License

1. Introduction

Many may ask.. "another xml-rpc lib?", and the answer is "YES"! There is another xml-rpc lib for Flash available here.
After analysing that lib, I realized that it was too complicated for an ordinary programmer to use it, and too boring even for experienced programmers to use it in large projects.
I then decided to build this lib, which was as powerfull as the other one, but much more easy to use. Now a programmer who doesn't know how to work with XML, can send and receive XML-RPC data seamlessy, like if it was AS data. And because I didn't forget the "power-users", it lets you define the data-types by hand (like the other lib did).
After said this, if your new to the world of XML and Web Services, please read the next chapter, otherwise you may proceed to chapter 3.

2. Web Services

  You have probably heard by now the word "Web Service" and you' re probably asking, what's this "web thing" all about?
Well.. a Web Service is.. a service on the Internet. (ahah, great explanation dude). Imagine the Yellow Pages, they are a service holder, you can find a phone number at any time. Imagine if there was a place on the Internet where you could do the same?
And you can, I mean, I don't know about looking in the Yellow Pages, but you can do it with your bank account information. You're probably saying by now, "Sure I 'd visit a web page with that kind of information!", but what if you wanted to make that data accessible to different computer applications?.
  Well my friend, Web Services are the answer for that, they are computer applications which serve other computer applications.
  And because your tired of this Web Services talk, let's introduce XML-RPC:

XML-RPC, one possible solution.

  Because there's are so many different applications, operating systems, and platforms on the Internet today, standard protocols of communication between the applications and the Web Services were created, being XML-RPC one of them (there are others like SOAP).
   With XML-RPC you call a method in the server, for which he returns some parameters. The parameters you send and receive range from simple scalar values (like strings, integers, doubles) to arrays and objects(aka struct).
  For more information on the XML-RPC capabilities please read the spec here.

3. The Class

  The Properties

  AUTO_FORMAT (defaults to True) - When this property is set to true, after parsing the response a ready-to-use object will be passed to the callback function. If the property is set to False a native XML-RPC object will be passed.
  NParameters - Returns the number of parameters that were returned in a reply to a method call.
  callBack - This is a reference to a function that will be called when loading is complete.

  The Methods

  xmlrpc(path_to_server) - The constructor function.

path_to_server - (Required) The path to the server that is runnig the service, ex: "http://mydomain.com/cgi-bin/webservice.php"

Example:
    rpc = new xmlrpc("scripts/servfoo.php");

  send(methodName, arOfParams) - This function must be called to send the method call, and wait for the reply.

methodName - (Required) The name of the method/function that is being called on the server.
arOfParams - (Optional) An Array of parameters(in Native Format) to be passed with the method call.

Example:
   rpc.send("admin.login",[username,password]); // Both username and password are already in the Native Object Format

  setParameter(objToTransform, objType) - This function will convert an ordinary scalar, array or object into the Native Object Format.

objToTranform - (Required) The value, array or object to transform.
objType - (Optional) You can pass the data type (see The Native Object for more information on data types).

Example:
     param1 = rpc.setParameter({name: Foo, nickname: Bar});
   param2 = rpc.setParameter("hello");
   rpc.send("testMethod",[param1,param2]);

 

  getParameters(objToTransform) - This function will convert a reply parameter to an ordinary AS data type (scalar, array or object), normally you will only have to use this function if AUTO_FORMAT is set to False;

objToTransform - An array of Native Object Types.

Example:
   calledBack = function(errorCode,parameters) {
         /*parameters is a Native Object Type*/
         ordinary = rpc.getParameters(parameters);
         /*ordinary is a regular array with values*/
         /*If the only parameter being passed was a string, you could show like*/
         trace(parameters[0].values);
         trace(ordinary[0]);
   }
   rpc = new xmlrpc("server.php");
   rpc.callBack = calledBack;
   rpc.send("methodFoo",["bar"]);

  The Native Object

  The Native Object is a formatted object, with contains a description of an XML-RPC Value. An XML-RPC value can be one of the following data types:

• int (Integer)
• double
• string
• boolean
• dateTime (iso8601)
• base64
• array
• struct

And this are the exact (case-sensitive) data types you can put in Native Object.
The Native Object Format is: { dtype: dataType, values: value or an array of Native Objects }
The struct has one more property - name.

  Example:

/*Simple string parameter*/
str = {dtype: "string", values: "foobar" };
/*Other simple scalar value - an integer*/
integer = {dtype: "int", values: 456 };
/*A complex data type - an array*/
arr = {dtype: "array", values: [str, integer]};
/*Other complex data type - a struct*/
struct = {dtype: "struct", value [
{dtype: "string", name: "aString", values: "foobar"},
{dtype: "int", name: "anInteger", values: 456}
]};

  How to use it

  Well it's pretty simple actually. Use just have to a create a class instance, gather the parameters you want to send, define a callback funtion, send the method call, and wait for the reply in the callback funtion.

Example:
#include "xml-rpc.as"

calledBack = function(errorCode,parameters) {
      /*parameters is a Native Object Type*/
      ordinary = rpc.getParameter(parameters);
      /*ordinary is a regular array with values*/
      /*If the only parameter being passed was a string, you could show like*/
      trace(parameters[0].values);
      trace(ordinary[0]);
}
rpc = new xmlrpc("server.php");
params = rpc.setParameter(["one","two"]);
rpc.callBack = calledBack;
rpc.send("methodFoo",[params]);

  The callback function returns an error code, and aditional parameters:

4. Download

xml-rpc.as
xml-rpc.zip (the .as, this .htm and the example)
xml-rpc.protolink.as (I will make a protolink compatible version in the future)

 

5. Credits & License

XML-RPC Flash Lib V 1.02
------------------------------------
Created By: Pedro Ornelas (killer@netmadeira.com)

Based on: Dave Winer's XML-RPC Specification

Tested with: Flash MX
Edd Dumbill's XML-RPC lib for PHP 1.02

New changes: -The ASSetPropFlag was missing, now it's there.

#V1.0.1# -A small bug was fixed, the object couldn't be reused after the first request
         -ASSetPropFlag was added to the beggining, so that an array.prototype property doesn't interfere with the for..in loops
         -The automatic escaping and unescaping of strings was removed

History: -(04/02/2002) The lib was completed and released

## LICENCE ##
You may use this library for individual and commercial purposes free of charge,
but you must keep this header in your source files.
A reference to this library and the author would be nice. :)
## END OF LICENSE ##