User Tools

Site Tools


k27:k27.5:start

27.5.0 XML-RPC

27.5.0.1 What is XML-RPC?

  • 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.

27.5.0.2 Client request and Server response

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>

27.5.0.3 RPC Function

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 ]

27.5.0.3.1 Properties

The following table contains the properties of the class RpcFunction:

PropertyData typeDescription
CountIntegerSpecifies the number of arguments of the RPC function.
HelpStringSets the help text for the RPC function or returns the help text.
MethodNameStringReturns the name of the method.
ReturnTypeIntegerReturns the data type of the function value → chapter 27.5.0.6.2

Table 27.5.0.3.1: Properties of class RpcFunction

27.5.0.4 RPC Array

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.

27.5.0.4.1 Methods

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

MethodReturn typeDescription
Add (Value As Variant, DataType As Integer) ~Inserts an element into the RPC array.
Clear ()~All elements in the RPC array are deleted.
Pop ()VariantRemoves the last element of an RPC array and returns this element as a Variant function value. If the original RPC array is empty, an error is triggered.
Push (Value As Variant, DataType As Integer) ~Inserts an element at the end of an RPC array.
Remove (Index As Integer)~Deletes the element with the specified index in the RPC array.
Reverse ()RpcArrayThe order of the array elements is inverted - the array elements E0… En are rearranged to En…E0 . The inverted RPC array is returned as a function value.

Table 27.5.0.4.1: Selected methods of the class RpcArray

27.5.0.5 RPC-Structure

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.

27.5.0.5.1 Methods

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

MethodReturn typeDescription
Add (Name As String, Value As Variant, DataType As Integer)~A field with the specified field name, field value, and specification of the appropriate data type is added to a structure.
Clear ()~All fields in the structure are deleted.
Copy ()RpcStructA structure is copied 1:1 and returned as a function value.
Key (Index As Integer)StringThe key for the given field index is returned as a function value.
Value (Index As Integer)VariantThe field value for the given field index is returned as a function value.
Remove (Index As Integer)~Deletes the element with the specified index in the structure.
Reverse ()RpcStructThe order of the elements is inverted - the structure elements E0… En are reordered to En…E0: The inverted structure is returned as a function value.
DataType (Index As Integer)IntegerDefines the data type of a field in the structure or returns its data type.

Table 27.5.0.5.1: Methods of the class RpcStruct

27.5.0.6 RPC Type

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.

27.5.0.6.1 Methods

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

MethodReturn typeDescription
Function ToString (type As Integer) StringConverts a constant integer value into its (string) description.
Function ToType (type As String)IntegerConverts a (string) description into its constant value.

Table 27.5.0.6.1: Methods of the class RpcType

27.5.0.6.2 Overview of Constants 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
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/start.txt · Last modified: 12.05.2022 (external edit)

Page Tools