ct_dequeue_msg
The ct_dequeue_msg function copies the contents of the message at the
head of the current thread's input queue, and then removes the message.
Prototype:
int ct_dequeue_msg( unsigned char * buff );
Parameters:
- buff
-
A non-NULL pointer to a buffer to which the message contents will be
copied. The application is responsible for ensuring that the
buffer is large enough to contain the data without overflow.
Return Value:
CT_OKAY if successful, or CT_ERROR if not.
Discussion:
The ct_dequeue_msg function copies the message's data, byte for
byte, into the specified buffer. It makes no assumptions about the
nature of these data, which may contain any arbitrary byte values.
In particular, the function does not assume that the data form a
character string, nor does it append a terminal nul.
After copying the data, ct_dequeue_msg() removes the message from the
head of the thread's input queue and destroys it.
The application code is responsible for ensuring that the buffer is
large enough to contain the data without overflow. Ordinarily the
length of the data will be available from a prior call to
ct_query_msg().
The ct_dequeue_msg function reports a fatal error if any of the
following occurs:
- The pointer parameter is NULL;
- There is no input message pending;
- The scheduler is not running.
See also: ct_discard_msg().
Restrictions:
The ct_dequeue_msg function may be called only from a thread or
user exit.
Home