#include <stdlib.h>
#include <time.h>
#include "cMsgConstants.h"
#include <inttypes.h>

Typedefs
typedef void *	cMsgSubscribeConfig

typedef void(	cMsgShutdownHandler )(void *userArg)

typedef void(	cMsgCallbackFunc )(void msg, void userArg)

Functions
int	cMsgConnect (const char myUDL, const char myName, const char myDescription, void *domainId)

int	cMsgReconnect (void *domainId)

int	cMsgSend (void domainId, void msg)

int	cMsgSyncSend (void domainId, void msg, const struct timespec timeout, int response)

int	cMsgFlush (void domainId, const struct timespec timeout)

int	cMsgSubscribe (void domainId, const char subject, const char type, cMsgCallbackFunc callback, void userArg, cMsgSubscribeConfig config, void **handle)

int	cMsgUnSubscribe (void domainId, void handle)

int	cMsgSubscriptionPause (void domainId, void handle)

int	cMsgSubscriptionResume (void domainId, void handle)

int	cMsgSubscriptionQueueClear (void domainId, void handle)

int	cMsgSubscriptionQueueCount (void domainId, void handle, int *count)

int	cMsgSubscriptionQueueIsFull (void domainId, void handle, int *full)

int	cMsgSubscriptionMessagesTotal (void domainId, void handle, int *total)

int	cMsgSendAndGet (void domainId, void sendMsg, const struct timespec timeout, void *replyMsg)

int	cMsgSubscribeAndGet (void domainId, const char subject, const char type, const struct timespec timeout, void **replyMsg)

int	cMsgMonitor (void domainId, const char command, void **replyMsg)

int	cMsgReceiveStart (void *domainId)

int	cMsgReceiveStop (void *domainId)

int	cMsgDisconnect (void **domainId)

int	cMsgSetShutdownHandler (void domainId, cMsgShutdownHandler handler, void *userArg)

int	cMsgShutdownClients (void domainId, const char client, int flag)

int	cMsgShutdownServers (void domainId, const char server, int flag)

int	cMsgGetConnectState (void domainId, int connectState)

int	cMsgSetUDL (void domainId, const char udl)

int	cMsgGetCurrentUDL (void domainId, const char *udl)

int	cMsgGetServerHost (void domainId, const char *ipAddress)

int	cMsgGetServerPort (void domainId, int port)

int	cMsgGetInfo (void domainId, const char command, char **string)

char *	cMsgPerror (int errorCode)

int	cMsgFreeMessage (void **vmsg)

void *	cMsgCreateMessage (void)

void *	cMsgCreateNewMessage (const void *vmsg)

void *	cMsgCopyMessage (const void *vmsg)

int	cMsgInitMessage (void *vmsg)

void *	cMsgCreateResponseMessage (const void *vmsg)

void *	cMsgCreateNullResponseMessage (const void *vmsg)

int	cMsgWasSent (const void vmsg, int hasBeenSent)

int	cMsgGetVersion (const void vmsg, int version)

int	cMsgGetGetRequest (const void vmsg, int getRequest)

int	cMsgSetGetResponse (void *vmsg, int getReponse)

int	cMsgGetGetResponse (const void vmsg, int getReponse)

int	cMsgSetNullGetResponse (void *vmsg, int nullGetResponse)

int	cMsgGetNullGetResponse (const void vmsg, int nullGetResponse)

int	cMsgGetDomain (const void vmsg, const char *domain)

int	cMsgGetPayloadText (const void vmsg, const char *payloadText)

int	cMsgSetSubject (void vmsg, const char subject)

int	cMsgGetSubject (const void vmsg, const char *subject)

int	cMsgSetType (void vmsg, const char type)

int	cMsgGetType (const void vmsg, const char *type)

int	cMsgSetText (void vmsg, const char text)

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

int	cMsgSetUserInt (void *vmsg, int userInt)

int	cMsgGetUserInt (const void vmsg, int userInt)

int	cMsgSetUserTime (void vmsg, const struct timespec userTime)

int	cMsgGetUserTime (const void vmsg, struct timespec userTime)

int	cMsgGetSender (const void vmsg, const char *sender)

int	cMsgGetSenderHost (const void vmsg, const char *senderHost)

int	cMsgGetSenderTime (const void vmsg, struct timespec senderTime)

int	cMsgGetReceiver (const void vmsg, const char *receiver)

int	cMsgGetReceiverHost (const void vmsg, const char *receiverHost)

int	cMsgGetReceiverTime (const void vmsg, struct timespec receiverTime)

int	cMsgSetByteArrayLength (void *vmsg, int length)

int	cMsgResetByteArrayLength (void *vmsg)

int	cMsgGetByteArrayLength (const void vmsg, int length)

int	cMsgGetByteArrayLengthFull (const void vmsg, int length)

int	cMsgSetByteArrayOffset (void *vmsg, int offset)

int	cMsgGetByteArrayOffset (const void vmsg, int offset)

int	cMsgSetByteArrayEndian (void *vmsg, int endian)

int	cMsgGetByteArrayEndian (const void vmsg, int endian)

int	cMsgNeedToSwap (const void vmsg, int swap)

int	cMsgSetByteArray (void vmsg, char array, int length)

int	cMsgSetByteArrayNoCopy (void vmsg, char array, int length)

int	cMsgGetByteArray (const void vmsg, char *array)

int	cMsgSetReliableSend (void *vmsg, int boolean)

int	cMsgGetReliableSend (void vmsg, int boolean)

int	cMsgGetSubscriptionDomain (const void vmsg, const char *domain)

int	cMsgGetSubscriptionSubject (const void vmsg, const char *subject)

int	cMsgGetSubscriptionType (const void vmsg, const char *type)

int	cMsgGetSubscriptionUDL (const void vmsg, const char *udl)

int	cMsgGetSubscriptionCueSize (const void vmsg, int size)

int	cMsgToString (const void vmsg, char *string)

int	cMsgToString2 (const void vmsg, char *string, int binary, int compact, int noSystemFields)

int	cMsgPayloadToString (const void vmsg, char *string, int binary, int compact, int noSystemFields)

void	cMsgTrim (char *s)

void	cMsgTrimChar (char *s, char trimChar)

void	cMsgTrimDoubleChars (char *s, char trimChar)

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

int	cMsgSetHistoryLengthMax (void *vmsg, int len)

int	cMsgGetHistoryLengthMax (const void vmsg, int len)

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

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

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	cMsgPayloadRemove (void vmsg, const char name)

