Maestro Audio Framework  v 1.0
NXP Semiconductors
osa_message.h File Reference

Contains message queue function prototypes for libosa. More...

Functions

int osa_mq_open (OsaMq *queue, const char *name, uint32_t max_size, bool blocking)
 Open a message queue. More...
 
int osa_mq_send (OsaMq *queue, const char *msg, size_t size)
 Add a message to the queue. More...
 
int osa_mq_receive (OsaMq *queue, char *msg, size_t size, uint32_t msec_timeout, size_t *receive_size)
 Receive a message from a queue. More...
 
int osa_mq_poll (OsaMq *queue, char *msg, size_t size, size_t *receive_size)
 Receive a message from a queue. More...
 
int osa_mq_close (OsaMq *queue)
 Close a message queue. More...
 
int osa_mq_destroy (const char *name)
 Destroy a message queue. More...
 

Function Documentation

◆ osa_mq_open()

int osa_mq_open ( OsaMq queue,
const char *  name,
uint32_t  max_size,
bool  blocking 
)

Open a connection to message queue identified by 'name'

Parameters
queueA queue object will be initialized and returned to the user in this parameter
nameThe name of the message queue. This must start with a forward slash (ex. /my_message_queue)
max_sizeThe maximum size of a message sent and received on the queue
blockingBoolean representing whether or not the queue will block when sending and receiving messages
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_OUT_OF_MEMORYOut of memory
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue may exist already, queue name may be invalid or too long, or max_size exceeds limits.
ERRCODE_PERMISSION_DENIEDPermission denied to open queue (Linux only)
ERRCODE_SYSTEM_LIMITExceeded system limits on number of open queues
ERRCODE_GENERAL_ERRORUnexpected system error

◆ osa_mq_send()

int osa_mq_send ( OsaMq queue,
const char *  msg,
size_t  size 
)

Add a message of a given size onto the given queue

Parameters
queueA valid queue object
msgA pointer to the message buffer
sizeThe size of the message
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_OUT_OF_MEMORYOut of memory
ERRCODE_TRY_AGAINThe queue is full and non-blocking was specified
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue object may be invalid or message size exceeds limits.
ERRCODE_GENERAL_ERRORUnexpected system error

◆ osa_mq_receive()

int osa_mq_receive ( OsaMq queue,
char *  msg,
size_t  size,
uint32_t  msec_timeout,
size_t *  receive_size 
)

Receive a message up to the given size from a queue

Parameters
queueA valid queue object
msgA pointer to a buffer to store the received message. The buffer must be at least 'size' bytes large.
sizeThe maximum size of message to be received
msec_timeoutThe maximum number of milliseconds to block for a message, if blocking is enabled. Passing 0 will block forever.
receive_sizeAn output parameter where the size of the received message will be stored. Will be 0 on failure. Will not exceed 'size'.
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_TRY_AGAINThe queue is empty and non-blocking was specified
ERRCODE_TIMED_OUTNo message received in the timeout period
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue object may be invalid or message size exceeds limits.
ERRCODE_PERMISSION_DENIEDXXX: mqx shouldn't return this?
ERRCODE_GENERAL_ERRORUnexpected system error

◆ osa_mq_poll()

int osa_mq_poll ( OsaMq queue,
char *  msg,
size_t  size,
size_t *  receive_size 
)

Receive a message up to the given size from a queue, never blocking for any amount of time if there is no message to be received.

Parameters
queueA valid queue object
msgA pointer to a buffer to store the received message. The buffer must be at least 'size' bytes large.
sizeThe maximum size of message to be received
receive_sizeAn output parameter where the size of the received message will be stored. Will be 0 on failure. Will not exceed 'size'.
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_TRY_AGAINThe queue is empty and non-blocking was specified
ERRCODE_TIMED_OUTNo message received in the timeout period
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue object may be invalid or message size exceeds limits.
ERRCODE_PERMISSION_DENIEDXXX: mqx shouldn't return this?
ERRCODE_GENERAL_ERRORUnexpected system error

◆ osa_mq_close()

int osa_mq_close ( OsaMq queue)

Closes an open connection to a message queue but does not destroy the queue.

Parameters
queueA valid queue object
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue object may be invalid.
ERRCODE_PERMISSION_DENIEDXXX: mqx shouldn't return this?
ERRCODE_GENERAL_ERRORUnexpected system error

◆ osa_mq_destroy()

int osa_mq_destroy ( const char *  name)

Destroys a message queue and releases all memory allocated by it.

Parameters
nameName of a valid queue object
Return values
ERRCODE_NO_ERRORFunction succeeded
ERRCODE_INVALID_ARGUMENTInvalid parameter. Queue object may be invalid.
ERRCODE_GENERAL_ERRORUnexpected system error