libcam API

group libcam

The CAM library API implements a number of functions used to communicate with the CAM Service.

Defines

CAM_DEFAULT_PORT

Default CAM service port.

This macro defines the default port CAM Service will be listening on.

CAM_STREAM_NAME_LEN

The length of stream name.

The macro defines the length of stream name including the \0 terminator.

CAM_ERROR

The error return value of CAM API.

The error return value if an error occurs in CAM library API.

CAM_SUCCESS

The success return value of CAM API.

The success return value if no error occurs in CAM library API.

CAM_VERSION_MAJOR

The Major number of CAM version.

CAM_VERSION_MINOR

The Minor number of CAM version.

Typedefs

typedef struct cam_ctx cam_ctx_t

CAM context.

The CAM context is an opaque data type used by the CAM library to identify a CAM connection.

typedef struct cam_stream_ctx cam_stream_ctx_t

Stream context.

The Stream context is an opaque data type used by the CAM library to identify an initialized Stream.

Functions

int cam_version(unsigned int *major, unsigned int *minor)

Retrieve the library version.

This function retrieves the current version of the library.

Parameters:

  • major – [out] Pointer to the major version number.

  • minor – [out] Pointer to the minor version number.

Return values:

  • CAM_SUCCESS – The version is retrieved with success.

  • CAM_ERROR – Failed to retrieve the library version. The returned major and minor are invalid.

int cam_init(cam_ctx_t *ctx, const char *service_address, unsigned int service_port)

Initialize the CAM connection.

This function initializes the connection with CAM service. It can be called multiple times by an application to initialize a cam_ctx_t descriptor used by further API functions that operate on the connection level. It must be called before any other CAM library function that requires the cam_ctx_t.

Parameters:

  • ctx – [out] Output context to be used with other functions in the CAM library.

  • service_address – String containing the CAM Service IP (v4).

  • service_port – String containing the networking port the CAM Service is listening. This maybe CAM_DEFAULT_PORT or any port the CAM Service was configure with.

Return values:

  • CAM_SUCCESS – The connection initialization succeeded.

  • CAM_ERROR – Failed to initialize the CAM connection. The returned content in the ctx is invalid.

int cam_stream_init(cam_stream_ctx_t *stream_ctx, struct cam_stream_config *config, struct cam_stream_cal_config *cal_config)

Initialize the event stream.

This function initializes the event stream and must be called before any other CAM library function that requires a stream context. It is responsible for internal data structure initialization for a stream.

Parameters:

  • stream_ctx – [out] Output stream context to be used with other functions in the CAM library.

  • config – Pointer to a configuration descriptor.

  • cal_config – Pointer to a configuration descriptor for calibration mode. If the value is NULL, the calibration will not be enabled.

Return values:

  • CAM_SUCCESS – The stream initialization succeeded.

  • CAM_ERROR – Failed to initialize the stream. The returned content in the ctx is invalid.

int cam_stream_start(cam_stream_ctx_t *ctx)

Mark the start of an event stream.

This function indicates to the CAM Service an event stream is about to start.

Parameters:

ctx – Pointer to a stream context the ‘stream’ relates to.

Return values:

  • CAM_SUCCESS – The start message was sent with success.

  • CAM_ERROR – Failed to send the start message.

int cam_stream_event(cam_stream_ctx_t *ctx, uint16_t event_id)

Send an event message.

This function sends an event message to the CAM Service.

Parameters:

  • ctx – Pointer to the stream context the ‘stream’ relates to.

  • event_id – The unique event identifier within the stream.

Return values:

  • CAM_SUCCESS – The event message was sent with success.

  • CAM_ERROR – Failed to send the event message.

int cam_stream_stop(cam_stream_ctx_t *ctx)

Indicate to the CAM Service the event stream stopped.

This function sends an stop message to the CAM Service to indicate the event stream stopped.

Parameters:

ctx – Pointer to the stream context the ‘stream’ relates to.

Return values:

  • CAM_SUCCESS – The stop message was sent with success.

  • CAM_ERROR – Failed to stop the stream.

int cam_stream_end(cam_stream_ctx_t *ctx)

Terminate the event stream.

Terminate the event stream. It is responsible for internal data structure destruction for a stream.

Parameters:

ctx – Pointer to the stream context the ‘stream’ relates to.

Return values:

  • CAM_SUCCESS – The stream was terminated with success.

  • CAM_ERROR – Failed to terminate the stream.

int cam_end(cam_ctx_t *ctx)

Terminate the CAM connection.

Terminate the CAM connection. The connection with the CAM service will be closed.

Parameters:

ctx – Pointer to the CAM context this call relates to.

Return values:

  • CAM_SUCCESS – The CAM connection was terminated with success.

  • CAM_ERROR – Failed to terminate the CAM connection.

struct cam_stream_config
#include <cam.h>

CAM stream configuration descriptor for monitor mode.

The CAM stream configuration descriptor is used to initialize the event stream.

Public Members

char name[CAM_STREAM_NAME_LEN]

Stream name.

Stream name (64 characters including the \0 terminator). The name is used to identify the stream in different contexts like in log files and deployment assets. It may be an empty string.

char *uuid_str

Stream UUID string.

Uniquely identify a stream. Must be in the form “1b4e28ba-2fa1-11d2-883f-b9a761bde3fb”.

cam_ctx_t *ctx

Context descriptor.

Context descriptor with the data for opening a connection with a CAM Service.

struct cam_stream_cal_config
#include <cam.h>

CAM stream configuration descriptor for calibration mode.

The CAM stream configuration descriptor is used to initialize the event stream in calibration mode.

Public Members

char *file_name

Stream event log file name.

Stream event log (CSEL) file name. The event log data will be saved to this file. If this variable is NULL, the file name will be {uuid}.csel in default.

unsigned int timeout_i2s

Timeout between init and start.

Timeout between the stream init and its first start. 0 indicates no timeout.

unsigned int timeout_s2e

Timeout between start and first event.

Timeout between the stream start and its first event. It is mandatory and cannot be zero.