#include <strings.h>
#include <dlfcn.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <time.h>
#include <pthread.h>
#include "cMsgPrivate.h"
#include "cMsgNetwork.h"

Macros
#define	CMSG_PAYLOAD_NAME_LEN 128

#define	CMSG_SYSTEM_FIELDS 0

#define	CMSG_PAYLOAD_FIELDS 1

#define	CMSG_BOTH_FIELDS 2

Typedefs
typedef union u1	intFloatUnion

typedef union u2	intDoubleUnion

Functions
char *	cMsgIntChars (uint32_t i)

char *	cMsgFloatChars (float f)

char *	cMsgDoubleChars (double d)

void	cMsgPayloadReset_r (void *vmsg)

void	cMsgPayloadReset (void *vmsg)

void	cMsgPayloadClear (void *vmsg)

int	cMsgHasPayload (const void vmsg, int hasPayload)

int	cMsgPayloadGetCount (const void vmsg, int count)

int	cMsgPayloadContainsName (const void vmsg, const char name)

int	cMsgPayloadGetType (const void vmsg, const char name, int *type)

int	cMsgPayloadGet (const void vmsg, char names, int types, int len)

int	cMsgPayloadGetInfo (const void vmsg, char names, int types, int *len)

int	cMsgPayloadRemove (void vmsg, const char name)

int	cMsgPayloadUpdateText (const void *vmsg)

int	cMsgAddHistoryToPayloadText (void vmsg, char name, char host, int64_t time, char *pTxt)

int	cMsgPayloadCopy (const void vmsgFrom, void vmsgTo)

const char *	cMsgPayloadFieldDescription (const void vmsg, const char name)

void	cMsgPayloadPrint (const void *vmsg)

int	cMsgPayloadGetFieldText (const void vmsg, const char name, const char **val)

int	cMsgPayloadSetFromText (void vmsg, const char text)

int	cMsgPayloadSetSystemFieldsFromText (void vmsg, const char text)

int	cMsgPayloadSetAllFieldsFromText (void vmsg, const char text)

int	cMsgPayloadGetFieldPointer (const void vmsg, const char name, void **p)

int	cMsgPayloadSetFieldPointer (const void vmsg, const char name, void *p)

int	cMsgGetBinary (const void vmsg, const char name, const char *val, int size, int *endian)

int	cMsgGetBinaryArray (const void vmsg, const char name, const char *vals, int sizes, int *endians, int count)

int	cMsgGetMessage (const void vmsg, const char name, const void **val)

int	cMsgGetMessageArray (const void vmsg, const char name, const void **val, int len)

int	cMsgGetFloat (const void vmsg, const char name, float *val)

int	cMsgGetDouble (const void vmsg, const char name, double *val)

int	cMsgGetFloatArray (const void vmsg, const char name, const float *vals, int len)

int	cMsgGetDoubleArray (const void vmsg, const char name, const double *vals, int len)

int	cMsgGetInt8 (const void vmsg, const char name, int8_t *val)

int	cMsgGetInt16 (const void vmsg, const char name, int16_t *val)

int	cMsgGetInt32 (const void vmsg, const char name, int32_t *val)

int	cMsgGetInt64 (const void vmsg, const char name, int64_t *val)

int	cMsgGetUint8 (const void vmsg, const char name, uint8_t *val)

int	cMsgGetUint16 (const void vmsg, const char name, uint16_t *val)

int	cMsgGetUint32 (const void vmsg, const char name, uint32_t *val)

int	cMsgGetUint64 (const void vmsg, const char name, uint64_t *val)

int	cMsgGetInt8Array (const void vmsg, const char name, const int8_t *vals, int len)

int	cMsgGetInt16Array (const void vmsg, const char name, const int16_t *vals, int len)

int	cMsgGetInt32Array (const void vmsg, const char name, const int32_t *vals, int len)

int	cMsgGetInt64Array (const void vmsg, const char name, const int64_t *vals, int len)

int	cMsgGetUint8Array (const void vmsg, const char name, const uint8_t *vals, int len)

int	cMsgGetUint16Array (const void vmsg, const char name, const uint16_t *vals, int len)

int	cMsgGetUint32Array (const void vmsg, const char name, const uint32_t *vals, int len)

int	cMsgGetUint64Array (const void vmsg, const char name, const uint64_t *vals, int len)

int	cMsgGetString (const void vmsg, const char name, const char **val)

