This class 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 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 binary (converted into text) items:
item_name item_type original_binary_byte_length isSystemItem? item_length[nl] string_length endian[nl] string_characters[nl]
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).
#include <strings.h>
#include <dlfcn.h>
#include <inttypes.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <pthread.h>
#include "cMsgPrivate.h"
#include "cMsgNetwork.h"
Defines | |
#define | CMSG_PAYLOAD_NAME_LEN 128 |
#define | CMSG_SYSTEM_FIELDS 0 |
#define | CMSG_PAYLOAD_FIELDS 1 |
#define | CMSG_BOTH_FIELDS 2 |
Typedefs | |
typedef u1 | intFloatUnion |
typedef u2 | intDoubleUnion |
Functions | |
char * | cMsgFloatChars (float f) |
char * | cMsgDoubleChars (double d) |
void | cMsgPayloadWipeout (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 | cMsgAddSenderToHistory (void *vmsg, char *name) |
int | cMsgPayloadCopy (const void *vmsgFrom, void *vmsgTo) |
int | cMsgPayloadUpdateText (const void *vmsg) |
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 *len, int *endian) |
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 | 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) |
|
|
|
|
|
Maximum len in chars for a payload item name. |
|
|
|
Union defined to help in skirting optimization problems with gcc. |
|
Union defined to help in skirting optimization problems with gcc. |
|
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.
|
|
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.
|
|
This routine adds a named, double array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, float array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 16-bit, signed int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 32-bit, signed int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 64-bit, signed int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 8-bit, signed int array field to the compound payload of a message.
|
|
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.
|
|
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.
|
|
Adds a name to the history of senders 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.
|
|
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.
|
|
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.
|
|
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.
|
|
This routine adds a named, 16-bit, unsigned int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 32-bit, unsigned int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 64-bit, unsigned int array field to the compound payload of a message.
|
|
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.
|
|
This routine adds a named, 8-bit, unsigned int array field to the compound payload of a message.
|
|
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.
|
|
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.
|
|
This routine returns the value of the given field as a binary array if it exists. Do NOT write into the returned pointer's memory location.
|
|
This routine returns the double given field if it exists.
|
|
This routine returns the double array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a float of the given field if it exists.
|
|
This routine returns the float array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 16 bit, signed integer given field if it exists.
|
|
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.
|
|
This routine returns a 32 bit, signed integer given field if it exists.
|
|
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.
|
|
This routine returns a 64 bit, signed integer given field if it exists.
|
|
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.
|
|
This routine returns an 8 bit, signed integer given field if it exists.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
This routine returns the string array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 16 bit, unsigned integer given field if it exists.
|
|
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.
|
|
This routine returns a 32 bit, unsigned integer given field if it exists.
|
|
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.
|
|
This routine returns a 64 bit, unsigned integer given field if it exists.
|
|
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.
|
|
This routine returns an 8 bit, unsigned integer given field if it exists.
|
|
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.
|
|
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.
|
|
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 cMsgPayloadWipeout.
|
|
This routine checks to see if a name is already in use by an existing field in the payload.
|
|
This routine copies the payload from one message to another. The original payload of the "to" message is overwritten.
|
|
This routine returns a description of the given field name. Do NOT write to this location in memory.
|
|
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.
|
|
This routine returns the number of payload items a message has.
|
|
This routine returns the user pointer of the given field. Used to implement C++ interface to compound payload.
|
|
This routine returns a pointer to the string representation of the given field. Do NOT write to this location in memory.
|
|
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.
|
|
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:
|
|
This routine prints out the message payload in a readable form.
|
|
This routine removes the named field if it exists.
|
|
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.
|
|
This routine sets the user pointer of the given field. Used to implement C++ interface to compound payload.
|
|
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).
|
|
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.
|
|
This routine creates a string representation of the whole compound payload in a form for sending over the network. It stores that string in the given message.
|
|
This routine frees the allocated memory of the given message's entire payload and then initializes the payload components of the message.
|