Kanzi Connect adaptation

Kanzi Connect provides an adaptation library that enables you to integrate Kanzi Connect to Kanzi applications.

Integration through the kanzi::connect::Context

The Context object represents a gateway to a Kanzi Connect Server. There is always one context instance for a connected Kanzi Connect Server. Each connection to a Kanzi Connect Server shares one Context object that is accessible to both Application and Kanzi Engine plugins source code. To obtain that Context object you must have a pointer to the Kanzi domain and know either the service or server name. Shared pointers to services control the lifetime of a connection. This means that the object using the Context object must always store the returned pointers and keep them alive for as long as it needs to interact with those services. When an application releases all references to services, the Context object takes down the connection.

A Context object:

• Initializes the Kanzi Connect Client and integrates it to the task scheduler in the Kanzi UI.

• Connects to the Kanzi Connect Server according to a given configuration. In an environment with more than one Kanzi Connect Server, there is one Context object for each Kanzi Connect Server.

• Exposes interfaces of connected services in the Kanzi Connect network to objects in the Kanzi UI.

Kanzi Connect supports only one context for one Kanzi application, because the context object is a singleton.

Configuring a Context object

You can configure the Context object in a connection.xml configuration file. Place the file in the resource directory of a Kanzi Connect Client. If you do not set the resource directory, the Context object tries to locate the file from the working directory of the application.

You can configure a Context object:

• In Kanzi Studio using the Library > Kanzi Connect tools.

• By manually editing the Application/bin/connection.xml configuration file.

This is an example Context object configuration file that the IVI example in Kanzi Connect SDK uses

<root>
  <connection_adapter>
    <name>IVI</name>
    <bearer>connect.bearer.ssl</bearer>
    <server_name>Server</server_name>
    <attribute name="host_ip" value="127.0.0.1" />
    <attribute name="host_port" value="2006" />
    <attribute name="alt-addresses" value="" />
    <attribute name="basepath" value="../../../../../certs/" />
    <attribute name="certificate" value="client.crt.pem" />
    <attribute name="privatekey" value="client.key.pem" />
    <attribute name="ca-certificate" value="server_ca.crt.pem" />
  </connection_adapter>
</root>

A context is a gateway to a Kanzi Connect Server. To configure multiple servers, use the server name to set which server you want to communicate with. This is an example configuration for creating two connections to the same server: a TCP and an SSL connection.

<root>
  <connection_adapter>
    <name>HUD</name>
    <bearer>connect.bearer.tcp</bearer>
    <server_name>Server</server_name>
    <attribute name="host_ip" value="127.0.0.1" />
    <attribute name="host_port" value="2002" />
    <attribute name="alt-addresses" value="" />
  </connection_adapter>
  <connection_adapter>
    <name>Client</name>
    <bearer>connect.bearer.ssl</bearer>
    <server_name>Server</server_name>
    <attribute name="host_ip" value="127.0.0.1" />
    <attribute name="host_port" value="2006" />
    <attribute name="alt-addresses" value="" />
    <attribute name="basepath" value="../../../../../certs/" />
    <attribute name="certificate" value="client.crt.pem" />
    <attribute name="privatekey" value="client.key.pem" />
    <attribute name="ca-certificate" value="server_ca.crt.pem" />
  </connection_adapter>
</root>

Using SSL connections

To enable encrypted connections configuration.xml contains the ssl element whose active attribute you must set to true. The ssl XML element has child XML elements that define the names of SSL certificate files that must be available.

You can find sample certificates for a secure SSL connection to the Kanzi Connect Server in the <KanziConnectInstallation>/certs directory.

Use the certificates in the Kanzi Connect Client and Kanzi Connect Server as specified in this table.

Used by	Certificate
Kanzi Connect Server	server.crt.pem: Kanzi Connect Server certificate file server.key.pem: Kanzi Connect Server private key file client_ca.crt.pem: Self-signed CA certificate used to sign the Kanzi Connect Client certificate (client.crt.pem)
Kanzi Connect Client	client.crt.pem: Kanzi Connect Client certificate file client.key.pem: Kanzi Connect Client private key file server_ca.crt.pem: Self-signed CA certificate used to sign the Kanzi Connect Server certificate (server.crt.pem)

You can define certificates at compile-time and embed them into the binary or read them programmatically from a secure location. The Kanzi Connect Client Application Kanzi Studio template includes support for this approach. When you create a project using this template, the C++ code in the project shows how you can use the MemorySecurityMaterialStore C++ class to set up the certificates programmatically.

These examples in the Kanzi Connect SDK use SSL:

• The <KanziConnectInstallation>/SDK/examples/IVI and HUD examples use SSL certificates from the <KanziConnectInstallation>/certs directory.

• The <KanziConnectInstallation>/SDK/examples/Cluster example compiles certificates into the binary.

Integrating services and content

You integrate Kanzi Connect services and content to your Kanzi applications using plugins. The plugin objects use the Context object to access the services in the Kanzi Connect Server.

To integrate Kanzi Connect services and content to your Kanzi application you can:

• Import a plugin to the Kanzi Studio project of your Kanzi application and bind runtime data values and content from a Kanzi Connect Server to the nodes in your application, such as a Text Block node, to show those values.

• Add and use the Kanzi Connect services in Kanzi Studio project. For example, you can bind a Media:play action to a button in the UI of your application. See Kanzi Connect service plugins and Kanzi Connect data source.

  Kanzi Connect provides seamless adaptation to Kanzi applications

  

See also

Kanzi Connect service plugins