int	cMsgGetStringArray (const void vmsg, const char name, const char **array, int len)

int	cMsgAddBinary (void vmsg, const char name, const char *src, int size, int endian)

int	cMsgAddBinaryArray (void vmsg, const char name, const char *src[], int number, const int size[], const int endian[])

int	cMsgAddFloat (void vmsg, const char name, float val)

int	cMsgAddDouble (void vmsg, const char name, double val)

int	cMsgAddFloatArray (void vmsg, const char name, const float vals[], int len)

int	cMsgAddDoubleArray (void vmsg, const char name, const double vals[], int len)

int	cMsgAddInt8 (void vmsg, const char name, int8_t val)

int	cMsgAddInt16 (void vmsg, const char name, int16_t val)

int	cMsgAddInt32 (void vmsg, const char name, int32_t val)

int	cMsgAddInt64 (void vmsg, const char name, int64_t val)

int	cMsgAddUint8 (void vmsg, const char name, uint8_t val)

int	cMsgAddUint16 (void vmsg, const char name, uint16_t val)

int	cMsgAddUint32 (void vmsg, const char name, uint32_t val)

int	cMsgAddUint64 (void vmsg, const char name, uint64_t val)

int	cMsgAddInt8Array (void vmsg, const char name, const int8_t vals[], int len)

int	cMsgAddInt16Array (void vmsg, const char name, const int16_t vals[], int len)

int	cMsgAddInt32Array (void vmsg, const char name, const int32_t vals[], int len)

int	cMsgAddInt64Array (void vmsg, const char name, const int64_t vals[], int len)

int	cMsgAddUint8Array (void vmsg, const char name, const uint8_t vals[], int len)

int	cMsgAddUint16Array (void vmsg, const char name, const uint16_t vals[], int len)

int	cMsgAddUint32Array (void vmsg, const char name, const uint32_t vals[], int len)

int	cMsgAddUint64Array (void vmsg, const char name, const uint64_t vals[], int len)

int	cMsgAddString (void vmsg, const char name, const char *val)

int	cMsgAddStringArray (void vmsg, const char name, const char **vals, int len)

int	cMsgAddMessage (void vmsg, const char name, const void *vmessage)

int	cMsgAddMessageArray (void vmsg, const char name, const void *vmessage[], int len)

Detailed Description

Introduction

This file defines the compound payload interface to cMsg messages. In short, the payload allows the text field of the message to store messages of arbitrary length and complexity. All types of ints (1,2,4,8 bytes), 4,8-byte floats, strings, binary, whole messages and arrays of all these types can be stored and retrieved from the compound payload. These methods are thread-safe.

Although XML would be a format well-suited to this task, cMsg should stand alone - not requiring an XML parser to work. It takes more memory and time to decode XML than a simple format. Thus, a simple, easy-to-parse format was developed to implement this interface.

Following is the text format of a complete compound payload (where [nl] means newline). Each payload consists of a number of items. The very first line is the number of items in the payload. That is followed by the text representation of each item. The first line of each item consists of 5 entries.

Note that there is only 1 space or newline between all entries. The only exception to the 1 space spacing is between the last two entries on each "header" line (the line that contains the item_name). There may be several spaces between the last 2 entries on these lines.

    item_count[nl]

for (arrays of) string items:

    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    string_length_1[nl]
    string_characters_1[nl]
     ~
     ~
     ~
    string_length_N[nl]
    string_characters_N

for (arrays of) binary (converted into text) items:

    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    string_length_1   original_binary_byte_length_1   endian_1[nl]
    string_characters_1[nl]
     ~
     ~
     ~
    string_length_N   original_binary_byte_length_N   endian_N[nl]
    string_characters_N

for primitive type items:

    item_name   item_type   item_count   isSystemItem?   item_length[nl]
    value_1   value_2   ...   value_N[nl]

A cMsg message is formatted as a compound payload. Each message has a number of fields (payload items).

for message items:

                                                                            _
    item_name   item_type   item_count   isSystemItem?   item_length[nl]   /
    message_1_in_compound_payload_text_format[nl]                         <  field_count[nl]
        ~                                                                  \ list_of_payload_format_items
        ~                                                                   -
        ~
    message_N_in_compound_payload_text_format[nl]

Notice that this format allows a message to store a message which stores a message which stores a message, ad infinitum. In other words, recursive message storing. The item_length in each case is the length in bytes of the rest of the item (not including the newline at the end).

Macro Definition Documentation