int	cMsgPayloadCopy (const void vmsgFrom, void vmsgTo)

int	cMsgPayloadUpdateText (const void *vmsg)

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

void	cMsgPayloadPrint (const void *vmsg)

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

int	cMsgPayloadSetFromText (void vmsg, const char text)

int	cMsgPayloadSetSystemFieldsFromText (void vmsg, const char text)

int	cMsgPayloadSetAllFieldsFromText (void vmsg, const char text)

void	cMsgPayloadReset (void *vmsg)

void	cMsgPayloadClear (void *vmsg)

int	cMsgHasPayload (const void vmsg, int hasPayload)

int	cMsgGetBinary (const void vmsg, const char name, const char *val, int len, 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	cMsgGetString (const void vmsg, const char name, const char **val)

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

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

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

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

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	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	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	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	cMsgAddMessage (void vmsg, const char name, const void *vmessage)

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

char *	cMsgFloatChars (float f)

char *	cMsgDoubleChars (double d)

char *	cMsgIntChars (uint32_t i)

int	cMsgGetUDL (void domainId, char *udl)

int	cMsgGetName (void domainId, char *name)

int	cMsgGetDescription (void domainId, char *description)

int	cMsgGetReceiveState (void domainId, int receiveState)

cMsgSubscribeConfig *	cMsgSubscribeConfigCreate (void)

int	cMsgSubscribeConfigDestroy (cMsgSubscribeConfig *config)

int	cMsgSubscribeSetMaxCueSize (cMsgSubscribeConfig *config, int size)

int	cMsgSubscribeGetMaxCueSize (cMsgSubscribeConfig config, int size)

int	cMsgSubscribeSetSkipSize (cMsgSubscribeConfig *config, int size)

int	cMsgSubscribeGetSkipSize (cMsgSubscribeConfig config, int size)

int	cMsgSubscribeSetMaySkip (cMsgSubscribeConfig *config, int maySkip)

int	cMsgSubscribeGetMaySkip (cMsgSubscribeConfig config, int maySkip)

int	cMsgSubscribeSetMustSerialize (cMsgSubscribeConfig *config, int serialize)

int	cMsgSubscribeGetMustSerialize (cMsgSubscribeConfig config, int serialize)

int	cMsgSubscribeSetMaxThreads (cMsgSubscribeConfig *config, int threads)

int	cMsgSubscribeGetMaxThreads (cMsgSubscribeConfig config, int threads)

int	cMsgSubscribeSetMessagesPerThread (cMsgSubscribeConfig *config, int mpt)

int	cMsgSubscribeGetMessagesPerThread (cMsgSubscribeConfig config, int mpt)

int	cMsgSubscribeSetStackSize (cMsgSubscribeConfig *config, size_t size)

int	cMsgSubscribeGetStackSize (cMsgSubscribeConfig config, size_t size)

int	cMsgSetDebugLevel (int level)

Detailed Description

This is the one necessary header file for all cMsg C users. C++ users must include cMsg.hxx instead, which includes this file.

INTRODUCTION

cMsg is a simple, abstract API to an arbitrary underlying message service. It is powerful enough to support synchronous and asynchronous point-to-point and publish/subscribe communication, and network-accessible message queues. Note that a given underlying implementation may not necessarily implement all these features.

DOMAINS

The abstraction relies on the important concept of a "domain", specified via a "Universal Domain Locator" (UDL) of the form:

cMsg:domainType://domainInfo

The domain type refers to an underlying messaging software implementation, and the domain info is interpreted by the implementation. Generally domains with different UDL's are isolated from each other, but this is not necessarily the case. For example, users can easily create gateways between different domains, or different domain servers may serve into the same messaging namespace.

The full domain specifier for the full cMsg domain looks like:

cMsg:cMsg://node:port/cMsg/namespace?param1=val1(&param2=val2)

where node:port correspond to the node and port of a cMsg nameserver, and namespace allows for multiple namespaces on the same server. If the port is missing a default port is used. Parameters are optional and not specified at this time. Currently different cMsg domains are completely isolated from each other. A process can connect to multiple domains if desired.

MESSAGES

Messages are sent via cMsgSend() and related functions. Messages have a type and are sent to a subject, and both are arbitrary strings. The payload consists of a single text string. Users must call cMsgFlush() to initiate delivery of messages in the outbound send queues, although the implementation may deliver messages before cMsgFlush() is called. Additional message meta-data may be set by the user (see below), although much of it is set by the system.

Message consumers ask the system to deliver messages to them that match various subject/type combinations (each may be NULL). The messages are delivered asynchronously to callbacks (via cMsgSubscribe()). cMsgFreeMessage() must be called when the user is done processing the message. Synchronous or RPC-like messaging is also possible via cMsgSendAndGet().

cMsgReceiveStart() must be called to start delivery of messages to callbacks.

In the cMsg domain perl-like subject wildcard characters are supported, multiple callbacks for the same subject/type are allowed, and each callback executes in its own thread.

ADDITIONAL INFORMATION

See the cMsg User's Guide and the cMsg Developer's Guide for more information. See the cMsg Doxygen and Java docs for the full API specification.

Typedef Documentation

typedef void( cMsgCallbackFunc)(void *msg, void *userArg)

Callback function.

typedef void( cMsgShutdownHandler)(void *userArg)

Shutdown handler function.

typedef void* cMsgSubscribeConfig

Subscribe configuration.

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.

int cMsgConnect	(	const char *	myUDL,
		const char *	myName,
		const char *	myDescription,
		void **	domainId
	)

This routine is called once to connect to a domain. The argument "myUDL" is the Universal Domain Locator used to uniquely identify the cMsg server to connect to. It has the form:

cMsg:domainType://domainInfo

The argument "myName" is the client's name and may be required to be unique within the domain depending on the domain. The argument "myDescription" is an arbitrary string used to describe the client. If successful, this routine fills the argument "domainId", which identifies the connection uniquely and is required as an argument by many other routines.

Parameters

myUDL	the Universal Domain Locator used to uniquely identify the cMsg server to connect to
myName	name of this client
myDescription	description of this client
domainId	pointer to pointer which gets filled with a unique id referring to this connection.

Returns: CMSG_OK if successful; CMSG_ERROR if regular expression compilation fails during UDL parsing or circular UDL references; CMSG_BAD_ARGUMENT if one of the arguments is bad; CMSG_BAD_FORMAT if the UDL is formatted incorrectly; CMSG_OUT_OF_MEMORY if out of memory (allocated or static); any errors returned from the actual domain dependent implemenation of cMsgConnect

References CMSG_BAD_ARGUMENT, CMSG_BAD_DOMAIN_TYPE, CMSG_OK, CMSG_OUT_OF_MEMORY, and LOCAL_ARRAY_SIZE.

void* cMsgCopyMessage ( const void * vmsg )

This routine copies a message. Memory is allocated with this function and can be freed by cMsgFreeMessage(). If the given message has a byte array that was copied in, it is copied again into the new message. Otherwise, if it has a byte array whose pointer was copied, the new message will point to the same byte array.

Parameters

vmsg	pointer to message structure being copied

Returns: a pointer to the message copy; NULL if argument is NULL or no memory available

References CMSG_OK, cMsgHasPayload(), and cMsgPayloadCopy().

Referenced by cMsgCreateNewMessage().

void* cMsgCreateMessage ( void )

This routine creates a new, initialized message. Memory is allocated with this function and can be freed by cMsgFreeMessage().

Returns: a pointer to the new message; NULL if no memory available

Referenced by cMsgCreateNullResponseMessage(), and cMsgCreateResponseMessage().

void* cMsgCreateNewMessage ( const void * vmsg )

This routine copies the given message, clears the history, and is marked as NOT having been sent. Memory is allocated with this function and can be freed by cMsgFreeMessage().

Parameters

vmsg	pointer to message being copied

Returns: a pointer to the new message; NULL if no memory available or message argument is NULL

References cMsgCopyMessage().

void* cMsgCreateNullResponseMessage ( const void * vmsg )

This routine creates a new, initialized message with some fields copied from the given message in order to make it a proper "NULL" (or no message) response to a sendAndGet() request. Memory is allocated with this function and can be freed by cMsgFreeMessage().

Parameters

vmsg	pointer to message to which response fields are set

Returns: a pointer to the new message; NULL if no memory available, message argument is NULL, or message argument is not from calling sendAndGet()

References cMsgCreateMessage().

void* cMsgCreateResponseMessage ( const void * vmsg )

This routine creates a new, initialized message with some fields copied from the given message in order to make it a proper response to a sendAndGet() request. Memory is allocated with this function and can be freed by cMsgFreeMessage().

Parameters

vmsg	pointer to message to which response fields are set

Returns: a pointer to the new message; NULL if no memory available, message argument is NULL, or message argument is not from calling sendAndGet()

References cMsgCreateMessage().

int cMsgDisconnect ( void ** domainId )

This routine disconnects the client from the cMsg server. May only call this once if it succeeds since it frees memory.

Parameters

domainId address of domain connection id

Returns: CMSG_OK if successful; CMSG_ERROR if this routine already called for the given domainId; CMSG_BAD_ARGUMENT if the domainId or the pointer it refers to is NULL, or cMsgDisconnect() already called; CMSG_LOST_CONNECTION if no longer connected to domain; any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

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 cMsgFlush	(	void *	domainId,
		const struct timespec *	timeout
	)

This routine sends any pending (queued up) communication with the server. The implementation of this routine depends entirely on the domain in which it is being used. In the cMsg domain, this routine does nothing as all server communications are sent immediately upon calling any function.

Parameters

domainId	domain connection id
timeout	amount of time to wait for completion

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgFlush

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgFreeMessage ( void ** vmsg )

This routine frees the memory allocated in the creation of a message. The cMsg client must call this routine on any messages created to avoid memory leaks.

Parameters

vmsg	address of pointer to message structure being freed

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if msg is NULL

References CMSG_OK.

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 cMsgGetByteArray	(	const void *	vmsg,
		char **	array
	)

This routine gets a message's byte array.

Parameters

vmsg	pointer to message
array	pointer to be filled with byte array

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetByteArrayEndian	(	const void *	vmsg,
		int *	endian
	)

This routine gets the endianness of the byte array data. Valid returned values are:

Parameters

vmsg	pointer to message
endian	int pointer to be filled with byte array data endianness

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

References CMSG_BAD_ARGUMENT, CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, and CMSG_OK.

int cMsgGetByteArrayLength	(	const void *	vmsg,
		int *	length
	)

This routine gets the region-of-interest length of a message's byte array.

Parameters

vmsg	pointer to message
length	int pointer to be filled with byte array length (in bytes)

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetByteArrayLengthFull	(	const void *	vmsg,
		int *	length
	)

This routine gets the total length of a message's byte array.

Parameters

vmsg	pointer to message
length	int pointer to be filled with byte array's total length (in bytes)

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetByteArrayOffset	(	const void *	vmsg,
		int *	offset
	)

This routine gets the region-of-interest offset of a message's byte array.

Parameters

vmsg	pointer to message
offset	int pointer to be filled with byte array offset index

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetConnectState	(	void *	domainId,
		int *	connected
	)

This routine gets the state of a cMsg connection. If connectState gets filled with a one, there is a valid connection. Anything else (zero in this case), indicates client is not connected. The meaning of "connected" may vary with domain.

Parameters

domainId	domain connection id
connected	integer pointer to be filled in with connection state, (1-connected, 0-unconnected)

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgGetConnectState

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgGetCurrentUDL	(	void *	domainId,
		const char **	udl
	)

This routine gets the UDL current used in the existing connection.

Parameters

domainId	domain connection id
udl	pointer filled in with current UDL or NULL if no connection

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or udl arg is NULL; any errors returned from the actual domain dependent implemenation of cMsgGetConnectState

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgGetDescription	(	void *	domainId,
		char **	description
	)

This routine gets the client description used in a cMsg connection. If successful, this routine will return a pointer to char inside the system structure. The user may NOT write to this memory location!

Parameters

domainId	id of the domain connection
description	pointer to pointer filled with the description

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetDomain	(	const void *	vmsg,
		const char **	domain
	)

This routine gets the domain of a message. When a message is newly created (eg. by cMsgCreateMessage()), the domain field of a message is not set. In the cMsg domain, the cMsg server sets this field when it receives a client's sent message. Messages received from the server will have this field set. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
domain	pointer to pointer filled with message's cMsg domain

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

References CMSG_BAD_ARGUMENT, 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 cMsgGetGetRequest	(	const void *	vmsg,
		int *	getRequest
	)

This routine gets the "get request" field of a message. The "get request" field indicates the message was sent by a sendAndGet call, if it has a value of 1. A value of 0 indicates it was not sent by a sendAndGet.

Parameters

vmsg	pointer to message
getRequest	integer pointer to be filled in with 1 if message sent by a sendAndGet and 0 otherwise

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetGetResponse	(	const void *	vmsg,
		int *	getResponse
	)

This routine gets the "get response" field of a message. The "get reponse" field indicates the message is a response to a message sent by a sendAndGet call, if it has a value of 1. A value of 0 indicates it is not a response to a sendAndGet.

Parameters

vmsg	pointer to message
getResponse	integer pointer to be filled in 1 if message is a response to a sendAndGet and 0 otherwise

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetHistoryLengthMax	(	const void *	vmsg,
		int *	len
	)

This routine gets the maximum number of entries this message keeps of its history of various parameters (sender's name, host, time).

Parameters

vmsg	pointer to message
len	integer pointer to be filled inwith max number of entries this message keeps of its history of various parameters

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetInfo	(	void *	domainId,
		const char *	command,
		char **	string
	)

This routine does general I/O and returns a string for each string argument.

Parameters

domainId	id of the domain connection
command	command whose value determines what is returned in string arg
string	pointer which gets filled in with a return string (may be NULL)

Returns: CMSG_OK if successful; CMSG_NOT_IMPLEMENTED this routine is not implemented

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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 cMsgGetName	(	void *	domainId,
		char **	name
	)

This routine gets the client name used in a cMsg connection. If successful, this routine will return a pointer to char inside the system structure. The user may NOT write to this memory location!

Parameters

domainId	id of the domain connection
name	pointer to pointer filled with the name

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetNullGetResponse	(	const void *	vmsg,
		int *	nullGetResponse
	)

This routine gets the "NULL get response" field of a message. If it has a value of 1, the "NULL get response" field indicates that if the message is a response to a message sent by a sendAndGet call, when sent it will be received as a NULL pointer - not a message. Any other value indicates it is not a null get response to a sendAndGet.

Parameters

vmsg	pointer to message
nullGetResponse	integer pointer to be filled in with 1 if message is a NULL response to a sendAndGet and 0 otherwise

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetPayloadText	(	const void *	vmsg,
		const char **	payloadText
	)

This routine gets the payload text of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
payloadText	pointer to pointer filled with message's payload text

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReceiver	(	const void *	vmsg,
		const char **	receiver
	)

This routine gets the receiver of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
receiver	pointer to pointer filled with message's receiver

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReceiverHost	(	const void *	vmsg,
		const char **	receiverHost
	)

This routine gets the host of the receiver of a message. This field is NULL for a newly created message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
receiverHost	pointer to pointer filled with host of the message receiver

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReceiverTime	(	const void *	vmsg,
		struct timespec *	receiverTime
	)

This routine gets the time a message was received (in seconds since midnight GMT, Jan 1st, 1970).

Parameters

vmsg	pointer to message
receiverTime	pointer to be filled with time message was received

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReceiveState	(	void *	domainId,
		int *	receiveState
	)

This routine gets the message receiving state of a cMsg connection. If receiveState gets filled with a one, all messages sent to the client will be received and sent to appropriate callbacks . Anything else (zero in this case), indicates no messages will be received or sent to callbacks.

Parameters

domainId	id of the domain connection
receiveState	integer pointer to be filled in with the receive state

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReliableSend	(	void *	vmsg,
		int *	boolean
	)

This routine gets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).

Parameters

vmsg	pointer to message
boolean	int pointer to be filled with 1 if true (TCP), else 0 (UDP)

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSender	(	const void *	vmsg,
		const char **	sender
	)

This routine gets the sender of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
sender	pointer to pointer filled with message's sender

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSenderHost	(	const void *	vmsg,
		const char **	senderHost
	)

This routine gets the host of the sender of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
senderHost	pointer to pointer filled with host of the message sender

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSenderTime	(	const void *	vmsg,
		struct timespec *	senderTime
	)

This routine gets the time a message was last sent (in seconds since midnight GMT, Jan 1st, 1970).

Parameters

vmsg	pointer to message
senderTime	pointer to be filled with time message was last sent

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetServerHost	(	void *	domainId,
		const char **	ipAddress
	)

This routine gets the IP address (in dotted-decimal form) that the client used to make the network connection to itsserver. Do NOT write into or free the returned char pointer.

Parameters

domainId	id of the domain connection
ipAddress	pointer filled in with server IP address

Returns: CMSG_OK if successful; CMSG_NOT_IMPLEMENTED if not implemented in the given domain; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgGetServerPort	(	void *	domainId,
		int *	port
	)

This routine gets the port that the client used to make the network connection to its server.

Parameters

domainId	id of the domain connection
port	pointer filled in with server TCP port

Returns: CMSG_OK if successful; CMSG_NOT_IMPLEMENTED if not implemented in the given domain; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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 cMsgGetSubject	(	const void *	vmsg,
		const char **	subject
	)

This routine gets the subject of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
subject	pointer to pointer filled with message's subject

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSubscriptionCueSize	(	const void *	vmsg,
		int *	size
	)

This routine gets the cue size of a callback and is valid only when used in a callback on the message given in the callback argument.

Parameters

vmsg	pointer to message
size	pointer which gets filled with a callback's cue size or -1 if no information is available

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSubscriptionDomain	(	const void *	vmsg,
		const char **	domain
	)

This routine gets the domain a subscription is running in and is valid only when used in a callback on the message given in the callback argument. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
domain	pointer to pointer filled with a subscription's domain or NULL if no information is available

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSubscriptionSubject	(	const void *	vmsg,
		const char **	subject
	)

This routine gets the subject a subscription is using and is valid only when used in a callback on the message given in the callback argument. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
subject	pointer to pointer filled with a subscription's subject or NULL if no information is available

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSubscriptionType	(	const void *	vmsg,
		const char **	type
	)

This routine gets the type a subscription is using and is valid only when used in a callback on the message given in the callback argument. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
type	pointer to pointer filled with a subscription's type or NULL if no information is available

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetSubscriptionUDL	(	const void *	vmsg,
		const char **	udl
	)

This routine gets the udl of a subscription's connection and is valid only when used in a callback on the message given in the callback argument. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
udl	pointer to pointer filled with the udl of a subscription's connection or NULL if no information is available

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

This routine gets the text of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
text	pointer to pointer filled with a message's text

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetType	(	const void *	vmsg,
		const char **	type
	)

This routine gets the type of a message. If successful, this routine will return a pointer to char inside the message structure. The user may NOT write to this memory location!

Parameters

vmsg	pointer to message
type	pointer to pointer filled with message's type

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetUDL	(	void *	domainId,
		char **	udl
	)

This routine gets the UDL used to establish a cMsg connection. If successful, this routine will return a pointer to char inside the system structure. The user may NOT write to this memory location!

Parameters

domainId	id of the domain connection
udl	pointer to pointer filled with the UDL

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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 cMsgGetUserInt	(	const void *	vmsg,
		int *	userInt
	)

This routine gets a message's user-defined integer.

Parameters

vmsg	pointer to message
userInt	integer pointer to be filled with message's user-defined integer

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetUserTime	(	const void *	vmsg,
		struct timespec *	userTime
	)

This routine gets a message's user-defined time (in seconds since midnight GMT, Jan 1st, 1970).

Parameters

vmsg	pointer to message
userTime	time_t pointer to be filled with message's user-defined time

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetVersion	(	const void *	vmsg,
		int *	version
	)

This routine gets the cMsg major version number of a message.

Parameters

vmsg	pointer to message
version	integer pointer to be filled in with cMsg major version

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

References CMSG_BAD_ARGUMENT, 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().

int cMsgInitMessage ( void * vmsg )

This routine initializes a message. It frees all allocated memory, sets all strings to NULL, and sets all numeric values to their default state.

Parameters

vmsg	pointer to message structure being initialized

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if msg is NULL

References CMSG_OK.

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

int cMsgMonitor	(	void *	domainId,
		const char *	command,
		void **	replyMsg
	)

This method is a synchronous call to receive a message containing monitoring data which describes the state of the cMsg domain the user is connected to. The time is data was sent can be obtained by calling cMsgGetSenderTime. The monitoring data in xml format can be obtained by calling cMsgGetText.

Parameters

domainId	domain connection id
command	string to monitor data collecting routine
replyMsg	message received from the domain containing monitor data

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgNeedToSwap	(	const void *	vmsg,
		int *	swap
	)

This method specifies whether the endian value of the byte array is the same value as the local host. If not, a 1 is returned indicating that the data needs to be swapped. If so, a 0 is returned indicating that no swap is needed.

Parameters

vmsg	pointer to message
swap	int pointer to be filled with 1 if byte array needs swapping, else 0

Returns: CMSG_OK if successful; CMSG_ERROR if local endianness is unknown; CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ERROR, and CMSG_OK.

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 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

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 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 cMsgPayloadToString	(	const void *	vmsg,
		char **	string,
		int	binary,
		int	compact,
		int	noSystemFields
	)

This routine converts the message payload to an XML string.

Parameters

vmsg	pointer to message
string	is pointer to char* that will hold the malloc'd string
binary	includes binary as ASCII if true, else binary is ignored
compact	if true (!=0), do not include attributes with null or default integer values
noSystemFields	if true (!=0), do not include system (metadata) payload fields

Returns: CMSG_OK if successful; CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count; CMSG_BAD_ARGUMENT if message is NULL; CMSG_OUT_OF_MEMORY if out of 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().

char* cMsgPerror ( int error )

This routine returns a string describing the given error condition. It can also print out that same string with printf if the debug level is set to CMSG_DEBUG_ERROR or CMSG_DEBUG_SEVERE by cMsgSetDebugLevel(). The returned string is a static char array. This means it is not thread-safe and will be overwritten on subsequent calls.

Parameters

error error condition

Returns: error string

References CMSG_ABORT, CMSG_ALREADY_EXISTS, CMSG_ALREADY_INIT, CMSG_BAD_ARGUMENT, CMSG_BAD_DOMAIN_ID, CMSG_BAD_DOMAIN_TYPE, CMSG_BAD_FORMAT, CMSG_BAD_MESSAGE, CMSG_DEBUG_ERROR, CMSG_DIFFERENT_VERSION, CMSG_ERROR, CMSG_ILLEGAL_MSGTYPE, CMSG_LIMIT_EXCEEDED, CMSG_LOST_CONNECTION, CMSG_NETWORK_ERROR, CMSG_NO_CLASS_FOUND, CMSG_NOT_IMPLEMENTED, CMSG_NOT_INITIALIZED, CMSG_OK, CMSG_OUT_OF_MEMORY, CMSG_OUT_OF_RANGE, CMSG_PEND_ERROR, CMSG_SERVER_DIED, CMSG_SOCKET_ERROR, CMSG_TIMEOUT, CMSG_WRONG_DOMAIN_TYPE, CMSG_WRONG_PASSWORD, and cMsgDebug.

int cMsgReceiveStart ( void * domainId )

This routine enables the receiving of messages and delivery to callbacks. The receiving of messages is disabled by default and must be explicitly enabled.

Parameters

domainId domain connection id

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgReceiveStart

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

int cMsgReceiveStop ( void * domainId )

This routine disables the receiving of messages and delivery to callbacks. The receiving of messages is disabled by default. This routine only has an effect when cMsgReceiveStart() was previously called.

Parameters

domainId domain connection id

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgReceiveStop

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

int cMsgReconnect ( void * domainId )

This routine tries to reconnect to the server if a connection is broken. The domainId argument is created by first calling cMsgConnect() and establishing a connection to a cMsg server

Parameters

domainId domain connection id

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if domainId is bad or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgReconnect

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgResetByteArrayLength ( void * vmsg )

This routine resets the region-of-interest length of a message's byte array to its total length or zero if there is none.

Parameters

vmsg	pointer to message

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSend	(	void *	domainId,
		void *	msg
	)

This routine sends a msg to the specified domain server. It is completely asynchronous and never blocks. The domain may require cMsgFlush() to be called to force delivery. The domainId argument is created by calling cMsgConnect() and establishing a connection to a cMsg server. The message to be sent may be created by calling cMsgCreateMessage(), cMsgCreateNewMessage(), or cMsgCopyMessage().

Parameters

domainId	domain connection id
msg	pointer to a message structure

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSend

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSendAndGet	(	void *	domainId,
		void *	sendMsg,
		const struct timespec *	timeout,
		void **	replyMsg
	)

This routine gets one message from another cMsg client by sending out an initial message to that responder. It is a synchronous routine that fails when no reply is received with the given timeout. This function can be thought of as a peer-to-peer exchange of messages. One message is sent to all listeners. The first responder to the initial message will have its single response message sent back to the original sender. In the cMsg domain, if there are no subscribers to get the sent message, this routine returns CMSG_OK, but with a NULL message.

Parameters

domainId	domain connection id
sendMsg	messages to send to all listeners
timeout	amount of time to wait for the response message
replyMsg	message received from the responder; may be NULL

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSetByteArray	(	void *	vmsg,
		char *	array,
		int	length
	)

This routine sets a message's byte array by copying "length" number of bytes into a newly allocated array. The offset is reset to 0 while the length is set to the given value. Any pre-existing byte array memory is freed if it was copied into the given message. If the given array is null, the message's byte array is set to null and both offset & length are set to 0.

Parameters

vmsg	pointer to message
array	byte array
length	number of bytes in array

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL, or length < 0; CMSG_OUT_OF_MEMORY if out of memory

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_MEMORY.

int cMsgSetByteArrayEndian	(	void *	vmsg,
		int	endian
	)

This routine sets the endianness of the byte array data. Valid values are:

Parameters

vmsg	pointer to message
endian	byte array's endianness

Returns: CMSG_OK if successful; CMSG_ERROR if local endianness is unknown; CMSG_BAD_ARGUMENT if message is NULL, or endian is not equal to either CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, CMSG_ENDIAN_NOTLOCAL, or CMSG_ENDIAN_SWITCH

References CMSG_BAD_ARGUMENT, CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, CMSG_ENDIAN_NOTLOCAL, CMSG_ENDIAN_SWITCH, CMSG_ERROR, and CMSG_OK.

int cMsgSetByteArrayLength	(	void *	vmsg,
		int	length
	)

This routine sets the region-of-interest length of a message's byte array. This may be smaller than the full length of the array if the user is only interested in a portion of the array. If the byte array is null, all non-negative values are accepted.

Parameters

vmsg	pointer to message
length	byte array's length (in bytes)

Returns: CMSG_OK if successful; CMSG_OUT_OF_RANGE if offset + length is beyond array bounds; CMSG_BAD_ARGUMENT if message is NULL or length < 0

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_RANGE.

int cMsgSetByteArrayNoCopy	(	void *	vmsg,
		char *	array,
		int	length
	)

This routine sets a message's byte array by copying the array arg pointer but NOT the data pointed to. The length arg sets the total length of the array in bytes. Any pre-existing byte array data is freed if it was copied into the given message. If the given array is null, the message's byte array is set to null and both offset & length are set to 0.

Parameters

vmsg	pointer to message
array	byte array
length	number of bytes in array

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL or length is < 0

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetByteArrayOffset	(	void *	vmsg,
		int	offset
	)

This routine sets the region-of-interest offset of a message's byte array. This may be non-zero if the user is only interested in a portion of the array. If the byte array is null, all non-negative values are accepted.

Parameters

vmsg	pointer to message
offset	byte array's offset index

Returns: CMSG_OK if successful; CMSG_OUT_OF_RANGE if offset + length is beyond array bounds; CMSG_BAD_ARGUMENT if message is NULL or offset < 0

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_RANGE.

int cMsgSetDebugLevel ( int level )

This routine sets the level of debug output. The argument should be one of:

Parameters

level debug level desired

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if debug level is bad

References CMSG_BAD_ARGUMENT, CMSG_DEBUG_ERROR, CMSG_DEBUG_INFO, CMSG_DEBUG_NONE, CMSG_DEBUG_SEVERE, CMSG_DEBUG_WARN, CMSG_OK, and cMsgDebug.

int cMsgSetGetResponse	(	void *	vmsg,
		int	getResponse
	)

This routine sets the "get response" field of a message. The "get reponse" field indicates the message is a response to a message sent by a sendAndGet call, if it has a value of 1. Any other value indicates it is not a response to a sendAndGet.

Parameters

vmsg	pointer to message
getResponse	set to 1 if message is a response to a sendAndGet, anything else otherwise

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message argument is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetHistoryLengthMax	(	void *	vmsg,
		int	len
	)

This routine sets the maximum number of entries this message keeps of its history of various parameters (sender's name, host, time).

Parameters

vmsg	pointer to message
len	max number of entries this message keeps of its history of various parameters

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message argument is NULL; CMSG_OUT_OF_RANGE if len < 0 or > CMSG_HISTORY_LENGTH_ABS_MAX

References CMSG_OK, and CMSG_OUT_OF_RANGE.

int cMsgSetNullGetResponse	(	void *	vmsg,
		int	nullGetResponse
	)

This routine sets the "null get response" field of a message. If it has a value of 1, the "null get response" field indicates that if the message is a response to a message sent by a sendAndGet call, when sent it will be received as a NULL pointer - not a message. Any other value indicates it is not a null get response to a sendAndGet.

Parameters

vmsg	pointer to message
nullGetResponse	set to 1 if message is a null get response to a sendAndGet, anything else otherwise

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message argument is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetReliableSend	(	void *	vmsg,
		int	boolean
	)

This routine sets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).

Parameters

vmsg	pointer to message
boolean	0 if false (use UDP), anything else true (use TCP)

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetShutdownHandler	(	void *	domainId,
		cMsgShutdownHandler *	handler,
		void *	userArg
	)

This routine sets the shutdown handler function.

Parameters

domainId	domain connection id
handler	shutdown handler function
userArg	argument to shutdown handler

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSetSubject	(	void *	vmsg,
		const char *	subject
	)

This routine sets the subject of a message.

Parameters

vmsg	pointer to message
subject	message subject

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

This routine sets the text of a message.

Parameters

vmsg	pointer to message
text	message text

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetType	(	void *	vmsg,
		const char *	type
	)

This routine sets the type of a message.

Parameters

vmsg	pointer to message
type	message type

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetUDL	(	void *	domainId,
		const char *	UDL
	)

This routine resets the UDL (may be a semicolon separated list of single UDLs). If a reconnect is done, the new UDLs will be used in the connection(s).

Parameters

domainId	domain connection id
UDL	new UDL

Returns: CMSG_OK if successful; CMSG_ERROR if not successful reading file for configFile domain UDL; CMSG_BAD_FORMAT if configFile domain file contains UDL of configFile domain or if one of the UDLs is not in the correct format; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or UDL arg has illegal characters or is NULL; CMSG_OUT_OF_MEMORY if out of memory; CMSG_WRONG_DOMAIN_TYPE one of the domains is of the wrong type; any errors returned from the actual domain dependent implemenation of cMsgSetUDL

References CMSG_BAD_ARGUMENT, CMSG_OK, CMSG_WRONG_DOMAIN_TYPE, and LOCAL_ARRAY_SIZE.

int cMsgSetUserInt	(	void *	vmsg,
		int	userInt
	)

This routine sets a message's user-defined integer.

Parameters

vmsg	pointer to message
userInt	message's user-defined integer

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetUserTime	(	void *	vmsg,
		const struct timespec *	userTime
	)

This routine sets a message's user-defined time (in seconds since midnight GMT, Jan 1st, 1970).

Parameters

vmsg	pointer to message
userTime	message's user-defined time

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgShutdownClients	(	void *	domainId,
		const char *	client,
		int	flag
	)

Method to shutdown the given clients.

Parameters

domainId	domain connection id
client	client(s) to be shutdown
flag	flag describing the mode of shutdown: 0 to not include self, CMSG_SHUTDOWN_INCLUDE_ME to include self in shutdown.

Returns: CMSG_OK if successful; CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement shutdown; CMSG_NETWORK_ERROR if error in communicating with the server; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or flag argument improper value; any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, CMSG_SHUTDOWN_INCLUDE_ME, and LOCAL_ARRAY_SIZE.

int cMsgShutdownServers	(	void *	domainId,
		const char *	server,
		int	flag
	)

Method to shutdown the given servers.

Parameters

domainId	domain connection id
server	server(s) to be shutdown
flag	flag describing the mode of shutdown: 0 to not include self, CMSG_SHUTDOWN_INCLUDE_ME to include self in shutdown.

Returns: CMSG_OK if successful; CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement shutdown; CMSG_NETWORK_ERROR if error in communicating with the server; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or flag argument improper value; any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, CMSG_SHUTDOWN_INCLUDE_ME, and LOCAL_ARRAY_SIZE.

int cMsgSubscribe	(	void *	domainId,
		const char *	subject,
		const char *	type,
		cMsgCallbackFunc *	callback,
		void *	userArg,
		cMsgSubscribeConfig *	config,
		void **	handle
	)

This routine subscribes to messages of the given subject and type. When a message is received, the given callback is passed the message pointer and the userArg pointer and then is executed. A configuration structure is given to determine the behavior of the callback. Only 1 subscription for a specific combination of subject, type, callback and userArg is allowed.

Parameters

domainId	domain connection id
subject	subject of messages subscribed to
type	type of messages subscribed to
callback	pointer to callback to be executed on receipt of message
userArg	user-specified pointer to be passed to the callback
config	pointer to callback configuration structure
handle	pointer to handle (void pointer) to be used for unsubscribing from this subscription

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSubscribe

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscribeAndGet	(	void *	domainId,
		const char *	subject,
		const char *	type,
		const struct timespec *	timeout,
		void **	replyMsg
	)

This routine gets one message from a one-time subscription to the given subject and type.

Parameters

domainId	domain connection id
subject	subject of message subscribed to
type	type of message subscribed to
timeout	amount of time to wait for the message
replyMsg	message received

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

cMsgSubscribeConfig* cMsgSubscribeConfigCreate ( void )

This routine creates a structure of configuration information used to determine the behavior of a cMsgSubscribe()'s callback. The configuration is filled with default values. Each aspect of the configuration may be modified by setter and getter functions. The defaults are:

maximum messages to cue for callback is 10000
no messages may be skipped
calls to the callback function must be serialized
may skip up to 2000 messages at once if skipping is enabled
maximum number of threads when parallelizing calls to the callback function is 100
enough worker threads are started so that there are at most 150 unprocessed messages for each thread

Note that this routine allocates memory and cMsgSubscribeConfigDestroy() must be called to free it.

Returns: NULL if no memory available; pointer to configuration if successful

int cMsgSubscribeConfigDestroy ( cMsgSubscribeConfig * config )

This routine frees the memory associated with a configuration created by cMsgSubscribeConfigCreate();

Parameters

config pointer to configuration

Returns: CMSG_OK

References CMSG_OK.

int cMsgSubscribeGetMaxCueSize	(	cMsgSubscribeConfig *	config,
		int *	size
	)

This routine gets a subscribe configuration's maximum message cue size. Messages are kept in the cue until they can be processed by the callback function.

Parameters

config	pointer to configuration
size	integer pointer to be filled with configuration's maximum cue size

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMaxThreads	(	cMsgSubscribeConfig *	config,
		int *	threads
	)

This routine gets the maximum number of threads a parallelized subscribe's callback can run at once. This setting is only used if cMsgSubscribeSetMustSerialize() was called with an argument of 0.

Parameters

config	pointer to configuration
threads	integer pointer to be filled with the maximum number of threads a parallelized subscribe's callback can run at once

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMaySkip	(	cMsgSubscribeConfig *	config,
		int *	maySkip
	)

This routine gets whether messages may be skipped over (deleted) if too many messages are piling up in the cue. The maximum number of messages skipped at once is determined by cMsgSubscribeSetSkipSize().

Parameters

config	pointer to configuration
maySkip	integer pointer to be filled with 0 if messages may NOT be skipped (deleted), or anything else otherwise

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMessagesPerThread	(	cMsgSubscribeConfig *	config,
		int *	mpt
	)

This routine gets the maximum number of unprocessed messages per thread before a new thread is started, if a callback is parallelized (cMsgSubscribeSetMustSerialize() set to 0).

Parameters

config	pointer to configuration
mpt	integer pointer to be filled with the maximum number of unprocessed messages per thread before starting another thread

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMustSerialize	(	cMsgSubscribeConfig *	config,
		int *	serialize
	)

This routine gets whether a subscribe's callback must be run serially (in one thread), or may be parallelized (run simultaneously in more than one thread) if more than 1 message is waiting in the cue.

Parameters

config	pointer to configuration
serialize	integer pointer to be filled with 0 if callback may be parallelized, or anything else if callback must be serialized

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetSkipSize	(	cMsgSubscribeConfig *	config,
		int *	size
	)

This routine gets the number of messages to skip over (delete) if too many messages are piling up in the cue. Messages are only skipped if cMsgSubscribeSetMaySkip() sets the configuration to do so.

Parameters

config	pointer to configuration
size	integer pointer to be filled with the number of messages to skip (delete)

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetStackSize	(	cMsgSubscribeConfig *	config,
		size_t *	size
	)

This routine gets the stack size in bytes of the subscription thread. By default the stack size is unspecified (returns 0).

Parameters

config	pointer to configuration
size	pointer to be filled with the stack size in bytes of subscription thread

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeSetMaxCueSize	(	cMsgSubscribeConfig *	config,
		int	size
	)

This routine sets a subscribe configuration's maximum message cue size. Messages are kept in the cue until they can be processed by the callback function.

Parameters

config	pointer to configuration
size	maximum cue size

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL or size < 1

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMaxThreads	(	cMsgSubscribeConfig *	config,
		int	threads
	)

This routine sets the maximum number of threads a parallelized subscribe's callback can run at once. This setting is only used if cMsgSubscribeSetMustSerialize() was called with an argument of 0.

Parameters

config	pointer to configuration
threads	the maximum number of threads a parallelized subscribe's callback can run at once

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL or threads < 0

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMaySkip	(	cMsgSubscribeConfig *	config,
		int	maySkip
	)

This routine sets whether messages may be skipped over (deleted) if too many messages are piling up in the cue. The maximum number of messages skipped at once is determined by cMsgSubscribeSetSkipSize().

Parameters

config	pointer to configuration
maySkip	set to 0 if messages may NOT be skipped, set to anything else otherwise

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMessagesPerThread	(	cMsgSubscribeConfig *	config,
		int	mpt
	)

This routine sets the maximum number of unprocessed messages per thread before a new thread is started, if a callback is parallelized (cMsgSubscribeSetMustSerialize() set to 0).

Parameters

config	pointer to configuration
mpt	set to maximum number of unprocessed messages per thread before starting another thread

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL or mpt < 1

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMustSerialize	(	cMsgSubscribeConfig *	config,
		int	serialize
	)

This routine sets whether a subscribe's callback must be run serially (in one thread), or may be parallelized (run simultaneously in more than one thread) if more than 1 message is waiting in the cue.

Parameters

config	pointer to configuration
serialize	set to 0 if callback may be parallelized, or set to anything else if callback must be serialized

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetSkipSize	(	cMsgSubscribeConfig *	config,
		int	size
	)

This routine sets the number of messages to skip over (delete) if too many messages are piling up in the cue. Messages are only skipped if cMsgSubscribeSetMaySkip() sets the configuration to do so.

Parameters

config	pointer to configuration
size	number of messages to skip (delete)

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL or size < 0

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetStackSize	(	cMsgSubscribeConfig *	config,
		size_t	size
	)

This routine sets the stack size in bytes of the subscription thread. By default the stack size is unspecified.

Parameters

config	pointer to configuration
size	stack size in bytes of subscription thread

Returns: CMSG_OK if successful; CMSG_NOT_INITIALIZED if configuration was not initialized; CMSG_BAD_ARGUMENT if configuration is NULL or size < 1 byte

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscriptionMessagesTotal	(	void *	domainId,
		void *	handle,
		int *	total
	)

This routine returns the total number of messages sent to a subscription callback.

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe
total	int pointer filled in with total number of messages sent to a subscription callback

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionPause	(	void *	domainId,
		void *	handle
	)

This routine pauses the delivery of messages to the given subscription callback.

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement this function; any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionQueueClear	(	void *	domainId,
		void *	handle
	)

This routine clears a subscription callback's queue of all messages.

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if the id/handle is bad or handle is NULL

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionQueueCount	(	void *	domainId,
		void *	handle,
		int *	count
	)

This routine returns the number of messages currently in a subscription callback's queue.

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe
count	int pointer filled in with number of messages in subscription callback queue

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionQueueIsFull	(	void *	domainId,
		void *	handle,
		int *	full
	)

This routine returns true(1) if a subscription callback's queue is full, else false(0).

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe
full	int pointer filled in with 1 if subscription callback queue full, else 0

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionResume	(	void *	domainId,
		void *	handle
	)

This routine resumes the delivery of messages to the given subscription callback.

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement this function; any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSyncSend	(	void *	domainId,
		void *	msg,
		const struct timespec *	timeout,
		int *	response
	)

This routine sends a msg to the specified domain server and receives a response. It is a synchronous routine and as a result blocks until it receives a status integer from the cMsg server. The domainId argument is created by calling cMsgConnect() and establishing a connection to a cMsg server. The message to be sent may be created by calling cMsgCreateMessage(), cMsgCreateNewMessage(), or cMsgCopyMessage().

Parameters

domainId	domain connection id
msg	pointer to a message structure
timeout	amount of time to wait for the response
response	integer pointer that gets filled with the response

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgSyncSend

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgToString	(	const void *	vmsg,
		char **	string
	)

This routine converts the message to an XML string. Everything is displayed including binary.

Parameters

vmsg	pointer to message
string	is pointer to char* that will hold the malloc'd string

Returns: CMSG_OK if successful; CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count; CMSG_BAD_ARGUMENT if message is NULL; CMSG_OUT_OF_MEMORY if out of memory

int cMsgToString2	(	const void *	vmsg,
		char **	string,
		int	binary,
		int	compact,
		int	noSystemFields
	)

This routine converts the message to an XML string.

Parameters

vmsg	pointer to message
string	is pointer to char* that will hold the malloc'd string
binary	includes binary as ASCII if true, else binary is ignored
compact	if true (!=0), do not include attributes with null or default integer values
noSystemFields	if true (!=0), do not include system (metadata) payload fields

Returns: CMSG_OK if successful; CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count; CMSG_BAD_ARGUMENT if message is NULL; CMSG_OUT_OF_MEMORY if out of memory

void cMsgTrim ( char * s )

Routine to trim white space from front and back of given string. Changes made to argument string in place.

Parameters

s	string to be trimmed

void cMsgTrimChar	(	char *	s,
		char	trimChar
	)

Routine to trim a given character from front and back of given string. Changes made to argument string in place.

Parameters

s	string to be trimmed
trimChar	character to be trimmed

void cMsgTrimDoubleChars	(	char *	s,
		char	trimChar
	)

Routine to eliminate contiguous occurrences of a given character in given string. Changes made to argument string in place.

Parameters

s	string to be trimmed
trimChar	character to be trimmed

int cMsgUnSubscribe	(	void *	domainId,
		void *	handle
	)

This routine unsubscribes to messages of the given handle (which represents a given subject, type, callback, and user argument).

Parameters

domainId	domain connection id
handle	void pointer obtained from cMsgSubscribe

Returns: CMSG_OK if successful; CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called; any errors returned from the actual domain dependent implemenation of cMsgUnSubscribe

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgWasSent	(	const void *	vmsg,
		int *	hasBeenSent
	)

This routine returns whether a message has been sent over the wire or not.

Parameters

vmsg	pointer to message
hasBeenSent	pointer which gets filled with 1 if msg has been sent, else 0

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

References CMSG_BAD_ARGUMENT, and CMSG_OK.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation