Detailed Description

gxPLMessage is a message circulating on xPL network.

Collaboration diagram for Messages:

Modules
	Message Listeners

Functions
int	gxPLAppBroadcastMessage (gxPLApplication app, const gxPLMessage message)
	Broadcast a message. More...

int	gxPLAppIsHubEchoMessage (const gxPLApplication app, const gxPLMessage message, const gxPLId *my_id)
	Check if a message is an echo hub. More...

int	gxPLAppSendMessage (gxPLApplication app, const gxPLMessage message, const gxPLIoAddr *target)
	Send a targeted xPL message. More...

gxPLMessage *	gxPLDeviceMessageNew (gxPLDevice *device, gxPLMessageType type)
	Create a message for the device. More...

int	gxPLDeviceMessageSend (gxPLDevice device, gxPLMessage message)
	Send a message out from this device. More...

gxPLSetting *	gxPLDeviceSetting (gxPLDevice *device)
	Returns device setting. More...

int	gxPLMessageBodyClear (gxPLMessage *message)
	Clear, release a body and all it's resources. More...

xVector *	gxPLMessageBodyGet (gxPLMessage *message)
	Returns body of message as a vector of gxPLPair. More...

const xVector *	gxPLMessageBodyGetConst (const gxPLMessage *message)
	Returns body of message as a const vector of gxPLPair. More...

int	gxPLMessageBodySize (const gxPLMessage *message)
	Number of pairs of the body. More...

int	gxPLMessageBroadcastSet (gxPLMessage *message, bool isBroadcast)
	Sets if a message is broadcast. More...

void	gxPLMessageDelete (gxPLMessage *message)
	Release a message and all it's resources. More...

int	gxPLMessageFilterMatch (const gxPLMessage message, const gxPLFilter filter)
	Check if the passed message matches the passed filter. More...

int	gxPLMessageFlagClear (gxPLMessage *message)
	Clear all flags. More...

gxPLMessage *	gxPLMessageFromString (gxPLMessage message, char line)
	Parse a list of lines as text to extract a message. More...

int	gxPLMessageGroupedSet (gxPLMessage *message, bool isGrouped)
	Sets if a message is grouped. More...

int	gxPLMessageHopGet (const gxPLMessage *message)
	Gets hop count. More...

int	gxPLMessageHopInc (gxPLMessage *message)
	Increments hop count. More...

int	gxPLMessageHopSet (gxPLMessage *message, int hop)
	Sets hop count. More...

int	gxPLMessageIsBroadcast (const gxPLMessage *message)
	Check if a message is broadcast. More...

int	gxPLMessageIsError (const gxPLMessage *message)
	Check if a message is in error. More...

int	gxPLMessageIsGrouped (const gxPLMessage *message)
	Check if a message is for a group. More...

int	gxPLMessageIsReceived (const gxPLMessage *message)
	Check if a message is received. More...

int	gxPLMessageIsValid (const gxPLMessage *message)
	Check if a message is valid. More...

gxPLMessage *	gxPLMessageNew (gxPLMessageType type)
	Create a new empty message. More...

int	gxPLMessagePairAdd (gxPLMessage message, const char name, const char *value)
	Adds a pair to the body. More...

int	gxPLMessagePairAddFormat (gxPLMessage message, const char name, const char *format,...)
	Produce value according to a format. More...

int	gxPLMessagePairExist (const gxPLMessage message, const char name)
	Check if a pair exist. More...

const char *	gxPLMessagePairGet (const gxPLMessage message, const char name)
	Gets the value of a name/value pair. More...

int	gxPLMessagePairSet (gxPLMessage message, const char name, const char *value)
	Sets the value of a name/value pair. More...

int	gxPLMessagePairSetFormat (gxPLMessage message, const char name, const char *format,...)
	Sets the value according to a format. More...

int	gxPLMessagePairValuesSet (gxPLMessage *message,...)
	Set a series of NameValue pairs for a message. More...

