User Tools

Site Tools


k27:k27.5:k27.5.1:start

27.5.1 RpcServer class

You can create an object of the class RpcServer (gb.xml.rpc) in this way:

Dim hRpcServer As RpcServer
hRpcServer = New RpcServer() As "EVENT-NAME"

27.5.1.1 Properties

The class RpcServer has exactly two properties:

PropertyData typeDescription
CountIntegerSpecifies the maximum number of allowed connections.
ListeningBooleanIs true when the RPC server listens on the specified port.

Table 27.5.1.1.1: RpcServer class properties

27.5.1.2 Methods

Here you can find a description of the methods of the class RpcServer:

MethodDescription
Lists (Port As Integer, MaxConn As Integer)The server listens at the specified port.
Register (remoteFunction As RpcFunction)The specified Rpc function is registered on the server.
Unregister (methodName As String)The registered method is removed from the list of registered methods.
SetReply (Data As Variant)The function value of the called RPC function is sent to the client.
Stop ()Stops the RPC server and destroys the RPC server object.

Table 27.5.1.2.1: Methods of the class RpcServer

27.5.1.3 Events

The class RpcServer has only one event:

RemoteCall(Method As String, Params As Variant[])

The event is triggered when a request is received by a client and the function (method) to be called is passed with the required arguments as a variant array (params). In the event handling routine, the requested function is selected in the list of registered methods by its name in a selection control structure and the assigned (internal) procedure for calculating the function value with the input arguments is called, in which the function value is returned to the client (response) with the Gambas procedure RpcServer.SetReply(…):

Public Sub hXMLRPC_RemoteCall(sMethod As String, aParameters As Variant[])
 Select Case sMethod
    Case "add2integer" ' 1. Service
      Sum(aParameters)
  End Select
End
 
Public Sub Sum(aParameters As Variant[])
 hXMLRPC.SetReply(aParameters[0] + aParameters[1])
End

27.5.1.4 Project XML-RPC-Server

The XML-RPC-Server presented here uses the class RpcServer and, after starting, provides only the one function 'add2integer' as a local service on the system on port 1088 next to the 3 (standard) methods for inspecting the server → chapter 27.5.2 XML-RPC-Client. The source code for the server in a module contains surprisingly few lines:

' Gambas module file
 
Public hXMLRPC As RpcServer
 
Public Sub Main()
 
  Dim hXMLRPCFunction1 As RpcFunction
  Dim iXMLRPCPort, iXMLRPCServerMaxConnections As Integer
 
  hXMLRPC = New RpcServer As "hXMLRPC"
  iXMLRPCPort = 1088 ' This Port officially not used or reserved
  iXMLRPCServerMaxConnections = 10
 
  hXMLRPCFunction1 = New RpcFunction("add2integer", [XmlRpc.xInteger, XmlRpc.xInteger], XmlRpc.xInteger)
  hXMLRPCFunction1.Help = ("Addition of 2 integers")
  hXMLRPC.Register(hXMLRPCFunction1)
 
  Try hXMLRPC.Listen(iXMLRPCPort, iXMLRPCServerMaxConnections)
  If Error Then
     Print ("Error-Text: ") & Error.Text & gb.NewLine & ("Error-Location: ") & Error.Where
     hXMLRPC.Unregister(hXMLRPCFunction1.MethodName)
     hXMLRPC.Stop()
  Endif
  If hXMLRPC.Listening Then
     Print ("The XMLRPC server listens for port ") & Str(iXMLRPCPort)
  Endif
 
End
 
Public Sub hXMLRPC_RemoteCall(sMethod As String, aParameters As Variant[])
  Select Case sMethod
    Case "add2integer" ' 1. Service
      Sum(aParameters)
  End Select
End
 
Public Sub Sum(aParameters As Variant[])
  hXMLRPC.SetReply(aParameters[0] + aParameters[1])
End

Only a few additional or additional lines are required to implement another service:

Dim hXMLRPCFunction1, hXMLRPCFunction2 As RpcFunction
 
hXMLRPCFunction2 = New RpcFunction("sub2integer", [XmlRpc.xInteger, XmlRpc.xInteger], XmlRpc.xInteger)
hXMLRPCFunction2.Help = ("Subtraction of 2 integers")
hXMLRPC.Register(hXMLRPCFunction2)
 
  Select Case sMethod
    Case "add2integer" ' 1. Service
      Sum(aParameters)
    Case "sub2integer" ' 2. Service
      Sub(aParameters)
  End Select
 
Public Sub Sub(aParameters As Variant[])
  hXMLRPC.SetReply(aParameters[0] - aParameters[1])
End

When the RPC server is inspected again, an RPC client displays the added service in the list of implemented functions on the RPC server:


Figure 27.5.1.4.1: List of implemented services (functions)

27.5.1.5 Project PHP-XML-RPC-Server

The server in the second project also offers a service. The XML RPC server is always started when the PHP file xmlrpc. server. php is called in the web folder public_html. However, this requires that an appropriately configured HTTP server is running on your system. Chapter 24.13_Exkurs_Webserver_LIGHTTPD describes in detail the installation and configuration of this HTTP server, which is fully recommended!

As in the first project, add2integer is implemented as RPC function.

This is the content of the PHP server file, which accesses several libraries of Edd Dumbill. The libraries must be stored in the ~/public_html/rpclib directory, because the PHP script expects them there. The two required libraries are made available to you as an archive.

<?php
 
// Kamil: Complete, simplest possible XMLRPC Server implementation
 
include "rpclib/xmlrpc.inc";     // from http://phpxmlrpc.sourceforge.net/ - version 3
include "rpclib/xmlrpcs.inc";    // from http://phpxmlrpc.sourceforge.net/ - version 3
 
// function that handles add2integer XML-RPC method
// function "mapping" is defined in 'new xmlrpc_server' constructor parameter.
function add2integer ($xmlrpcmsg)
{
    $summand_1 = $xmlrpcmsg->getParam(0)->scalarval(); // first parameter becomes variable $summand_1
    $summand_2 = $xmlrpcmsg->getParam(1)->scalarval(); // second parameter becomes variable $summand_2
 
    $result = $summand_1 + $summand_2; // calculating result
 
    $xmlrpcretval = new xmlrpcval($result, "int");   // creating value object - type integer
    $xmlrpcresponse = new xmlrpcresp($xmlrpcretval); // creating (new) response object
 
    return $xmlrpcresponse; // returning response
}
 
// creating XML-RPC server object that handles only 1 method
$s = new xmlrpc_server(
     array(
       "add2integer" =>  array( // xml-rpc function/method name
       "function" => "add2integer", // php function name to use when "add2integer" is called
       // signature with defined IN and OUT parameter types
       "signature" => array(array($xmlrpcInt, $xmlrpcInt, $xmlrpcInt)),
       "docstring" =>  'Returns sum = summand1 + summand2' // description of method
     )));
 
?>

Note: If you are using the basic installation of PHP on your operating system, you may need to install the extension package 'php5-xmlrpc' or 'php-xmlrpc' and then restart your web server. The web server Lighttpd was used for testing the project.

Download

The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k27/k27.5/k27.5.1/start.txt · Last modified: 12.05.2022 (external edit)

Page Tools