Indonesian

HXP Server


In order for an application to receive procedure calls coming from a remote application and respond with the needed data, it should have an HXP server created and installed.

Creating a server

Creating a HXP server is very easy and straightforward by using a ready made library. Below is an explanation on how to create a basic HXP server based on the Incutio IXR library for the php programming language. Other libraries for other languages should have similar methods for creating the server.

Basic Server Construction

Basic HXP servers based on IXR library are constructed using the IXR_Server class. The methodology is simple - create PHP functions (or class methods if you want to go the OOP route), then call the IXR_Server constructor with an array that "maps" XML-RPC method names to the names of your functions. The IXR_Server class will then call the relevant functions based on information from the client.

Your callback functions can return normal PHP variables (strings, integers, arrays, indexed arrays or even objects) and IXR will convert the return values in to an XML-RPC response and send it back to the client.

Here is a simple HXP server (based on IXR, php):

<?php

include('IXR_Library.inc.php');

function PersonNameLast($args) {
    return 'Rodriguez';
}
function PersonNameFirst($args) {
    return 'Jonathan';
}
$server = new IXR_Server(array(
    'Person.Name.Last' => 'PersonNameLast',
    'Person.Name.First' => 'PersonNameFirst'
));


?>

The above code will create an XML-RPC server with two available methods which accepts a struct and an integer as arguments- Person.Name.Last returns the string 'Rodriguez', and Person.Name.First which returns the string 'Jonathan'. Of course, in real implementation, the function's internal routine will access the database, get the name of the patient based on the PID number which was passed as a second argument and return the name.

Note that both of the callback functions accept a single argument - $args. $args is an array of paramaters received from the XML-RPC client. If there is only one argument, $args will be that argument rather than an array with only one element.

Header arguments and authentication data

Each function accepts a compulsory heading argument as the first parameter ($args[0]). This parameter is an indexed array (RPC's struct) and must contain by default the following keys and data:
usr Username
pw Password
emergency (integer) 1
(If the call is done in "emergency". Can be left unset in normal cases.)
When the header argument is missing, the application will return an error code 1000 and the descriptive string "_ERROR_AUTH_BADHEADER".

By default, the "emergency" key is either not available or set to 0 or empty character.

lang Language code
sid session ID
version HXP version (e.g. 1.0, 1.0.3)
The HXP server should be have the functions to inform an inquiring client of the availability of optional keys by including the following system procedure calls:
	system.Header.Keys.lang
	system.Header.Keys.sid
	system.Header.Keys.version
If the key is supported by the application, the function should return the value of integer 1.

Other keys and data can be added according to the application's design but these are not considered standard and should be properly documented and published. Once these added keys and data get widespread acceptance or when they were proposed for addition and approved, they will be included as standard header keys and published in the next PCD (Procedure Call Dictionary) version.

Sending Errors

XML-RPC has a flexible error system, which you can use in your server implementations. An XML-RPC error consists of an error number (an integer) and a descriptive string. The number you use is pretty much up to you as the application developer, but it is important you keep a consistent numbering scheme. You can send errors back to the client using the following code:

function ErrorMessage($args) {
    if ($args[0]['pw'] != 'thesecretpassword') {
        return new IXR_Error(1002, '_ERROR_AUTH_USER');
    }
    // Rest of function here
}

The above function will return an error if the first argument sent by the client is anything other than 'thesecretpassword' - it can be used to form a very basic (and not particularly secure) authentication system.

HXP error codes

Error codes of HXP start at 1000. The following codes are draft proposals version 0.1.

1000 _ERROR_AUTH_BADHEADER Bad or missing header argument/parameter
1001 _ERROR_AUTH_USER Wrong user.
1002 _ERROR_AUTH_PW Wrong password.
1003 _ERROR_AUTH_AREA No permission for the protected area.
1004 _ERROR_AUTH_LOCKED The user permission is locked.
1005 _ERROR_SQL_FAILED The sql query failed.
1006 _ERROR_SQL_NOINSERT The sql insert query failed
1007 _ERROR_SQL_NOUPDATE The sql update query failed
1008 _ERROR_NORESULT The procedure returned no result.
1009 _ERROR_PROC_NOSUPPORT The procedure is not supported
1010 _ERROR_PROC_NOEXISTS The procedure is not available
1011 _ERROR_PROC_INACTIVE The procedure is inactive or deactivated
1012 _ERROR_DATA_INCOMPLETE The data is incomplete (mostly the input data)
1012 _ERROR_DATA_INVALID The data is invalid (mostly the input data)

Dates and base64 encoded data

XML-RPC has support for two types that do not have a direct corresponding type in PHP - dates and base64 encoded data. To return data in these formats, you can use the following:

function myFunction($args) {
    $data = 'a string to be transmitted as base64 encoded data';
    $time = time();
    return array(
        'data' => new IXR_Base64($data),
        'time' => new IXR_Date($time)
    );
}

The above function returns an indexed array (an XML-RPC struct) consisting of a base64 encoded data chunk and an iso encoded date. As you can see, the details of the encoding are kept hidden from the web service programmer.

The Object Oriented Approach

Creating a HXP server with callback functions is all well and good, but IXR can also be used to create a HXP server as PHP classes. This can be achieved by creating a server class that extends IXR_Server and defining methods that you wish to use as XML-RPC procedures in the new class. You can then call the IXR_Server constructor with the now familiar callback array, with one small difference - each of your callback functions should be prefixed with "this:", to inform IXR that you wish to call a class method rather than a normal function.

Here is the above simple HXP server implemented using OOP:

<?php

include('IXR_Library.inc.php');

class HXP_Server extends IXR_Server {
    function SimpleServer {
        $this->IXR_Server(array(
            'Person.Name.Last' => 'this:PersonNameLast',
            'Person.Name.First' => 'this:PersonNameFirst'
        ));
    }
	function PersonNameLast($args) {
		return 'Rodriguez';
	}
	function PersonNameFirst($args) {
    	return 'Jonathan';
	}
}

$server = new HXP_Server();

?>

Server construction with other languages

Please refer to the documentation of the library that you wish to use.


©2004 Elpidio Latorilla. All rights reserved