appCORE - coreMsgCreate()

NAME

coreMsgCreate() -- create an appCORE message.

SYNOPSIS

include "appcore.h"

coreMsg_t* coreMsgCreate( int Type, size_t Length, void* Payload )

DESCRIPTION

The coreMsgCreate() function creates a standard appCORE message, a coreMsg_t data type, and returns a pointer to it. Default behavior is too allocate the message using the message pool. Refer to SDK Messages for information on appCORE messages.

To dispatch or forward a message to the main application thread use the function coreAppDispatch() and coreAppForward() respectively. To dispatch or forward a message to a specific thread use the functions coreMsgDispatch() and coreMsgForward() respectively. To dispatch or forward a message to a multicore processing element use the functions coreMultiCoreDispatch() and coreMultiCoreForward() respectively.

The following macros are provided to access message elements:
CORE_MSG_TYPE(p) - message type
CORE_MSG_SIZE(p) - message size (total)
CORE_MSG_SRC_THR(p) - source thread Id
CORE_MSG_PAYLOAD(p) - access payload
CORE_MSG_PAYLOAD_SIZE(p) - payload size

PARAMETERS

Type
	The message type. Valid application types are from 1 to coreMsgTypeMin 
	(0x7ffeffff). appCORE reserves message types from 0x7fffe0000 through 
	0x7fffffff. 

Length
	Length of the message's payload. If the payload is NULL, a message 
	of the requested size is always allocated.

Payload
	Pointer to the message payload. The payload is copied into the message
	if non-null.

RETURN VALUE

If successful, coreMsgCreate() returns a pointer to the message. If an error occurs, NULL is returned and errno is set to one of the following:

errno Value	Condition
EINVAL	Message type out of range (1,0x7fffeffff).
	Length is zero, payload is non-zero.
ENOMEM	Unable to allocate memory for message.

MULTI-THREAD SAFETY LEVEL

MT-safe.