C API documentation

Utility functions

Defines

A_SERVICE_ID_DIGITAL_OUTPUTS

Compat define for older SDK.

a_membersof(arr)

Get the number of elements in an array.

Parameters:

  • arr – An array

Returns:

Number of elements in the array

Enums

enum a_ipc_service_ids

IPC IDs of Actia services

Values:

enumerator A_SERVICE_ID_SYSTEM

System Service

enumerator A_SERVICE_ID_SOFTWARE_UPDATE

Software Update Service

enumerator A_SERVICE_ID_LOG

Logging control service

enumerator A_SERVICE_ID_CELLULAR

Cellular service

enumerator A_SERVICE_ID_LOCATION

Location service

enumerator A_SERVICE_ID_CAN

CAN configuration service

enumerator A_SERVICE_ID_IMU

IMU service

enumerator A_SERVICE_ID_ANALOG_INPUTS

ANALOG_INPUTS service

enumerator A_SERVICE_ID_POWER

Power manager

enumerator A_SERVICE_ID_WIFI

WIFI

enumerator A_SERVICE_ID_DIGITAL_INPUT_OUTPUT

DIGITAL_INPUT_OUTPUT service

enumerator A_SERVICE_ID_BUB

BUB service

enumerator A_SERVICE_ID_RTC

RTC manager

enumerator A_SERVICE_ID_ETHERNET

Ethernet manager

enumerator A_SERVICE_ID_MQTT_HANDLER

MQTT manager

enumerator A_SERVICE_ID_BTMGR

BT manager

enumerator A_SERVICE_ID_CONNECTIVITY

Connectivity service

Functions

int a_open_software_update_stream(void)

Open a stream for sending update packages to Software Update.

Call this function when the updater is waiting for files.

If the update includes multiple files, stream them back-to-back.

The stream is non-blocking, but this open call is blocking. The stream file descriptor might be a socket, but it is NOT guaranteed to be a socket.

Note: If the stream unexpectedly closes, write() to the stream can trigger a SIGPIPE signal to the process.

Returns:

The stream file descriptor, or a negative error code on error

Logging functions

Typedefs

typedef void (*a_log_function)(a_log_level level, const char *format, va_list ap)

Logger function prototype.

For use with a_log_set_logger().

Param level:

The log level of the message

Param format:

printf-style format string

Param ap:

printf arguments

Enums

enum a_log_level

Actia library log levels

Values:

enumerator A_LOG_DEBUG

Debug info

enumerator A_LOG_INFO

Ordinary event

enumerator A_LOG_WARNING

Ordinary event, but not quite expected (e.g. bad frame)

enumerator A_LOG_ERROR

Extraordinary event.

enumerator A_LOG_FATAL

Extreme event. Application will abort immediately.

Functions

void a_log_set_logger(a_log_function function)

Set Actia library logging function.

All Actia library log messages will invoke this function to log messages.

Note: This setting only affects logs for the instance of the Actia library in the current application. Device system logs are not affected.

Logs are sent to syslog by default ( a_log_syslog_logger() ).

The built-in logger functions are named a_log_*_logger().

Parameters:

  • function – Function that will be called for each log message

void a_log_syslog_logger(a_log_level level, const char *format, va_list ap)

Syslog logger.

Sends all messages to the syslog, mapping the log level.

See also

a_log_set_logger()

void a_log_stdout_logger(a_log_level level, const char *format, va_list ap)

Standard output logger.

Sends all messages to standard output (stdout), prefixed with the log level.

See also

a_log_set_logger()

void a_log_stderr_logger(a_log_level level, const char *format, va_list ap)

Standard error logger.

Sends all messages to standard error (stderr), prefixed with the log level.

See also

a_log_set_logger()

Actia IPC Common functions

Defines

A_IPC_ALLOC_MSG_BUFFER(name, size, modifiers)

Helper macro to allocate space for a message structure NOTE, never use this directly, use A_IPC_MSG_ON_STACK or A_IPC_STATIC_MSG

A_IPC_MSG_ON_STACK(name, size)

Allocate a message buffer on the stack.

The resulting variable is equivalent to

a_ipc_msg *name;

Note: The macro expands to multiple lines.

Note: This can be used both on function scope and file scope.