int	gxPLMessageReceivedSet (gxPLMessage *message, bool isReceived)
	Sets if a message is received. More...

const char *	gxPLMessageSchemaClassGet (const gxPLMessage *message)
	Gets the schema class. More...

int	gxPLMessageSchemaClassSet (gxPLMessage message, const char schema_class)
	Sets the schema class. More...

int	gxPLMessageSchemaCopy (gxPLMessage message, const gxPLSchema schema)
	Sets the schema. More...

const gxPLSchema *	gxPLMessageSchemaGet (const gxPLMessage *message)
	Gets the schema. More...

int	gxPLMessageSchemaSet (gxPLMessage message, const char schema_class, const char *schema_type)
	Sets the schema. More...

const char *	gxPLMessageSchemaTypeGet (const gxPLMessage *message)
	Gets the schema type. More...

int	gxPLMessageSchemaTypeSet (gxPLMessage message, const char schema_type)
	Sets the schema type. More...

const char *	gxPLMessageSourceDeviceIdGet (const gxPLMessage *message)
	Source device identifier. More...

int	gxPLMessageSourceDeviceIdSet (gxPLMessage message, const char device_id)
	Sets source device identifier. More...

const gxPLId *	gxPLMessageSourceIdGet (const gxPLMessage *message)
	Source identifier. More...

int	gxPLMessageSourceIdSet (gxPLMessage message, const gxPLId id)
	Sets source identifier. More...

const char *	gxPLMessageSourceInstanceIdGet (const gxPLMessage *message)
	Source instance identifier. More...

int	gxPLMessageSourceInstanceIdSet (gxPLMessage message, const char instance_id)
	Sets source instance identifier. More...

int	gxPLMessageSourceSet (gxPLMessage message, const char vendor_id, const char device_id, const char instance_id)
	Sets source identifier. More...

const char *	gxPLMessageSourceVendorIdGet (const gxPLMessage *message)
	Source vendor identifier. More...

int	gxPLMessageSourceVendorIdSet (gxPLMessage message, const char vendor_id)
	Sets source vendor identifier. More...

gxPLMessageState	gxPLMessageStateGet (const gxPLMessage *message)
	gets the decoding state More...

const char *	gxPLMessageTargetDeviceIdGet (const gxPLMessage *message)
	Target device identifier. More...

int	gxPLMessageTargetDeviceIdSet (gxPLMessage message, const char device_id)
	Sets target device identifier. More...

const gxPLId *	gxPLMessageTargetIdGet (const gxPLMessage *message)
	Target identifier. More...

int	gxPLMessageTargetIdSet (gxPLMessage message, const gxPLId id)
	Sets target identifier. More...

const char *	gxPLMessageTargetInstanceIdGet (const gxPLMessage *message)
	Target instance identifier. More...

int	gxPLMessageTargetInstanceIdSet (gxPLMessage message, const char instance_id)
	Sets target instance identifier. More...

int	gxPLMessageTargetSet (gxPLMessage message, const char vendor_id, const char device_id, const char instance_id)
	Sets target identifier. More...

const char *	gxPLMessageTargetVendorIdGet (const gxPLMessage *message)
	Target vendor identifier. More...

int	gxPLMessageTargetVendorIdSet (gxPLMessage message, const char vendor_id)
	Sets target vendor identifier. More...

char *	gxPLMessageToString (const gxPLMessage *message)
	Returns xPL message as text. More...

gxPLMessageType	gxPLMessageTypeFromString (const char *str)
	message type from a string More...

gxPLMessageType	gxPLMessageTypeGet (const gxPLMessage *message)
	Gets message type. More...

int	gxPLMessageTypeSet (gxPLMessage *message, gxPLMessageType type)
	Sets message type. More...

const char *	gxPLMessageTypeToString (gxPLMessageType type)
	string from a message type More...

Function Documentation

int gxPLAppBroadcastMessage	(	gxPLApplication *	app,
		const gxPLMessage *	message
	)

Broadcast a message.

