cMsg.h File Reference


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.

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

Go to the source code of this file.

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 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 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)
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 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 cMsgGetByteArrayLength (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 cMsgGetByteArray (const void *vmsg, char **array)
int cMsgSetByteArrayAndLimits (void *vmsg, char *array, int offset, int length)
int cMsgCopyByteArray (void *vmsg, char *array, int offset, int length)
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 cMsgSetReliableSend (void *vmsg, int boolean)
int cMsgGetReliableSend (void *vmsg, int *boolean)
int cMsgToString (void *vmsg, char **string, int binary)
int cMsgAddSenderToHistory (void *vmsg, char *name)
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 cMsgPayloadWipeout (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 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 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)
int cMsgGetUDL (void *domainId, char **udl)
int cMsgGetName (void *domainId, char **name)
int cMsgGetDescription (void *domainId, char **description)
int cMsgGetConnectState (void *domainId, int *connectState)
int cMsgGetReceiveState (void *domainId, int *receiveState)
cMsgSubscribeConfigcMsgSubscribeConfigCreate (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)


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
isSystem if = 1 allows using names starting with "cmsg", else not
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 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

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

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

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

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

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

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

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

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

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

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

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

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
message 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 cMsgAddSenderToHistory void *  vmsg,
char *  name
 

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

Parameters:
name name of sender to add to the history of senders

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

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

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

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

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

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

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

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

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

any errors returned from the actual domain dependent implemenation of cMsgConnect

int cMsgCopyByteArray void *  vmsg,
char *  array,
int  offset,
int  length
 

This routine sets a message's byte array by copying the data into a newly allocated array using the given offset and length values. No existing byte array memory is freed. The offset is reset to zero while length is set to the given value.

Parameters:
vmsg pointer to message
array byte array
offset offset of index into array
length number of bytes in array
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if message or array is NULL, or length is negative

void* cMsgCopyMessage const void *  vmsg  ) 
 

This routine copies a message. Memory is allocated with this function and can be freed by cMsgFreeMessage(). Note that the copy of the byte array will only have byteArrayLength number of bytes. Since in C the original size of the array in unknown, a whole copy cannot be guaranteed unless the orginial message has its offset at zero and its length to be the total length of its 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

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

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

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

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

int cMsgDisconnect void **  domainId  ) 
 

This routine disconnects the client from the cMsg server.

Parameters:
domainId pointer to id of the domain connection
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId or the pointer it points to is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgDisconnect

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 character 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 character 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 id of the domain connection
timeout amount of time to wait for completion
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgFlush

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

int cMsgGetBinary const void *  vmsg,
const char *  name,
const char **  val,
int *  len,
int *  endian
 

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

Parameters:
vmsg pointer to message
name name of payload field
val pointer filled with field value
len 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

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

int cMsgGetByteArrayEndian const void *  vmsg,
int *  endian
 

This routine gets the endianness of the byte array data.

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

int cMsgGetByteArrayLength const void *  vmsg,
int *  length
 

This routine gets the 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

int cMsgGetByteArrayOffset const void *  vmsg,
int *  offset
 

This routine gets the 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

int cMsgGetConnectState void *  domainId,
int *  connectState
 

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 no connection to a cMsg server.

Parameters:
domainId id of the domain connection
connectState integer pointer to be filled in with the connection state
Returns:
CMSG_BAD_ARGUMENT if either arg is NULL

CMSG_OK if successful

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 id of the domain connection
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 domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

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

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

Parameters:
vmsg pointer to message

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

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

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

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.

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 or of improper value

CMSG_LIMIT_EXCEEDED if len < the number of items

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

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

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.

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

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

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

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

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 cMsgPayloadUpdateText const void *  vmsg  ) 
 

This routine creates a string representation of the whole compound payload in a form for sending over the network. It stores that string in the given message.

Parameters:
vmsg pointer to message
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if vmsg is NULL

CMSG_OUT_OF_MEMORY if no more memory

void cMsgPayloadWipeout void *  vmsg  ) 
 

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

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

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 id of the domain connection
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgReceiveStart

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 id of the domain connection
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgReceiveStop

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 id of the domain connection
msg pointer to a message structure
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSend

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.

Parameters:
domainId id of the domain connection
sendMsg messages to send to all listeners
timeout amount of time to wait for the response message
replyMsg message received from the responder
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

int cMsgSetByteArray void *  vmsg,
char *  array
 

This routine sets a message's byte array by setting the pointer and NOT copying the data.

Parameters:
vmsg pointer to message
array byte array
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if message is NULL

int cMsgSetByteArrayAndLimits void *  vmsg,
char *  array,
int  offset,
int  length
 

This routine sets a message's byte array by setting the pointer and NOT copying the data. It also sets the offset index into and length of the array.

Parameters:
vmsg pointer to message
array byte array
offset offset of index into array
length number of bytes in array
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if message is NULL or length is negative

int cMsgSetByteArrayEndian void *  vmsg,
int  endian
 

This routine sets the endianness of the byte array data.

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

int cMsgSetByteArrayLength void *  vmsg,
int  length
 

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

Parameters:
vmsg pointer to message
length byte array's length (in bytes)
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if message is NULL or length is negative

int cMsgSetByteArrayOffset void *  vmsg,
int  offset
 

This routine sets the offset of a message's byte array.

Parameters:
vmsg pointer to message
offset byte array's offset index
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if message is NULL

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

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

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

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

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

This routine sets the shutdown handler function.

Parameters:
domainId id of the domain connection
handler shutdown handler function
userArg argument to shutdown handler
Returns:
CMSG_OK if successful

any errors returned from the actual domain dependent implemenation of cMsgDisconnect

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

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

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

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

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

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

Method to shutdown the given clients.

Parameters:
domainId id of the domain connection
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 one of the arguments is bad

any errors returned from the actual domain dependent implemenation of cMsgDisconnect

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

Method to shutdown the given servers.

Parameters:
domainId id of the domain connection
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 one of the arguments is bad

any errors returned from the actual domain dependent implemenation of cMsgDisconnect

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 id of the domain connection
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 domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSubscribe

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 id of the domain connection
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 domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 id of the domain connection
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 domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgSyncSend

int cMsgToString void *  vmsg,
char **  string,
int  binary
 

This routine converts the message to a printable string. There is always a danger that the message could be changed in another thread as it is being transformed into XML. Since nothing is mutex protected here, that may lead to segmentation faults.

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
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 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 id of the domain connection
handle void pointer obtained from cMsgSubscribe
Returns:
CMSG_OK if successful

CMSG_BAD_ARGUMENT if domainId is NULL

CMSG_LOST_CONNECTION if no longer connected to domain

any errors returned from the actual domain dependent implemenation of cMsgUnSubscribe

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


Generated on Wed Feb 6 13:37:49 2008 for cMsg Messaging System by  doxygen 1.3.9.1