Parameters:

  • name – Name of the variable

  • size – Size of the buffer, in bytes.

A_IPC_STATIC_MSG(name, size)

Allocate a message buffer statically

The resulting variable is equivalent to

static a_ipc_msg *name;

Note: The macro expands to multiple lines.

Note: This can be used both on function scope and file scope.

Parameters:

  • name – Name of the variable

  • size – Size of the buffer, in bytes.

A_IPC_STATIC_BUFFERS(name, inbox_size, outbox_size)

Allocate ipc inbox/outbox buffers statically.

DEPRECATED This is a legacy helper and has been replaced by A_IPC_STATIC_BUFFERS_BYTES. Each buffer will be sized as 512 * number of messages

Typically placed at the top of a code file.

The resulting variable is equivalent to

static a_ipc_buffers name;

Note: The macro expands to multiple lines.

Parameters:

  • name – Name of the variable

  • inbox_size – Size of the inbox buffer, in number of messages.

  • outbox_size – Size of the outbox buffer, in number of messages.

A_IPC_STATIC_BUFFERS_BYTES(name, inbox_size, outbox_size)

Allocate ipc inbox/outbox buffers statically.

Typically placed at the top of a code file.

The resulting variable is equivalent to

static a_ipc_buffers name;

Note: The macro expands to multiple lines.

Parameters:

  • name – Name of the variable

  • inbox_size – Size of the inbox buffer, in bytes

  • outbox_size – Size of the outbox buffer, in bytes.

A_IPC_ALLOCATE_BUFFERS(name, inbox_size, outbox_size)

Allocate ipc inbox/outbox buffers dynamically.

DEPRECATED This is a legacy helper and has been replaced by A_IPC_ALLOCATE_BUFFERS_BYTES

Prefer the static macro for better memory utilization.

The resulting variable is equivalent to

a_ipc_buffers *name;

Note: The macro expands to multiple lines.

Parameters:

  • name – Name of the variable

  • inbox_size – Size of the inbox buffer, in number of messages.

  • outbox_size – Size of the outbox buffer, in number of messages.

A_IPC_ALLOCATE_BUFFERS_BYTES(name, inbox_size, outbox_size)

Allocate ipc inbox/outbox buffers dynamically.

Prefer the static macro for better memory utilization.

The resulting variable is equivalent to

a_ipc_buffers *name;

Note: The macro expands to multiple lines.

Parameters:

  • name – Name of the variable

  • inbox_size – Size of the inbox buffer, in bytes.

  • outbox_size – Size of the outbox buffer, in bytes.

A_IPC_GUEST_MIN_ID

Minimum allowed IPC ID for User VM applications

A_IPC_GUEST_MAX_ID

Maximum allowed IPC ID for User VM applications

Typedefs

typedef struct a_ipc_buffers a_ipc_buffers

Handle to a struct containing IPC inbox/outbox buffers.

typedef struct a_ipc_handle a_ipc_handle

Handle to an IPC instance. Created with a_ipc_init().

typedef struct a_ipc_msg a_ipc_msg

AIPC Message. Defined in generated headers for each application

Enums

enum A_IPC_RESULT

IPC function result codes

Values:

enumerator A_IPC_RET_OK

Operation succeeded

enumerator A_IPC_RET_ERROR

Unspecified error

enumerator A_IPC_RET_BUFFER_TOO_SMALL

The provided buffer is too small

enumerator A_IPC_RET_BAD_TYPE

The message type is not known

enumerator A_IPC_RET_NO_MSG

No message found/received

enumerator A_IPC_RET_SEND_ERROR

Error when signaling message to be sent

enumerator A_IPC_RET_TIMEOUT

Timeout while waiting

enumerator A_IPC_RET_MALFORMED_PACKET

Malformed packet in transport layer

enumerator A_IPC_RET_NOT_IMPLEMENTED

Functionality not implemented

enumerator A_IPC_RET_OUT_OF_MEMORY

Not enough memory (allocated) to perform the request action

enumerator A_IPC_RET_INVALID_ARGUMENT

Invalid arguments given

enumerator A_IPC_RET_OUTBOX_FULL

Outbox full

Functions

a_ipc_handle *a_ipc_init(int id, a_ipc_buffers *buffers)