Parameters

app	pointer to a gxPLApplication object
message	pointer to the message

Returns: number of bytes send, -1 if error occurs

int gxPLAppIsHubEchoMessage	(	const gxPLApplication *	app,
		const gxPLMessage *	message,
		const gxPLId *	my_id
	)

Check if a message is an echo hub.

Parameters

app	pointer to a gxPLApplication object
message	pointer to the message
my_id	identifier of the request source. Necessary if the underlying network is not udp (hbeat.basic), may be NULL otherwise (hbeat.app).

Returns: true, false, -1 if an error occurs

int gxPLAppSendMessage	(	gxPLApplication *	app,
		const gxPLMessage *	message,
		const gxPLIoAddr *	target
	)

Send a targeted xPL message.

Parameters

app	pointer to a gxPLApplication object
message	pointer to the message
target	io adress of the target

Returns: number of bytes send, -1 if error occurs

gxPLMessage* gxPLDeviceMessageNew	(	gxPLDevice *	device,
		gxPLMessageType	type
	)

Create a message for the device.

The message can be modified using the functions of the message module before being sent with gxPLDeviceMessageSend(). A message to send can not be gxPLMessageAny type. The message should be released with gxPLMessageDelete after use.

Parameters

device	pointer on the device
type	the type of message

Returns: the message, NULL if an error occurs

int gxPLDeviceMessageSend	(	gxPLDevice *	device,
		gxPLMessage *	message
	)

Send a message out from this device.

The source of the message should be the device but no check is performed.

Parameters

device	pointer on the device
message

Returns: number of bytes send, -1 if error occurs

Examples:: sender/gxpl-sender.c.

gxPLSetting* gxPLDeviceSetting ( gxPLDevice * device )

Returns device setting.

Warning: this setting is shared with all devices connected to the parent xPL application.

Parameters

device pointer on the device

Returns: the setting or NULL if error occurs

int gxPLMessageBodyClear ( gxPLMessage * message )

Clear, release a body and all it's resources.

Parameters

message pointer to the message

Returns: 0, -1 if an error occurs

xVector* gxPLMessageBodyGet ( gxPLMessage * message )

Returns body of message as a vector of gxPLPair.

All added pairs will be released during the destruction of the message. If a pair is changed, it will reallocate the memory of the modified parameter if it is longer.

Parameters

message pointer to the message

Returns: pointer body of message as a vector of gxPLPair, must not be released. NULL if an error occurs

const xVector* gxPLMessageBodyGetConst ( const gxPLMessage * message )

Returns body of message as a const vector of gxPLPair.

Parameters

message pointer to the message

Returns: pointer body of message as a const vector of gxPLPair, must not be released. NULL if an error occurs

int gxPLMessageBodySize ( const gxPLMessage * message )

Number of pairs of the body.

Parameters

message pointer to the message

Returns: the value, -1 if an error occurs

int gxPLMessageBroadcastSet	(	gxPLMessage *	message,
		bool	isBroadcast
	)

Sets if a message is broadcast.

Parameters

message	pointer to the message
isBroadcast	the value

Returns: 0, -1 if an error occurs

Examples:: sender/gxpl-sender.c.

void gxPLMessageDelete ( gxPLMessage * message )

Release a message and all it's resources.

Parameters

message pointer to the message

Examples:: sender/gxpl-sender.c.

int gxPLMessageFilterMatch	(	const gxPLMessage *	message,
		const gxPLFilter *	filter
	)

Check if the passed message matches the passed filter.

Parameters

message	pointer to the message
filter	pointer to the filter

Returns: true, false, -1 if an error occurs

int gxPLMessageFlagClear ( gxPLMessage * message )

Clear all flags.

Parameters

message pointer to the message

Returns: 0, -1 if an error occurs

gxPLMessage* gxPLMessageFromString	(	gxPLMessage *	message,
		char *	line
	)

Parse a list of lines as text to extract a message.

