Message Box Functions
[Abstracted Functions]

Functions
NANOEXT void *	nosMessageAlloc (UINT_t msgSize)
NANOEXT void	nosMessageFree (void *buf)
NANOEXT VAR_t	nosMessageSend (void *buf, NOSTASK_t taskhandle)
NANOEXT void *	nosMessageGet (void)
NANOEXT void *	nosMessageWait (UINT_t timeoutticks)
NANOEXT VAR_t	nosMessageAvailable (void)

---

Detailed Description

For detailed information about using message boxes please see detailed description of message boxes

---

Function Documentation

NANOEXT void* nosMessageAlloc (  UINT_t  msgSize  )

Message box function. Allocates a new message buffer. To increase the execution speed, it is recommended to set POSCFG_MSG_MEMORY to 1. Otherwise, nosMessageAlloc will need to call nosMemAlloc to allocate memory (and this is possibly slower than the pico]OS internal message allocator). Usually the sending task would allocate a new message buffer, fill in its data and send it via nosMessageSend to the receiving task. The receiving task is responsible for freeing the message buffer again. Parameters: msgSize  size of the requested message buffer in bytes. Returns: the pointer to the new buffer. NULL is returned if the system is low on memory or the requested msgSize is larger than POSCFG_MSG_BUFSIZE (only if POSCFG_MSG_MEMORY is set to 1). Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. If POSCFG_MSG_MEMORY is set to 0, you also need to enable the nano layer memory manager by setting NOSCFG_FEATURE_MEMALLOC to 1. See also: nosMessageSend, nosMessageGet, nosMessageFree

NANOEXT VAR_t nosMessageAvailable (  void   )

Message box function. Tests if a new message is available in the message box. This function can be used to prevent the task from blocking. Returns: 1 (=true) when a new message is available. Otherwise zero is returned. A negative value is returned on error. Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. Dependent of your configuration, this function can be defined as macro to decrease code size. See also: nosMessageGet, nosMessageWait

NANOEXT void nosMessageFree (  void *  buf  )

Message box function. Frees a message buffer again. Usually the receiving task would call this function after it has processed a message to free the message buffer again. Parameters: buf  Pointer to the message buffer that is no more used. Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. See also: nosMessageGet, nosMessageSend, nosMessageAlloc

NANOEXT void* nosMessageGet (  void   )

Message box function. Gets a new message from the message box. If no message is available, the task blocks until a new message is received. Returns: Pointer to the received message. Note that the message memory must be freed again with nosMessageFree when the message buffer is no more used. Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. Dependent of your configuration, this function can be defined as macro to decrease code size. See also: nosMessageFree, nosMessageAvailable, nosMessageWait, nosMessageSend

NANOEXT VAR_t nosMessageSend (  void *  buf, NOSTASK_t  taskhandle )

Message box function. Sends a message to a task. Parameters: buf  Pointer to the message to send. The message buffer must have been allocated by calling nosMessageAlloc before. taskhandle  handle to the task to send the message to. Returns: zero on success. When an error condition exist, a negative value is returned and the message buffer is freed. Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. See also: nosMessageAlloc, nosMessageGet

NANOEXT void* nosMessageWait (  UINT_t  timeoutticks  )

Message box function. Gets a new message from the message box. If no message is available, the task blocks until a new message is received or the timeout has been reached. Parameters: timeoutticks  timeout in timer ticks (see HZ define and MS macro). If this parameter is set to zero, the function immediately returns. If this parameter is set to INFINITE, the function will never time out. Returns: Pointer to the received message. Note that the message memory must be freed again with nosMessageFree when the message buffer is no more used. NULL is returned when no message was received within the specified time (=timeout). Note: NOSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. POSCFG_FEATURE_MSGWAIT must be defined to 1 to have this function compiled in. Dependent of your configuration, this function can be defined as macro to decrease code size. See also: nosMessageFree, nosMessageGet, nosMessageAvailable, nosMessageSend, HZ, MS

---