#define CMSG_BOTH_FIELDS 2

#define CMSG_PAYLOAD_FIELDS 1

#define CMSG_PAYLOAD_NAME_LEN 128

Maximum len in chars for a payload item name.

#define CMSG_SYSTEM_FIELDS 0

Typedef Documentation

typedef union u2 intDoubleUnion

Union defined to help in skirting optimization problems with gcc.

typedef union u1 intFloatUnion

Union defined to help in skirting optimization problems with gcc.

Function Documentation

int cMsgAddBinary	(	void *	vmsg,
		const char *	name,
		const char *	src,
		int	size,
		int	endian
	)

This routine adds a named field of binary data to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
src	pointer to binary data to add
size	size in bytes of data to add
endian	endian value of binary data, may be CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, or CMSG_ENDIAN_NOTLOCAL

Returns: CMSG_OK if successful; CMSG_ERROR if cannot find local endian; CMSG_BAD_ARGUMENT if message, src or name is NULL, size < 1, or endian != CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, or CMSG_ENDIAN_NOTLOCAL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddBinaryArray	(	void *	vmsg,
		const char *	name,
		const char *	src[],
		int	number,
		const int	size[],
		const int	endian[]
	)

This routine adds a named field of binary data to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
src	pointer to array of binary data arrays to add
number	number of arrays of binary data to add
size	array of sizes in bytes of binary data arrays to add
endian	array of endian values of binary data arrays, may be CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, or CMSG_ENDIAN_NOTLOCAL

Returns: CMSG_OK if successful; CMSG_ERROR if cannot find local endian; CMSG_BAD_ARGUMENT if message, src or name is NULL, size < 1, or endian != CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, or CMSG_ENDIAN_NOTLOCAL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed, or if error in binary-to-text transformation; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddDouble	(	void *	vmsg,
		const char *	name,
		double	val
	)

This routine adds a named, double field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	double to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_DBL.

int cMsgAddDoubleArray	(	void *	vmsg,
		const char *	name,
		const double	vals[],
		int	len
	)

This routine adds a named, double array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of doubles to add (copy)
len	number of doubles from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, name, or vals is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_DBL_A.

int cMsgAddFloat	(	void *	vmsg,
		const char *	name,
		float	val
	)

This routine adds a named, float field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	float to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_FLT.

int cMsgAddFloatArray	(	void *	vmsg,
		const char *	name,
		const float	vals[],
		int	len
	)

This routine adds a named, float array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of floats to add (copy)
len	number of floats from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, name, or vals is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_FLT_A.

int cMsgAddHistoryToPayloadText	(	void *	vmsg,
		char *	name,
		char *	host,
		int64_t	time,
		char **	pTxt
	)

Adds arguments to the history of senders, senderHosts, and senderTimes of this message (in the payload). This method only keeps cMsgMessage_t.historyLengthMax number of the most recent names. This method is reserved for system use only.

When a client sends the same message over and over again, we do NOT want the history to change. To ensure this, we follow a simple principle: the sender history needs to go into the sent message (ie. over the wire), but must not be added to the local one. Thus, if I send a message, its local sender history will not change.

Parameters

vmsg	pointer to message
name	name of sender to add to the history of senders
host	name of sender host to add to the history of hosts
time	sender time to add to the history of times
pTxt	pointer filled with text representation of payload with the history items added (memory is allocated)

Returns: CMSG_OK if successful; CMSG_ERROR if error in internal details of existing history payload items; CMSG_OUT_OF_MEMORY if out of memory

References CMSG_CP_INT64_A, CMSG_ERROR, CMSG_OK, CMSG_OUT_OF_MEMORY, cMsgGetInt64Array(), cMsgGetStringArray(), and cMsgPayloadContainsName().

int cMsgAddInt16	(	void *	vmsg,
		const char *	name,
		int16_t	val
	)

This routine adds a named, 16-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 16-bit, signed int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT16.

int cMsgAddInt16Array	(	void *	vmsg,
		const char *	name,
		const int16_t	vals[],
		int	len
	)

This routine adds a named, 16-bit, signed int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 16-bit, signed ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT16_A.

int cMsgAddInt32	(	void *	vmsg,
		const char *	name,
		int32_t	val
	)

This routine adds a named, 32-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 32-bit, signed int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT32.

int cMsgAddInt32Array	(	void *	vmsg,
		const char *	name,
		const int32_t	vals[],
		int	len
	)

