Writing Kanzi Connect service descriptions

Kanzi Connect services are described with custom xml document where one file describes one service.

There is a dependency between the name of a service and the xml file that defines the service. For example, if a service name is MyService, you must store it in the file named MyService.xml or MyService_interface.xml.

For Kanzi Connect example service descriptions see files in the <KanziConnectInstallation>/SDK/interfaces/definitions directory. To edit the service descriptions, use the Kanzi Connect Simulator. See Kanzi Connect Simulator and Using service scripting in the Kanzi Connect Simulator.

Built-in and custom datatypes used with services

For service descriptions you can use these built-in data types.

Data type	Description
void	You can use void only as method return value to indicate a completion of operation.
int	32-bit signed integer
bool	Boolean value
float	32-bit floating point number
string	UTF-8 encoded string value
binary	Binary blob

In addition to the built-in data types you can define custom data types that you compose from built-in data types and other custom data types. For example, this custom data type definition defines nested custom types of the Input Service <KanziConnectInstallation>/SDK/sources/connect/core_services/input_service/ interface/input_interface.xml.

For methods and events you can pass an array of values as an argument by adding keyword repeated before the data type. For example, repeated string passes an array of strings.

This table describes how data types map to their use.

Data type	Method argument	Method return	Event argument	Runtime data
void	NO	YES	NO	NO
int	YES	YES	YES	YES
string	YES	YES	YES	YES
bool	YES	YES	YES	YES
float	YES	YES	YES	YES
binary	YES	NO	YES	NO
Custom data type	YES	NO	YES	NO

Note

Kanzi Studio does not support void, binary, and custom types and does not allow accessing the arrays. For this reason you cannot access from Kanzi Studio method and events with these types or modifies in their signature. To access these data types, you must create your own Kanzi Engine plugin.

Reference for service definition

This is an example service definition that uses all XML elements.

<service name="MyService" description="My brand new service" namespace="kanzi">
  <type name="CustomData">
    <field name="lines" datatype="repeated string"/>
  </type>
  <enum name="">
        <value name="" intValue="" description=""/>
        <value name="" intValue="" description=""/>
  </enum>
  <routing>
        <route link=”" linkType="">
            <method name=""/>
            <event name=""/>
            <runtimedata/>
        </route>
  </routing>
  <method name="" return="">
    <argument name="" datatype=""/>
  </method>
  <event name="">
    <argument name="" datatype=""/>
  </event>
  <runtime-data>
    <element datatype="int" persistent="1" writable="1"/>
  </runtime-data>
</service>

service

Encapsulates the service interface definition.

Attribute	Description
name	Symbolic name for the service. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
description	Description of the service. Optional.
namespace	Namespace to be used in generated C++ source code. Optional.

type

Defines a custom data type for use in the service API.

Attribute	Description
name	Custom type name. Must begin with a capital letter. (^[A-Z][A-Za-z0-9_]*$) Mandatory.

type/field

Defines a single field for a custom data type.

Attribute	Description
name	Custom type name. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
datatype	Data type of the field. Can be either one of the built-in data types or a previously defined custom data type. Can be a repeated type. Mandatory.

enum

Defines a custom enum type you can use in the service API.

Attribute	Description
name	Enum type name. Must begin with a capital letter. (^[A-Z][A-Za-z0-9_]*$) Mandatory.

enum/value

Defines a single enumeration value for an enum data type.

Attribute	Description
name	Name of the enum value. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
intValue	Integer representation of the enum value in code. Mandatory.
description	Description of the enum value. Optional.

routing

Defines the peer-to-peer routes that a service must create when you run it as a remote service. No attributes.

routing/route

Individual route for the method, event, and runtime data elements. Note that each of the mentioned has its own individual route although the service description groups logically similar routes together.

Attribute	Description
bearer	Type of the connection adapter. Prebuilt adapters include connect.bearer.tcp, connect.bearer.ssl, and connect.bearer.udp. Optional.
link	Identifier (not unique) for the route. Built-in identifiers are “reliable” and “unreliable”. Mandatory.
linkType	Specifies whether data is routed through the server or directly between endpoints. Either “direct” or “server”. Mandatory.
Any additional attribute	Depending on the connection type, some bearers may require additional attributes to configure the route. Optional.

routing/route/method

A route may contain method elements which specify that that method is using the containing route.

Attribute	Description
name	Name of the method. Mandatory.

routing/route/event

A route may contain event elements which specify that that event is using the containing route.

Attribute	Description
name	Name of the event. Mandatory.

routing/route/runtimedata

A runtime data element within a route which specifies that that runtime data uses this route. No attributes.

method

Declares the RPC method that you want to invoke remotely.

Attribute	Description
name	Name of the method. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
description	Description of the method. Optional.
return	Type of the method return value. Optional.

method/argument

Defines the argument for the method. Optional.

Attribute	Description
name	Name of the argument. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
datatype	Data type of the argument. Mandatory.

event

Declares the RPC event that allows a service to notify its clients.

Attribute	Description
name	Name of the event. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
description	Description of the event. Optional.

event/argument

Defines the argument for the event. Optional.

Attribute	Description
name	Name of the argument. (^[A-Za-z_][A-Za-z0-9_]*$) Mandatory.
datatype	Data type of the argument. Mandatory.

runtime-data

Defines the service runtime data structure definition. Optional.

runtime-data/elements

Defines each runtime data element. Optional.

Attribute	Description
writable	If set to 1, Kanzi Connect creates a setter function for this data element. You can use this attribute only for nodes that store data (type=int|string|float|bool). Optional.
persistent	If set to 1, then value of this runtime data element is stored into persistent storage and restored from there at startup. You can use this attribute only for nodes that store data (type=int|string|float|bool). Optional.