Parse the string, line per line. I do this because the bottom layer can make repeated calls with parts of the message. The smallest portion that can be passed is a line. Do not pass incomplete line !
This function must be called again with the returned pointer as the message is not valid and is not in error.

Parameters

message	pointer to the message returned by a previous call or NULL if the first call.
lines	the list of lines as text, this string is modified by the function and is no longer valid after apple.

Returns: the message, NULL if an error occurs

int gxPLMessageGroupedSet	(	gxPLMessage *	message,
		bool	isGrouped
	)

Sets if a message is grouped.

Parameters

message	pointer to the message
isGrouped	the value

Returns: 0, -1 if an error occurs

int gxPLMessageHopGet ( const gxPLMessage * message )

Gets hop count.

Parameters

message pointer to the message

Returns: hop count, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageHopInc ( gxPLMessage * message )

Increments hop count.

Parameters

message pointer to the message

Returns: 0, -1 if an error occurs

int gxPLMessageHopSet	(	gxPLMessage *	message,
		int	hop
	)

Sets hop count.

Parameters

message pointer to the message

Returns: hop hop count; 0, -1 if an error occurs

int gxPLMessageIsBroadcast ( const gxPLMessage * message )

Check if a message is broadcast.

Parameters

message pointer to the message

Returns: true if broadcast, false if not, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageIsError ( const gxPLMessage * message )

Check if a message is in error.

Parameters

message pointer to the message

Returns: true if error, false if not, -1 if an error occurs

int gxPLMessageIsGrouped ( const gxPLMessage * message )

Check if a message is for a group.

Parameters

message pointer to the message

Returns: true, false, -1 if an error occurs

int gxPLMessageIsReceived ( const gxPLMessage * message )

Check if a message is received.

Parameters

message pointer to the message

Returns: true if received, false if not, -1 if an error occurs

int gxPLMessageIsValid ( const gxPLMessage * message )

Check if a message is valid.

Parameters

message pointer to the message

Returns: true if valid, false if not, -1 if an error occurs

gxPLMessage* gxPLMessageNew ( gxPLMessageType type )

Create a new empty message.

All fields are set to zero except the hop count is set to 1 and the type that is set with the value passed as parameter. The message should be released with gxPLMessageDelete after use.

Parameters

type	the type of message

Returns: the message, NULL if an error occurs

Examples:: sender/gxpl-sender.c.

int gxPLMessagePairAdd	(	gxPLMessage *	message,
		const char *	name,
		const char *	value
	)

Adds a pair to the body.

Parameters

message	pointer to the message
name	the name
value	the value, If NULL is supplied, a zero-length string is assigned ("")

Returns: 0, -1 if an error occurs

Examples:: sender/gxpl-sender.c.

int gxPLMessagePairAddFormat	(	gxPLMessage *	message,
		const char *	name,
		const char *	format,
			...
	)

Produce value according to a format.

Parameters

message	pointer to the message
name	the name
format	format as described in the sprintf() function man page

Returns: 0, -1 if an error occurs

int gxPLMessagePairExist	(	const gxPLMessage *	message,
		const char *	name
	)

Check if a pair exist.

Parameters

message	pointer to the message
name	the name

Returns: true if exists, false in the other cases, -1 if an error occurs

const char* gxPLMessagePairGet	(	const gxPLMessage *	message,
		const char *	name
	)

Gets the value of a name/value pair.

Parameters

message	pointer to the message
name	the name

Returns: pointer to the schema type, must not be released. NULL if an error occurs

int gxPLMessagePairSet	(	gxPLMessage *	message,
		const char *	name,
		const char *	value
	)

Sets the value of a name/value pair.

Parameters

message	pointer to the message
name	the name
value	the value, If NULL is supplied, a zero-length string is assigned ("")

Returns: 0, -1 if an error occurs

int gxPLMessagePairSetFormat	(	gxPLMessage *	message,
		const char *	name,
		const char *	format,
			...
	)

Sets the value according to a format.

Parameters