This routine adds a named, 32-bit, signed int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 32-bit, signed ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT32_A.

int cMsgAddInt64	(	void *	vmsg,
		const char *	name,
		int64_t	val
	)

This routine adds a named, 64-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 64-bit, signed int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT64.

int cMsgAddInt64Array	(	void *	vmsg,
		const char *	name,
		const int64_t	vals[],
		int	len
	)

This routine adds a named, 64-bit, signed int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 64-bit, signed ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT64_A.

int cMsgAddInt8	(	void *	vmsg,
		const char *	name,
		int8_t	val
	)

This routine adds a named, 8-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 8-bit, signed int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT8.

int cMsgAddInt8Array	(	void *	vmsg,
		const char *	name,
		const int8_t	vals[],
		int	len
	)

This routine adds a named, 8-bit, signed int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 8-bit, signed ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_INT8_A.

int cMsgAddMessage	(	void *	vmsg,
		const char *	name,
		const void *	vmessage
	)

This routine adds a named cMsg message field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes. The string representation of the message is the same format as that used for a complete compound payload.

Parameters

vmsg	pointer to message
name	name of field to add
vmessage	cMsg message to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if any arg is NULL; CMSG_BAD_FORMAT if name is not properly formed, or if error in binary-to-text transformation; CMSG_OUT_OF_MEMORY if no more memory; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddMessageArray	(	void *	vmsg,
		const char *	name,
		const void *	vmessage[],
		int	len
	)

This routine adds a named field of an array of cMsg messages to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
vmessage	array of cMsg messages to add
len	number of messages from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message array, src, or name is NULL; len < 1; CMSG_BAD_FORMAT if name is not properly formed, or if error in binary-to-text transformation; CMSG_OUT_OF_MEMORY if no more memory; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddString	(	void *	vmsg,
		const char *	name,
		const char *	val
	)

This routine adds a named string field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	string to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, val or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddStringArray	(	void *	vmsg,
		const char *	name,
		const char **	vals,
		int	len
	)

This routine adds a named string array field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
vals	strings to add
len	number of strings to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

int cMsgAddUint16	(	void *	vmsg,
		const char *	name,
		uint16_t	val
	)

This routine adds a named, 16-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 16-bit, unsigned int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT16.

int cMsgAddUint16Array	(	void *	vmsg,
		const char *	name,
		const uint16_t	vals[],
		int	len
	)

This routine adds a named, 16-bit, unsigned int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 16-bit, unsigned ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT16_A.

int cMsgAddUint32	(	void *	vmsg,
		const char *	name,
		uint32_t	val
	)

This routine adds a named, 32-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 32-bit, unsigned int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT32.

int cMsgAddUint32Array	(	void *	vmsg,
		const char *	name,
		const uint32_t	vals[],
		int	len
	)

This routine adds a named, 32-bit, unsigned int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 32-bit, unsigned ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT32_A.

int cMsgAddUint64	(	void *	vmsg,
		const char *	name,
		uint64_t	val
	)

This routine adds a named, 64-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 64-bit, unsigned int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT64.

int cMsgAddUint64Array	(	void *	vmsg,
		const char *	name,
		const uint64_t	vals[],
		int	len
	)

This routine adds a named, 64-bit, unsigned int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 64-bit, unsigned ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT64_A.

int cMsgAddUint8	(	void *	vmsg,
		const char *	name,
		uint8_t	val
	)

This routine adds a named, 8-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.

Parameters

vmsg	pointer to message
name	name of field to add
val	value of 8-bit, unsigned int to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message or name is NULL; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT8.

int cMsgAddUint8Array	(	void *	vmsg,
		const char *	name,
		const uint8_t	vals[],
		int	len
	)

This routine adds a named, 8-bit, unsigned int array field to the compound payload of a message.

Parameters

vmsg	pointer to message
name	name of field to add
vals	array of 8-bit, unsigned ints to add (copy)
len	number of ints from array to add

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message, vals, or name is NULL; len < 1; CMSG_OUT_OF_MEMORY if no more memory; CMSG_BAD_FORMAT if name is not properly formed; CMSG_ALREADY_EXISTS if name is being used already

References CMSG_CP_UINT8_A.

char* cMsgDoubleChars ( double d )

This routine returns a string representation of a double in the form of 16 hex chars of the IEEE754 representation. String points to internal static character array.

Parameters

d	double value to convert

Returns: string of hex characters rep of IEEE765 bytes

