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.
Mandatory. |
description |
Description of the service. Optional. |
namespace |
Namespace to be used in generated C++ source code. |
type¶
Defines a custom data type for use in the service API.
Attribute |
Description |
---|---|
name |
Custom type name. Must begin with a capital letter.
Mandatory. |
type/field¶
Defines a single field for a custom data type.
Attribute |
Description |
---|---|
name |
Custom type name.
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.
Mandatory. |
enum/value¶
Defines a single enumeration value for an enum data type.
Attribute |
Description |
---|---|
name |
Name of the enum value.
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.
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.
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.
Mandatory. |
description |
Description of the event. Optional. |
event/argument¶
Defines the argument for the event. Optional.
Attribute |
Description |
---|---|
name |
Name of the argument.
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 |
---|---|
create_notifier |
If set to 1, Kanzi Connect posts an event when this data element changes. You can use this attribute only for nodes that store data (type=int|string|float|bool). Optional. |
create_getter |
If set to 1, Kanzi Connect creates a getter function for this data element. You do not usually need getter functions with Kanzi UI, because either an event or a data source provides the data to the Kanzi application. You can use this attribute only for nodes that store data (type=int|string|float|bool). Optional. |
writable |
If set to 1, Kanzi Connect creates a setter function for this data element. You can use a two-way binding in your Kanzi application to update a data element that has a setter function. 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. |