 |
English  |
|
|
HXP Server
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 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-
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: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. 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.versionIf 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 Konsep proposal version 0.1.
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 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. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||