char* cMsgFloatChars ( float f )

This routine returns a string representation of a float in the form of 8 hex chars of the IEEE754 representation. String points to internal static character array.

Parameters

f	float value to convert

Returns: string of hex characters rep of IEEE765 bytes

int cMsgGetBinary	(	const void *	vmsg,
		const char *	name,
		const char **	val,
		int *	size,
		int *	endian
	)

This routine returns the value of the given field as binary (byte array) if it exists. Do NOT write into the returned pointer's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value
size	pointer filled with number of bytes in binary array
endian	pointer filled with endian of data (CMSG_ENDIAN_BIG/LITTLE)

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_BIN, CMSG_ERROR, and CMSG_OK.

int cMsgGetBinaryArray	(	const void *	vmsg,
		const char *	name,
		const char ***	vals,
		int **	sizes,
		int **	endians,
		int *	count
	)

This routine returns the value of the given field as an array of binary data (array of byte arrays) if it exists. Do NOT write into the returned pointer's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with array of byte arrays
sizes	pointer filled with array of number of bytes in byte arrays
endians	pointer filled with array of endian of data in byte arrays (CMSG_ENDIAN_BIG/LITTLE)
count	pointer filled with number of element in each returned array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_BIN_A, CMSG_ERROR, and CMSG_OK.

int cMsgGetDouble	(	const void *	vmsg,
		const char *	name,
		double *	val
	)

This routine returns the double given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_DBL.

int cMsgGetDoubleArray	(	const void *	vmsg,
		const char *	name,
		const double **	vals,
		int *	len
	)

This routine returns the double array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_DBL_A, and CMSG_OK.

int cMsgGetFloat	(	const void *	vmsg,
		const char *	name,
		float *	val
	)

This routine returns a float of the given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_FLT, and CMSG_OK.

int cMsgGetFloatArray	(	const void *	vmsg,
		const char *	name,
		const float **	vals,
		int *	len
	)

This routine returns the float array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_FLT_A, and CMSG_OK.

int cMsgGetInt16	(	const void *	vmsg,
		const char *	name,
		int16_t *	val
	)

This routine returns a 16 bit, signed integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT16, and CMSG_OK.

int cMsgGetInt16Array	(	const void *	vmsg,
		const char *	name,
		const int16_t **	vals,
		int *	len
	)

This routine returns a 16 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT16_A, and CMSG_OK.

int cMsgGetInt32	(	const void *	vmsg,
		const char *	name,
		int32_t *	val
	)

This routine returns a 32 bit, signed integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT32, and CMSG_OK.

int cMsgGetInt32Array	(	const void *	vmsg,
		const char *	name,
		const int32_t **	vals,
		int *	len
	)

This routine returns a 32 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT32_A, and CMSG_OK.

int cMsgGetInt64	(	const void *	vmsg,
		const char *	name,
		int64_t *	val
	)

This routine returns a 64 bit, signed integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT64.

int cMsgGetInt64Array	(	const void *	vmsg,
		const char *	name,
		const int64_t **	vals,
		int *	len
	)

This routine returns a 64 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT64_A, and CMSG_OK.

Referenced by cMsgAddHistoryToPayloadText().

int cMsgGetInt8	(	const void *	vmsg,
		const char *	name,
		int8_t *	val
	)

This routine returns an 8 bit, signed integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT8, and CMSG_OK.

int cMsgGetInt8Array	(	const void *	vmsg,
		const char *	name,
		const int8_t **	vals,
		int *	len
	)

This routine returns an 8 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_INT8_A, and CMSG_OK.

int cMsgGetMessage	(	const void *	vmsg,
		const char *	name,
		const void **	val
	)

This routine returns the value of the given field as a cMsg message if it exists. Do NOT write into the returned pointer's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_MSG, CMSG_ERROR, and CMSG_OK.

int cMsgGetMessageArray	(	const void *	vmsg,
		const char *	name,
		const void ***	val,
		int *	len
	)

This routine returns the value of the given field as an array of cMsg messages if it exists. Do NOT write into the returned pointer's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with array value
len	pointer to int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_MSG_A, CMSG_ERROR, and CMSG_OK.

int cMsgGetString	(	const void *	vmsg,
		const char *	name,
		const char **	val
	)

This routine returns the value of the given field as a string if it exists. Do NOT write into the returned pointer's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_STR, CMSG_ERROR, and CMSG_OK.