message	pointer to the message
name	the name
format	format as described in the sprintf() function man page

Returns: 0, -1 if an error occurs

int gxPLMessagePairValuesSet	(	gxPLMessage *	message,
			...
	)

Set a series of NameValue pairs for a message.

Parameters

message pointer to the message

Returns: 0, -1 if an error occurs

int gxPLMessageReceivedSet	(	gxPLMessage *	message,
		bool	isReceived
	)

Sets if a message is received.

Parameters

message	pointer to the message
isReceived	the value

Returns: 0, -1 if an error occurs

const char* gxPLMessageSchemaClassGet ( const gxPLMessage * message )

Gets the schema class.

Parameters

message pointer to the message

Returns: pointer to the schema class, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageSchemaClassSet	(	gxPLMessage *	message,
		const char *	schema_class
	)

Sets the schema class.

Parameters

message	pointer to the message
schema_class	pointer to the schema class

Returns: 0, -1 if an error occurs

int gxPLMessageSchemaCopy	(	gxPLMessage *	message,
		const gxPLSchema *	schema
	)

Sets the schema.

Parameters

message	pointer to the message
schema	pointer to the schema

Returns: 0, -1 if an error occurs

const gxPLSchema* gxPLMessageSchemaGet ( const gxPLMessage * message )

Gets the schema.

Parameters

message pointer to the message

Returns: pointer to the schema, must not be released. NULL if an error occurs

int gxPLMessageSchemaSet	(	gxPLMessage *	message,
		const char *	schema_class,
		const char *	schema_type
	)

Sets the schema.

Parameters

message	pointer to the message
schema_class	pointer to the schema class
schema_type	pointer to the schema type

Returns: 0, -1 if an error occurs

Examples:: sender/gxpl-sender.c.

const char* gxPLMessageSchemaTypeGet ( const gxPLMessage * message )

Gets the schema type.

Parameters

message pointer to the message

Returns: pointer to the schema type, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageSchemaTypeSet	(	gxPLMessage *	message,
		const char *	schema_type
	)

Sets the schema type.

Parameters

message	pointer to the message
schema_type	pointer to the schema type

Returns: 0, -1 if an error occurs

const char* gxPLMessageSourceDeviceIdGet ( const gxPLMessage * message )

Source device identifier.

Parameters

message pointer to the message

Returns: pointer to the device id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c, and sender/gxpl-sender.c.

int gxPLMessageSourceDeviceIdSet	(	gxPLMessage *	message,
		const char *	device_id
	)

Sets source device identifier.

Parameters

message	pointer to the message
device_id	pointer to the device id

Returns: 0, -1 if an error occurs

const gxPLId* gxPLMessageSourceIdGet ( const gxPLMessage * message )

Source identifier.

Parameters

message pointer to the message

Returns: pointer to the id, must not be released. NULL if an error occurs

int gxPLMessageSourceIdSet	(	gxPLMessage *	message,
		const gxPLId *	id
	)

Sets source identifier.

Parameters

message	pointer to the message
id	pointer to the source identifier

Returns: 0, -1 if an error occurs

Examples:: sender/gxpl-sender.c.

const char* gxPLMessageSourceInstanceIdGet ( const gxPLMessage * message )

Source instance identifier.

Parameters

message pointer to the message

Returns: pointer to the instance id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c, and sender/gxpl-sender.c.

int gxPLMessageSourceInstanceIdSet	(	gxPLMessage *	message,
		const char *	instance_id
	)

Sets source instance identifier.

Parameters

message	pointer to the message
instance_id	pointer to the instance id

Returns: 0, -1 if an error occurs

int gxPLMessageSourceSet	(	gxPLMessage *	message,
		const char *	vendor_id,
		const char *	device_id,
		const char *	instance_id
	)

Sets source identifier.

Parameters

message	pointer to the message
vendor_id	pointer to the vendor id
device_id	pointer to the device id
instance_id	pointer to the instance id

Returns: 0, -1 if an error occurs

