Kanzi Connect services

Kanzi Connect provides a framework for connected services, which are components running on a server. This allows you to implement your own services for any purpose and run them on a Kanzi Connect network.

You can use the connected services to:

  • Provide higher level, easy-to-use integration to operating system and platform features.

  • Provide higher level, easy-to-use interface for external components.

  • Produce and collect data the Kanzi Connect clients can consume.

  • Perform data processing and manipulation for the Kanzi Connect clients.

  • Synchronize the state of Kanzi Connect clients.

The Kanzi Connect SDK comes with several built-in services that you can use to start the development of a connected system. See Built-in services.

Service interface definition

Each service component exposes an interface to the Kanzi Connect network, which a client can access remotely. The network interface is defined in XML and contains:

  • Service methods (action / request / RPC function call)

  • Service events (trigger / notification / RPC callback)

  • Service data (runtime state of the service)

You can use built-in scripts with the interface XML file to output:

  • Server-side stub for the service. This is an abstract class that you can implement on the server side.

  • Client-side service class that you can use to access its server-side counterpart.

  • Plugin objects that you can use directly in Kanzi Studio to enable seamless adaptation in a Kanzi user interface.

This is an example of the interface XML file syntax:

<service fullname="Connect.Service.Service_name" name="Service_name" description="service_description" namespace="service_namespace" package="service_package" type="simulated" version="0.1">
        <routing/>
        <runtime-data>
                <engine>
                        <speed datatype="float" default="0.000000" persistent="0" controller="Input"/>
                        <rpm datatype="int" default="0" persistent="0" controller="Input"/>
                        <power datatype="float" default="0.000000" persistent="0" controller="Input"/>
                        <gear datatype="int" default="0" persistent="0" controller="Input" writable="1"/>
                </engine>
        </runtime-data>
        <event name="event_name" description="event_description">
                <argument name="event_parameter" datatype="int"/>
        </event>
        <method name="method_name" description="method_description">
                <argument name="method_parameter" datatype="int"/>
        </method>
        <method name="method_with_returnvalue" description="method_description" return="int">
                <argument name="method_parameter_1" datatype="int"/>
                <argument name="method_parameter_2" datatype="string"/>
        </method>
        <method autogenerated="true" name="setEngineGear">
                <argument controller="Input" datatype="int" default="0" name="gear" persistent="0"/>
        </method>
</service>

You can find examples of the interface XML files in these directories:

  • <KanziConnectInstallation>/SDK/interfaces/definitions

  • <KanziConnectInstallation>/SDK/examples/services/native/interfaces/definitions

These rules apply for the service interface XML:

  • Method names, event names, their arguments and custom type names and fields must follow the naming rules of C language variables. The validity is checked against this regular expression:

    "^[A-Za-z_][A-Za-z0-9_]*$"
    
  • Methods and events must have unique names.

  • Arguments of methods and events must have unique names.

  • Custom type names must start with a capital letter (A … Z).

  • Custom type fields must have unique names.

  • Supported return value types include void, int, string, float, and bool.

    • Return values are always asynchronous.

    • You cannot use return values in Kanzi Studio Actions.

  • Supported predefined argument types include int, string, float, bool, and binary.

To learn more about writing Kanzi Connect service descriptions, see Writing Kanzi Connect service descriptions.

Error handling

In Kanzi Engine the model is strongly decoupled from the controller and view, which means that the actions and triggers do not provide synchronous return values. However, when you create a new Kanzi Connect service, you can define a return value for a method.

  • To ensure that Kanzi Connect Server or a service receives and handles the method correctly, you can use return values in the C++ code of your application.

  • Keep the method return values simple and provide responses with more data through runtime data and events.

For example, a typical error situation in Kanzi Connect is that a service or resource is not present. Make the UI design modular and designed so that it remains functional even when some of the content is not present. To test what your application looks like when a service is not available, in Kanzi Studio in the Kanzi Connect Editor disable the service from which your application receives content.

../_images/kanzi-connect-with-cluster-and-content-services.png

Built-in services

The Kanzi Connect SDK comes with built-in services that you can use to develop an application.

This table lists the services included in the Kanzi Connect SDK.

Service

Supported on Windows

Supported on Android

Configuration Service

Yes

Yes

Cluster Service

Yes

Yes

Connection Service

Yes

Yes

Content Service

Yes

Yes

Diagnostics service

Yes

Yes

Virtual File Service

Yes

Yes

Input Service

Yes

Yes

Media Service

Using the Windows Media Foundation

Using the Android MediaPlayer

OBD-II Service

No

Supports OBD-II adapters using Bluetooth

Persistence Service

Yes

Yes

Scenario

Yes

Yes

Screencast Service

No

Yes

Sensor Service

No

Using the Android SensorManager

Speech2Text Service

No

Using the Android SpeechRecognizer

System Service

Yes

Yes