int cMsgGetStringArray	(	const void *	vmsg,
		const char *	name,
		const char ***	array,
		int *	len
	)

This routine returns the string array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
array	pointer to array of pointers which gets filled with string array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_BAD_FORMAT, CMSG_CP_STR_A, CMSG_ERROR, and CMSG_OK.

Referenced by cMsgAddHistoryToPayloadText().

int cMsgGetUint16	(	const void *	vmsg,
		const char *	name,
		uint16_t *	val
	)

This routine returns a 16 bit, unsigned integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT16, and CMSG_OK.

int cMsgGetUint16Array	(	const void *	vmsg,
		const char *	name,
		const uint16_t **	vals,
		int *	len
	)

This routine returns a 16 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT16_A, and CMSG_OK.

int cMsgGetUint32	(	const void *	vmsg,
		const char *	name,
		uint32_t *	val
	)

This routine returns a 32 bit, unsigned integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT32, and CMSG_OK.

int cMsgGetUint32Array	(	const void *	vmsg,
		const char *	name,
		const uint32_t **	vals,
		int *	len
	)

This routine returns a 32 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT32_A, and CMSG_OK.

int cMsgGetUint64	(	const void *	vmsg,
		const char *	name,
		uint64_t *	val
	)

This routine returns a 64 bit, unsigned integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT64, and CMSG_OK.

int cMsgGetUint64Array	(	const void *	vmsg,
		const char *	name,
		const uint64_t **	vals,
		int *	len
	)

This routine returns a 64 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT64_A, and CMSG_OK.

int cMsgGetUint8	(	const void *	vmsg,
		const char *	name,
		uint8_t *	val
	)

This routine returns an 8 bit, unsigned integer given field if it exists.

Parameters

vmsg	pointer to message
name	name of payload field
val	pointer filled with field value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT8, and CMSG_OK.

int cMsgGetUint8Array	(	const void *	vmsg,
		const char *	name,
		const uint8_t **	vals,
		int *	len
	)

This routine returns an 8 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.

Parameters

vmsg	pointer to message
name	name of payload field
vals	pointer filled with field array
len	pointer int which gets filled with the number of elements in array

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_FORMAT field is not right type or contains error; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_CP_UINT8_A, and CMSG_OK.

int cMsgHasPayload	(	const void *	vmsg,
		int *	hasPayload
	)

This routine returns whether a message has a compound payload or not. It returns 0 if there is no payload and the number of items in the payload is there is one.

Parameters

vmsg	pointer to message
hasPayload	pointer which gets filled with the number of items if msg has compound payload, else 0

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if either arg is NULL

References cMsgPayloadGetCount().

Referenced by cMsgCopyMessage().

char* cMsgIntChars ( uint32_t i )

This routine returns a unique string representation of a int in the form of 8 hex chars. String points to allocated memory which needs to be freed by caller to avoid a memory leak.

Parameters

i	int value to convert

Returns: string of hex characters rep of 32 bit unsigned int, needs to be freed by caller

void cMsgPayloadClear ( void * vmsg )

This routine removes all the user-added items in the given message's payload. The payload may still contain fields added by the cMsg system. If there are no items left in the payload, this routine is equivalent to cMsgPayloadReset.

Parameters

vmsg	pointer to message

References cMsgPayloadUpdateText().

int cMsgPayloadContainsName	(	const void *	vmsg,
		const char *	name
	)

This routine checks to see if a name is already in use by an existing field in the payload.

Parameters

vmsg	pointer to message
name	name to check

Returns: 0 if name does not exist or there is no payload; 1 if name exists

Referenced by cMsgAddHistoryToPayloadText().

int cMsgPayloadCopy	(	const void *	vmsgFrom,
		void *	vmsgTo
	)

This routine copies the payload from one message to another. The original payload of the "to" message is overwritten.

Parameters

vmsgFrom	pointer to message to copy payload from
vmsgTo	pointer to message to copy payload to

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if either argument is null; CMSG_OUT_OF_MEMORY if operating system out of memory

References CMSG_BAD_ARGUMENT, CMSG_CP_INT64_A, CMSG_OK, and CMSG_OUT_OF_MEMORY.

Referenced by cMsgCopyMessage().

const char* cMsgPayloadFieldDescription	(	const void *	vmsg,
		const char *	name
	)

This routine returns a description of the given field name. Do NOT write to this location in memory.

Parameters

vmsg	pointer to message
name	name of field to describe

