Message Box Functions
[User API: Pico Layer]

Functions
POSEXTERN void *	posMessageAlloc (void)
POSEXTERN void	posMessageFree (void *buf)
POSEXTERN VAR_t	posMessageSend (void *buf, POSTASK_t taskhandle)
POSEXTERN void *	posMessageGet (void)
POSEXTERN VAR_t	posMessageAvailable (void)
POSEXTERN void *	posMessageWait (UINT_t timeoutticks)

---

Detailed Description

Message boxes are a mechanism that is used for inter-process or, in the case of pico]OS, inter-task communication. All tasks can post messages to each other, and the receiving task will look into its message box and continues when it got a new message. Note that a message box in the pico]OS can hold chunk of messages, so that no message will be lost while the receiving task is still busy processing the last message.
There are two possible types of message boxes: The simple type can only hold a pointer to a user supplied buffer. The other message box type can hold whole messages with different sizes. A message buffer must be allocated with posMessageAlloc by the sending task, and the receiving task must free this buffer again with posMessageFree.
To select the simple message box type, you have to set the define POSCFG_MSG_MEMORY to 0. When you want to have the full message buffer support, you must set POSCFG_MSG_MEMORY to 1.

---

Function Documentation

POSEXTERN void* posMessageAlloc (  void   )

Message box function. Allocates a new message buffer. The maximum buffer size is set at compilation time by the define POSCFG_MSG_BUFSIZE. Usually the sending task would allocate a new message buffer, fill in its data and send it via posMessageSend to the receiving task. Returns: the pointer to the new buffer. NULL is returned on error. Note: POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. POSCFG_MSG_MEMORY must be defined to 1 to have this function compiled in. See also: posMessageSend, posMessageGet, posMessageFree

POSEXTERN VAR_t posMessageAvailable (  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: POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. See also: posMessageGet, posMessageWait

POSEXTERN void posMessageFree (  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: POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. POSCFG_MSG_MEMORY must be defined to 1 to have this function compiled in. See also: posMessageGet, posMessageSend, posMessageAlloc

POSEXTERN void* posMessageGet (  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 posMessageFree when POSCFG_MSG_MEMORY is defined to 1. NULL may be returned when the system has not enough events. In this case, please increase the value for POSCFG_MAX_EVENTS in your poscfg.h . Note: POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. See also: posMessageFree, posMessageAvailable, posMessageWait, posMessageSend

POSEXTERN VAR_t posMessageSend (  void *  buf, POSTASK_t  taskhandle )

Message box function. Sends a message to a task. Parameters: buf  pointer to the message to send. If POSCFG_MSG_MEMORY is defined to 1, this pointer must point to the buffer that was allocated with posMessageAlloc. Note that this parameter must not be NULL. Exception: POSCFG_MSG_MEMORY = 0 and POSCFG_FEATURE_MSGWAIT = 0. 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: POSCFG_FEATURE_MSGBOXES must be defined to 1 to have message box support compiled in. See also: posMessageAlloc, posMessageGet

POSEXTERN void* posMessageWait (  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 posMessageFree when POSCFG_MSG_MEMORY is defined to 1. NULL is returned when no message was received within the specified time (=timeout). Hint: NULL may also be returned when the system has not enough events. In this case, please increase the value for POSCFG_MAX_EVENTS in your poscfg.h . Note: POSCFG_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. See also: posMessageFree, posMessageGet, posMessageAvailable, posMessageSend, HZ, MS

---