Initialize AIPC and make application available to other IPC applications.

Messages can arrive after initializing.

This version will use defaults or heuristics to determine additional settings.

Note: This function potentially starts threads, if you need to block signals for e.g. signalfd(2), make sure to do so before calling this function.

Parameters:

  • id – Unique ID of the endpoint.

  • buffers – Struct containing inbox and outbox buffers. Use A_IPC_ALLOCATE_BUFFERS_BYTES to allocate dynamically, or use A_IPC_STATIC_BUFFERS_BYTES to allocate statically.

Returns:

Handle to AIPC, or NULL on error.

a_ipc_handle *a_ipc_init_ex(int id, a_ipc_buffers *buffers, unsigned int outstanding_window)

Initialize AIPC and make application available to other IPC applications.

Messages can arrive after initializing.

This version allows to specify additional settings compared to a_ipc_init.

Note: This function potentially starts threads, if you need to block signals for e.g. signalfd(2), make sure to do so before calling this function.

Parameters:

  • id – Unique ID of the endpoint.

  • buffers – Struct containing inbox and outbox buffers. Use A_IPC_ALLOCATE_BUFFERS_BYTES to allocate dynamically, or use A_IPC_STATIC_BUFFERS_BYTES to allocate statically.

  • outstanding_window – The number of messages that can be in-flight at any time that has not been ACKed by the receiver.

Returns:

Handle to AIPC, or NULL on error.

void a_ipc_destroy(a_ipc_handle *handle)

Destroy AIPC. Clears up used resources and makes the application unavailable to other IPC applications.

Parameters:

  • handle – AIPC handle.

void a_ipc_free_buffers(a_ipc_buffers *buffers)

Free the memory of a dynamically alloctated ipc inbox/outbox buffers struct.

Parameters:

  • buffers – inbox/outbox buffers.

int a_ipc_get_fd(a_ipc_handle *handle)

Get file descriptor for selecting/polling for new messages. Use a_ipc_recv() to receive the messages.

Parameters:

  • handle – AIPC handle.

Returns:

A file descriptor, or -1 on error.

A_IPC_RESULT a_ipc_send(a_ipc_handle *handle, int to, a_ipc_msg *msg)

Send an IPC message.

Parameters:

  • handle – AIPC handle.

  • to – ID of the receiver.

  • msg – Initialized and filled-in message to send.

Returns:

A_IPC_RESULT a_ipc_recv(a_ipc_handle *handle, int *from, a_ipc_msg *msg)

Receive an IPC message.

The contents of msg are undefined if the return value is not A_IPC_RET_OK or A_IPC_RET_SEND_ERROR.

Parameters:

  • handle – AIPC handle.

  • from – Populated with ID of the sender. This argument can be NULL, if the value is not of interest.

  • msg – Message buffer for the received message.

Returns:

A_IPC_RESULT a_ipc_copy_message(a_ipc_msg *dst, const a_ipc_msg *src)

Copy an IPC message. Both buffers must have been initialized.

Parameters:

  • dst – Message buffer to copy to.

  • src – Message buffer to copy from.

Returns:

A_IPC_RET_OK on success. Otherwise an A_IPC_RESULT.

const char *a_ipc_msg_type_str(int msg_type)

Get the string representation (enum constant) for the given msg_type.

Parameters:

  • msg_type – Message type (A_IPC_MSG_*)

Returns:

String representation of the message type or “Unknown (<ID>)”.

const char *a_ipc_result_str(A_IPC_RESULT result)

Get the string representation for the given result value.

Parameters:

  • result – Result

Returns:

String representation of the result or “Unknown (<ID>)”.

int a_ipc_dump_stats(a_ipc_handle *handle)

Outputs information to the log about the current IPC instance.

Includes: Max slot usage of inbox and outbox

Parameters:

  • handle – AIPC handle

Returns:

A_IPC_RET_OK on success. Otherwise an A_IPC_RESULT.

struct a_ipc_msg_info

IPC message basic info. These members should not be updated by the user.

Public Members

int type

The message type, as given by the user-provided IPC IDs file

size_t msg_alloc_size

Total message size - including struct members

size_t msg_used_size

How much of the message that is used - including struct members