Returns: NULL if no payload exists; field name if field exists

References CMSG_CP_BIN, CMSG_CP_BIN_A, CMSG_CP_DBL, CMSG_CP_DBL_A, CMSG_CP_FLT, CMSG_CP_FLT_A, CMSG_CP_INT16, CMSG_CP_INT16_A, CMSG_CP_INT32, CMSG_CP_INT32_A, CMSG_CP_INT64, CMSG_CP_INT64_A, CMSG_CP_INT8, CMSG_CP_INT8_A, CMSG_CP_MSG, CMSG_CP_MSG_A, CMSG_CP_STR, CMSG_CP_STR_A, CMSG_CP_UINT16, CMSG_CP_UINT16_A, CMSG_CP_UINT32, CMSG_CP_UINT32_A, CMSG_CP_UINT64, CMSG_CP_UINT64_A, CMSG_CP_UINT8, CMSG_CP_UINT8_A, and cMsgPayloadGetType().

int cMsgPayloadGet	(	const void *	vmsg,
		char **	names,
		int *	types,
		int	len
	)

This routine fills 2 arrays provided by the caller. One contains all the names of the items in the payload, and the second contains the corresponding data types of those items. Each element of the array of characters points to a string in the message itself which must not be freed or written to. The difference between this routine and cMsgPayloadGetInfo is that this routine allocates no memory so nothing needs to be freed.

Parameters

vmsg	pointer to message
names	pointer which gets filled with the array of names in a payload
types	pointer to an array of ints which gets filled with type of data associated with each field name in "names"
len	length of each of the given arrays, if arrays are different lengths give the smallest of the lengths

Returns: CMSG_OK if successful; CMSG_ERROR if no payload is found; CMSG_BAD_ARGUMENT if any arg is NULL or of improper value; CMSG_LIMIT_EXCEEDED if len < the number of items, but len number of valid values are still returned in names and types

References CMSG_BAD_ARGUMENT, CMSG_ERROR, CMSG_LIMIT_EXCEEDED, and CMSG_OK.

int cMsgPayloadGetCount	(	const void *	vmsg,
		int *	count
	)

This routine returns the number of payload items a message has.

Parameters

vmsg	pointer to message
count	pointer which gets filled with the number of payload items (0 for no payload)

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

Referenced by cMsgHasPayload().

int cMsgPayloadGetFieldPointer	(	const void *	vmsg,
		const char *	name,
		void **	p
	)

This routine returns the user pointer of the given field. Used to implement C++ interface to compound payload.

Parameters

vmsg	pointer to message
name	name of payload item
p	pointer that gets filled with user pointer

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ERROR, and CMSG_OK.

int cMsgPayloadGetFieldText	(	const void *	vmsg,
		const char *	name,
		const char **	val
	)

This routine returns a pointer to the string representation of the given field. Do NOT write to this location in memory.

Parameters

vmsg	pointer to message
name	name of field
val	pointer to pointer which is set to string representation of field

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ERROR, and CMSG_OK.

int cMsgPayloadGetInfo	(	const void *	vmsg,
		char ***	names,
		int **	types,
		int *	len
	)

This routine returns 2 arrays. One contains all the names of the items in the payload, and the second contains the corresponding data types of those items. It also returns the length of both arrays. Both arrays use allocated memory and must be freed by the caller. Each element of the array of characters points to a string in the message itself which must not be freed or written to. The difference between this routine and cMsgPayloadGet is that the other routine allocates no memory so nothing needs to be freed.

Parameters

vmsg	pointer to message
names	pointer which gets filled with the array of names in a payload
types	pointer to an array of ints which gets filled with type of data associated with each field name in "names"
len	pointer to int which gives the length of the returned arrays

Returns: CMSG_OK if successful; CMSG_ERROR if no payload is found; CMSG_BAD_ARGUMENT if any arg is NULL; CMSG_OUT_OF_MEMORY if out of memory

References CMSG_BAD_ARGUMENT, CMSG_ERROR, CMSG_OK, and CMSG_OUT_OF_MEMORY.

int cMsgPayloadGetType	(	const void *	vmsg,
		const char *	name,
		int *	type
	)

This routine returns the type of data associated with the payload field given by the name argument. The returned type may have the following values:

