C API

Overview

The OpenZen API is implemented using a pure C API to guarantee ABI stability. The header file OpenZenCAPI.h can be included to access the C interface to OpenZen.

The overall concept of OpenZen usage is described in the section getting-started-labe. This section will describe some special considerations when using the C API. A complete example of the C API usage can be found at this example source file.

Initialisation and Cleanup

In your application, you can create any numbers of clients to manage the sensors that you want to communicate with. When a new client is created, the OpenZen backend needs to connect to subsystems, which can result in failure. To initialize a client, call the ZenInit function with a pointer to the ZenClientHandle_t struct. This struct will then hold the handle to communicate with OpenZen on future calls. Before you use this handle, check whether the returned error equals ZenError_None.

ZenError_t zenError = 0;
ZenClientHandle_t clientHandle = { 0 };
zenError = ZenInit(&clientHandle);
if (zenError != ZenError_None) {
    printf("ZenError %d when obtaining client.\n", zenError);
    return -1;
}

To release all resources associated with the OpenZen client, you can call the ZenShutdown function:

ZenShutdown(clientHandle);

Events

Every ZenClientHandle_t instance contains its own event queue which accumulates events from all sensors that were obtained on that client. Events can either be polled using ZenPollNextEvent or waited for using ZenWaitForNextEvent. The only way to terminate a client that is waiting for an event, is by destroying the client or preemptively calling ZenReleaseSensor.

Access to Sensors and Components

To query the available sensors and connect them can be done using the functions ZenListSensorsAsync, ZenObtainSensor, ZenObtainSensorByName. The usage of these functions is described in the section getting-started-labe.

Once a sensor handle has been obtained, it needs to be provided to all ZenSensor* functions as a parameter.

A sensor component can be retrieved with the function call ZenSensorComponents by providing the type of sensor component which should be loaded. Currently, the component types g_zenSensorType_Imu and g_zenSensorType_Gnss are supported.