Gethoper's Blogger

Documentation: services/call.php - Yet Another Community System

Documentation: services/call.php - Yet Another Community System
Documentation: services/call.php

Browse the source of this script · All scripts

* Class Call - Web service client broker
* Implementing different protocol
* Invoke() - Call a web service
* List_resources() - Get some service remotely

Class Call - Web service client broker
This script is a skeleton used to build actual web service, whether it be XML-RPC, Packeteer API, or whatever else. Basically, it has the glue necessary to interface with YACS client and server API.

When some script has to invoke some remote service it has to provide following information:

* the name of the targeted service
* adequate parameters

After the call, the calling script has to fetch and to process the result of the remote process.

For example, the remote search facility is implemented quite easily in search.php:


// search at other sites
include_once 'parameters/hooks.include.php';
if(is_callable(array('Hooks', 'call_scripts'))) {
$parameters = array( 'search' => $_REQUEST['search'],
'output_spec' => array('output_format' => 'slashdot') );
if($rows = Hooks::call_scripts('search.php#call', $parameters)) {
$context['text'] .= Skin::build_block(i18n::s('title'), 'title');
$context['text'] .= Skin::build_list($rows, 'decorated');
$no_result = FALSE;
}
}





Within YACS the actual binding of the service to a network address and to some protocol is achieved through some hooks definition.


// client hook to some web service
global $hooks;
$hooks[] = array(
'id' => 'search.php#call',
'type' => 'call',
'link' => 'http://127.0.0.1/yacs/broker.php',
'service' => 'search',
'label_en' => 'Remote search',
'label_fr' => 'Recherche distante',
'description_en' => 'Example of remote search configuration.',
'description_fr' => 'Exemple de configuration pour recherche distante.',
'source' => 'http://www.yetanothercommunitysystem.com/'
);





The hook is automatically converted by control/scan.php into a call to Call::invoke() to actually handle the transport layer between the client and the server. For example, the previous declaration appears into parameters/hooks.include.php as:


function call_scripts($id, $parameters) {
global $local;
include_once $context['path_to_root'].'services/call.php';

switch($id) {
case 'search.php#call':
$result = array_merge($result,
Call::invoke('http://127.0.0.1/yacs/broker.php', 'search', $parameters));
break;
}

return $result;
}





Implementing different protocol
By default the XML-RPC protocol is used between the client and the server. However other options may have to be considered to adapt to other constraints. For example Packeteer, as others, has its own implementation of XML-over-HTTP for web services.

To select among available protocols you have to specify it on the client side like this:


// query a PacketShaper from Packeteer
$variant = 'packetwiseAPI';
if($data = Hooks::call_scripts('search.php#call', $parameters, $variant)) {
...





This script is a reference file of this system.

See also:

* services/configure.php

License: GNU Lesser General Public License

Authors:

* Bernard Paques bernard.paques@bigfoot.com

invoke() - Call a web service

function invoke($url, $service, $parameters = NULL, $variant='XML-RPC')

* $url - string the url to use
* $service - string the service to call
* $parameters = NULL - array the parameters to transmit
* $variant='XML-RPC' - string the protocol to use
* returns an array of which the first value indicates call success or failure

Minimum example:


$result = Call::invoke($url, $method);
if(!$result[0])
echo $result[1]; // error message
else
... // use call result from $result[1]





Note that in a previous version data was encoded. Unfortunately, most servers do not handle encoding, despite it's a useful web standard.

See also:

* control/scan.php
* links/links.php
* servers/servers.php
* services/blog_test.php

list_resources() - Get some service remotely

function list_resources($url, $parameters = NULL)

* $url - string the url to use
* $parameters = NULL - array the parameters to transmit
* returns an array of which the first value indicates call success or failure

This function is aiming to support REST calls to remote resources.

Minimum example:


$result = Call::list_resources($url);
if(!$result[0])
echo $result[1]; // error message
else
... // use call result from $result[1]

posted by BillyIdiot(gethoper) @ 11:09 AM