CMSG_CP_STR for a String
CMSG_CP_FLT for a 4 byte float
CMSG_CP_DBL for an 8 byte float
CMSG_CP_INT8 for an 8 bit int
CMSG_CP_INT16 for a 16 bit int
CMSG_CP_INT32 for a 32 bit int
CMSG_CP_INT64 for a 64 bit int
CMSG_CP_UINT8 for an unsigned 8 bit int
CMSG_CP_UINT16 for an unsigned 16 bit int
CMSG_CP_UINT32 for an unsigned 32 bit int
CMSG_CP_UINT64 for an unsigned 64 bit int
CMSG_CP_MSG for a cMsg message
CMSG_CP_BIN for binary
CMSG_CP_STR_A for a String array
CMSG_CP_FLT_A for a 4 byte float array
CMSG_CP_DBL_A for an 8 byte float array
CMSG_CP_INT8_A for an 8 bit int array
CMSG_CP_INT16_A for a 16 bit int array
CMSG_CP_INT32_A for a 32 bit int array
CMSG_CP_INT64_A for a 64 bit int array
CMSG_CP_UINT8_A for an unsigned 8 bit int array
CMSG_CP_UINT16_A for an unsigned 16 bit int array
CMSG_CP_UINT32_A for an unsigned 32 bit int array
CMSG_CP_UINT64_A for an unsigned 64 bit int array
CMSG_CP_MSG_A for a cMsg message array
CMSG_CP_BIN_A for an array of binary items

Parameters

vmsg	pointer to message
name	name of payload field
type	pointer to int gets filled with type of data associated with field given by name

Returns: CMSG_OK if successful; CMSG_ERROR if no field of the given name is found; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ERROR, and CMSG_OK.

Referenced by cMsgPayloadFieldDescription().

void cMsgPayloadPrint ( const void * vmsg )

This routine prints out the message payload in a readable form.

Parameters

vmsg	pointer to message

int cMsgPayloadRemove	(	void *	vmsg,
		const char *	name
	)

This routine removes the named field if it exists.

Parameters

vmsg	pointer to message
name	name of field to remove

Returns: 1 if successful; 0 if no field with that name was found

void cMsgPayloadReset ( void * vmsg )

This routine resets the payload to its initial condition (no payload). It frees the allocated memory of the given message's entire payload and then initializes the payload components of the message.

Parameters

vmsg	pointer to message

void cMsgPayloadReset_r ( void * vmsg )

This routine resets the payload to its initial condition (no payload), but in a way which avoids mutex deadlock when recursively freeing a payload's cMsgMessage items (ie. doesn't call grabMutex()).

Parameters

vmsg	pointer to message

int cMsgPayloadSetAllFieldsFromText	(	void *	vmsg,
		const char *	text
	)

This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the hidden system fields and payload of the message. This overwrites any existing system fields and payload.

Parameters

vmsg	pointer to message
text	string sent over network to be unmarshalled

Returns: NULL if no payload exists or no memory

int cMsgPayloadSetFieldPointer	(	const void *	vmsg,
		const char *	name,
		void *	p
	)

This routine sets the user pointer of the given field. Used to implement C++ interface to compound payload.

Parameters

vmsg	pointer to message
name	name of payload item
p	user pointer value

Returns: CMSG_OK if successful; CMSG_ERROR if no payload or field of that name exists; CMSG_BAD_ARGUMENT if any arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ERROR, and CMSG_OK.

int cMsgPayloadSetFromText	(	void *	vmsg,
		const char *	text
	)

This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the standard message payload. All system information is ignored. This overwrites any existing payload and skips over any fields with names starting with "cMsg" (as they are reserved for system use).

Parameters

vmsg	pointer to message
text	string sent over network to be unmarshalled

Returns: NULL if no payload exists or no memory

int cMsgPayloadSetSystemFieldsFromText	(	void *	vmsg,
		const char *	text
	)

This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the hidden system fields of the message. All non-system information is ignored. This overwrites any existing system fields.

Parameters

vmsg	pointer to message
text	string sent over network to be unmarshalled

Returns: NULL if no payload exists or no memory

int cMsgPayloadUpdateText ( const void * vmsg )

This routine updates the text representation of a message's payload. This routine is used internally and does not need to be called by the cMsg user.

Parameters

vmsg	pointer to message

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if arg is NULL; CMSG_OUT_OF_MEMORY if out of memory

References CMSG_BAD_ARGUMENT, and CMSG_OK.

Referenced by cMsgPayloadClear().

Macros

Typedefs

Functions

Detailed Description

Introduction

Macro Definition Documentation

Typedef Documentation

Function Documentation