GAMBAS BOOK 3.19.5

• XML-RPC is a simple, language-independent protocol for remote function calls over a local network or the Internet, which has also been implemented in gambas.
• XML-RPC allows function calls over the HTTP protocol. The term' Remote Procedure Call' or RPC stands for remote function calls.
• XML is used to encode the transfer parameters to the remote procedures on an RPC server but also to encode the function values. Hence the name XML-RPC.
• An XML RPC server provides an interface for remote access to a list of implemented functions. This list can be retrieved from an RPC client.
• XML-RPC works according to the client-server model: A function call from an XML-RPC client is sent via HTTP-POST to an XML-RPC server (request) that offers a service via a list of implemented functions that can be called by a client with appropriate arguments. Note that arguments in XML-RPC do not have a name. The position of an argument alone determines its meaning! The server evaluates the XML document contained in the body (HTTP-POST) and uses its contents as arguments for calling the required function. The function value is again' packed' in XML and transferred to the calling XML RPC client (response). In addition to native data types such as DateTime (ISO_8601: https://de.wikipedia.org/wiki/ISO_8601), Boolean, Integer, String, Float or Base64, arrays (RpcArray) and the data type Struct (RpcStruct) are also supported by the component gb. xml. rpc.

Thomas Bayer presents a complete example of an introduction to XML-RPC functionality in an application-related article at https://www.oio.de/public/xml/xml-rpc.htm

The following notes should not be missing in this book chapter: The gb. xml. rpc component uses its own internal mini HTTP server to provide XML-RPC services. The component is not designed to use the internal mini HTTP server in the same way as PHP web services, for example. RPC is therefore not a web service in the usual sense - but a service provided by a local HTTP server. An XML RPC server is an HTTP server, just like Apache2 or Lighttpd. Unlike the aforementioned servers, XMLRPC servers do not normally run on port 80 and do not deliver Web pages.

The component gb.xml.rpc has the classes RpcServer, RpcClient, RpcFunction, RpcArray, RpcStruct and RpcType. The classes RpcServer and RpcClient are described in separate chapters. The relevant projects are also presented there.

The client request (Request) and the server response (Response) each contain a multiline XML section containing the arguments (Request) or the function value (Response). For the project with the arguments summand1=12 and summand2=8 and the function value summe = 20, the XML sections look like this:

Request extract:

POST /RPC HTTP/1.1
...
Content-Length: 230
Content-Type: text/xml
<?xml version="1.0"?>
<methodCall>
  <methodName>add2integer</methodName>
  <params>

    <param>
      <value><int>12</int></value>
    </param>
    <param>
      <value><int>8</int></value>
    </param>

  </params>
</methodCall>

Response neck:

...
<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <int>20</int>
      </value>
    </param>
  </params>
</methodResponse>

You can create an object of the class RpcFunction (gb. xml. rpc):

Dim hRpcFunction As RpcFunction
hRpcFunction = New RpcFunction(Name As String, DataTypes As Integer[], Ret As Integer)

• Name - Name of the function
• DataTypes - array of data types of arguments of the function
• Ret - Data type of the function value

You can use the class RpcFunction like a read-only array:

Dim hRpcFunction As RpcFunction
Dim anInteger As Integer

anInteger = hRpcFunction [ Index As Integer ]

The following table contains the properties of the class RpcFunction:

Table 27.5.0.3.1: Properties of class RpcFunction

You can create an object of the class RpcArray (gb.xml.rpc):

Dim hRpcArray As RpcArray
hRpcArray = New RpcArray()

You can use the class RpcArray like a read-write array:

Reading:

Dim hRpcArray As RpcArray
Dim aVariant As Variant
aVariant = hRpcArray [ Index As Integer ]

Writing:

Dim hRpcArray As RpcArray
Dim aVariant As Variant
hRpcArray [ Index As Integer ] = aVariant

The RpcArray class has only the read-only Count property of the Integer data type, which returns the number of elements in the array.

Here you will find an overview of selected methods of the class RpcArray:

Table 27.5.0.4.1: Selected methods of the class RpcArray

You can create an object of the class RpcStruct (gb. xml. rpc):

Dim hRpcStruct As RpcStruct
hRpcStruct = New RpcStruct()

The class RpcStruct has only the read-only property Count of the data type Integer, which returns the number of fields in the structure.

Here you will find an overview of the seven methods of the class RpcStruct:

Table 27.5.0.5.1: Methods of the class RpcStruct

The class RpcType (gb.xml.rpc) is static and contains 2 (static) conversion methods and nine constants. The classes RpcType and XmlRpc have the same methods and constants and can therefore be used synonymously.

Here you find an overview of the two methods of the class RpcType:

Table 27.5.0.6.1: Methods of the class RpcType

• xInteger → 0
• xBoolean → 1
• xDouble → 2
• xString → 3
• xBase64 →4
• xDate → 5 ( → dateTime. iso8601 - Example: 2017-08-31T16:47+00:00 (in UTC))
• xStruct → 6
• xArray → 7
• xVoid → 8