const char* gxPLMessageSourceVendorIdGet ( const gxPLMessage * message )

Source vendor identifier.

Parameters

message pointer to the message

Returns: pointer to the vendor id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c, and sender/gxpl-sender.c.

int gxPLMessageSourceVendorIdSet	(	gxPLMessage *	message,
		const char *	vendor_id
	)

Sets source vendor identifier.

Parameters

message	pointer to the message
vendor_id	pointer to the vendor id

Returns: 0, -1 if an error occurs

gxPLMessageState gxPLMessageStateGet ( const gxPLMessage * message )

gets the decoding state

Parameters

message pointer to the message

Returns: the state, -1 if an error occurs

const char* gxPLMessageTargetDeviceIdGet ( const gxPLMessage * message )

Target device identifier.

Parameters

message pointer to the message

Returns: pointer to the device id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageTargetDeviceIdSet	(	gxPLMessage *	message,
		const char *	device_id
	)

Sets target device identifier.

Parameters

message	pointer to the message
device_id	pointer to the device id

Returns: 0, -1 if an error occurs

const gxPLId* gxPLMessageTargetIdGet ( const gxPLMessage * message )

Target identifier.

Parameters

message pointer to the message

Returns: pointer to the id, must not be released. NULL if an error occurs

int gxPLMessageTargetIdSet	(	gxPLMessage *	message,
		const gxPLId *	id
	)

Sets target identifier.

Parameters

message	pointer to the message
id	pointer to the target identifier

Returns: 0, -1 if an error occurs

Examples:: sender/gxpl-sender.c.

const char* gxPLMessageTargetInstanceIdGet ( const gxPLMessage * message )

Target instance identifier.

Parameters

message pointer to the message

Returns: pointer to the instance id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageTargetInstanceIdSet	(	gxPLMessage *	message,
		const char *	instance_id
	)

Sets target instance identifier.

Parameters

message	pointer to the message
instance_id	pointer to the instance id

Returns: 0, -1 if an error occurs

int gxPLMessageTargetSet	(	gxPLMessage *	message,
		const char *	vendor_id,
		const char *	device_id,
		const char *	instance_id
	)

Sets target identifier.

Parameters

message	pointer to the message
vendor_id	pointer to the vendor id
device_id	pointer to the device id
instance_id	pointer to the instance id

Returns: 0, -1 if an error occurs

const char* gxPLMessageTargetVendorIdGet ( const gxPLMessage * message )

Target vendor identifier.

Parameters

message pointer to the message

Returns: pointer to the vendor id, must not be released. NULL if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageTargetVendorIdSet	(	gxPLMessage *	message,
		const char *	vendor_id
	)

Sets target vendor identifier.

Parameters

message	pointer to the message
vendor_id	pointer to the vendor id

Returns: 0, -1 if an error occurs

char* gxPLMessageToString ( const gxPLMessage * message )

Returns xPL message as text.

Parameters

message pointer to the message

Returns: xPL message as text, NULL if an error occurs. This character buffer must be released after use.

Examples:: sender/gxpl-sender.c.

gxPLMessageType gxPLMessageTypeFromString ( const char * str )

message type from a string

Parameters

str	string that starts with 8 characters corresponding to xpl-cmnd, xpl gold xpl-stat-trig

Returns: the type, -1 if unknown

gxPLMessageType gxPLMessageTypeGet ( const gxPLMessage * message )

Gets message type.

Parameters

message pointer to the message

Returns: message type, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLMessageTypeSet	(	gxPLMessage *	message,
		gxPLMessageType	type
	)

Sets message type.

Parameters

message	pointer to the message
type	message type

Returns: 0, -1 if an error occurs

const char* gxPLMessageTypeToString ( gxPLMessageType type )

string from a message type

Parameters

type	message type

Returns: the string (xpl-cmnd, ...) or NULL if error occurs

Examples:: logger/gxpl-logger.c.

Detailed Description

Modules

Functions

Function Documentation