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(¶m2=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) |
cMsgSubscribeConfig * | cMsgSubscribeConfigCreate (void) |
int | cMsgSubscribeConfigDestroy (cMsgSubscribeConfig *config) |
int | cMsgSubscribeSetMaxCueSize (cMsgSubscribeConfig *config, int size) |
int | cMsgSubscribeGetMaxCueSize (cMsgSubscribeConfig *config, int *size) |
int | cMsgSubscribeSetSkipSize (cMsgSubscribeConfig *config, int size) |
int | cMsgSubscribeGetSkipSize (cMsgSubscribeConfig *config, int *size) |
int | cMsgSubscribeSetMaySkip (cMsgSubscribeConfig *config, int maySkip) |
int | cMsgSubscribeGetMaySkip (cMsgSubscribeConfig *config, int *maySkip) |
int | cMsgSubscribeSetMustSerialize (cMsgSubscribeConfig *config, int serialize) |
int | cMsgSubscribeGetMustSerialize (cMsgSubscribeConfig *config, int *serialize) |
int | cMsgSubscribeSetMaxThreads (cMsgSubscribeConfig *config, int threads) |
int | cMsgSubscribeGetMaxThreads (cMsgSubscribeConfig *config, int *threads) |
int | cMsgSubscribeSetMessagesPerThread (cMsgSubscribeConfig *config, int mpt) |
int | cMsgSubscribeGetMessagesPerThread (cMsgSubscribeConfig *config, int *mpt) |
int | cMsgSubscribeSetStackSize (cMsgSubscribeConfig *config, size_t size) |
int | cMsgSubscribeGetStackSize (cMsgSubscribeConfig *config, size_t *size) |
int | cMsgSetDebugLevel (int level) |
|
Callback function. |
|
Shutdown handler function. |
|
Subscribe configuration. |
|
This routine adds a named field of binary data to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, double field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, double array field to the compound payload of a message.
|
|
This routine adds a named, float field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, float array field to the compound payload of a message.
|
|
This routine adds a named, 16-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 16-bit, signed int array field to the compound payload of a message.
|
|
This routine adds a named, 32-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 32-bit, signed int array field to the compound payload of a message.
|
|
This routine adds a named, 64-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 64-bit, signed int array field to the compound payload of a message.
|
|
This routine adds a named, 8-bit, signed int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 8-bit, signed int array field to the compound payload of a message.
|
|
This routine adds a named cMsg message field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes. The string representation of the message is the same format as that used for a complete compound payload.
|
|
This routine adds a named field of an array of cMsg messages to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
Adds a name to the history of senders of this message (in the payload). This method only keeps cMsgMessage_t.historyLengthMax number of the most recent names. This method is reserved for system use only.
|
|
This routine adds a named string field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named string array field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 16-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 16-bit, unsigned int array field to the compound payload of a message.
|
|
This routine adds a named, 32-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 32-bit, unsigned int array field to the compound payload of a message.
|
|
This routine adds a named, 64-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 64-bit, unsigned int array field to the compound payload of a message.
|
|
This routine adds a named, 8-bit, unsigned int field to the compound payload of a message. Names may not begin with "cmsg" (case insensitive), be longer than CMSG_PAYLOAD_NAME_LEN, or contain white space or quotes.
|
|
This routine adds a named, 8-bit, unsigned int array field to the compound payload of a message.
|
|
This routine 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.
|
|
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.
|
|
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.
|
|
This routine creates a new, initialized message. Memory is allocated with this function and can be freed by cMsgFreeMessage().
|
|
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().
|
|
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().
|
|
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().
|
|
This routine disconnects the client from the cMsg server.
|
|
This routine returns a string representation of a double in the form of 16 hex chars of the IEEE754 representation. String points to internal static character array.
|
|
This routine returns a string representation of a float in the form of 8 hex chars of the IEEE754 representation. String points to internal static character array.
|
|
This routine 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.
|
|
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.
|
|
This routine returns the value of the given field as a binary array if it exists. Do NOT write into the returned pointer's memory location.
|
|
This routine gets a message's byte array.
|
|
This routine gets the endianness of the byte array data.
|
|
This routine gets the length of a message's byte array.
|
|
This routine gets the offset of a message's byte array.
|
|
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.
|
|
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!
|
|
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!
|
|
This routine returns the double given field if it exists.
|
|
This routine returns the double array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a float of the given field if it exists.
|
|
This routine returns the float array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine 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.
|
|
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.
|
|
This routine returns a 16 bit, signed integer given field if it exists.
|
|
This routine returns a 16 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 32 bit, signed integer given field if it exists.
|
|
This routine returns a 32 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 64 bit, signed integer given field if it exists.
|
|
This routine returns a 64 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns an 8 bit, signed integer given field if it exists.
|
|
This routine returns an 8 bit, signed integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns the value of the given field as a cMsg message if it exists. Do NOT write into the returned pointer's memory location.
|
|
This routine returns the value of the given field as an array of cMsg messages if it exists. Do NOT write into the returned pointer's memory location.
|
|
This routine 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!
|
|
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.
|
|
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!
|
|
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!
|
|
This routine gets the time a message was received (in seconds since midnight GMT, Jan 1st, 1970).
|
|
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.
|
|
This routine gets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
|
|
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!
|
|
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!
|
|
This routine gets the time a message was last sent (in seconds since midnight GMT, Jan 1st, 1970).
|
|
This routine returns the value of the given field as a string if it exists. Do NOT write into the returned pointer's memory location.
|
|
This routine returns the string array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine 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!
|
|
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.
|
|
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!
|
|
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!
|
|
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!
|
|
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!
|
|
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!
|
|
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!
|
|
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!
|
|
This routine returns a 16 bit, unsigned integer given field if it exists.
|
|
This routine returns a 16 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 32 bit, unsigned integer given field if it exists.
|
|
This routine returns a 32 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns a 64 bit, unsigned integer given field if it exists.
|
|
This routine returns a 64 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine returns an 8 bit, unsigned integer given field if it exists.
|
|
This routine returns an 8 bit, unsigned integer array of the given field if it exists. Do NOT write into the returned array's memory location.
|
|
This routine gets a message's user-defined integer.
|
|
This routine gets a message's user-defined time (in seconds since midnight GMT, Jan 1st, 1970).
|
|
This routine gets the cMsg major version number of a message.
|
|
This routine returns whether a message has a compound payload or not. It returns 0 if there is no payload and the number of items in the payload is there is one.
|
|
This routine initializes a message. It frees all allocated memory, sets all strings to NULL, and sets all numeric values to their default state.
|
|
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.
|
|
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.
|
|
This routine removes all the user-added items in the given message's payload. The payload may still contain fields added by the cMsg system. If there are no items left in the payload, this routine is equivalent to cMsgPayloadWipeout.
|
|
This routine checks to see if a name is already in use by an existing field in the payload.
|
|
This routine copies the payload from one message to another. The original payload of the "to" message is overwritten.
|
|
This routine returns a description of the given field name. Do NOT write to this location in memory.
|
|
This routine fills 2 arrays provided by the caller. One contains all the names of the items in the payload, and the second contains the corresponding data types of those items. Each element of the array of characters points to a string in the message itself which must not be freed or written to.
|
|
This routine returns the number of payload items a message has.
|
|
This routine returns a pointer to the string representation of the given field. Do NOT write to this location in memory.
|
|
This routine returns 2 arrays. One contains all the names of the items in the payload, and the second contains the corresponding data types of those items. It also returns the length of both arrays. Both arrays use allocated memory and must be freed by the caller. Each element of the array of characters points to a string in the message itself which must not be freed or written to.
|
|
This routine returns the type of data associated with the payload field given by the name argument. The returned type may have the following values:
|
|
This routine prints out the message payload in a readable form.
|
|
This routine removes the named field if it exists.
|
|
This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the hidden system fields and payload of the message. This overwrites any existing system fields and payload.
|
|
This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the standard message payload. All system information is ignored. This overwrites any existing payload and skips over any fields with names starting with "cMsg" (as they are reserved for system use).
|
|
This routine takes a pointer to a string representation of the whole compound payload, including the system (hidden) fields of the message, as it gets sent over the network and converts it into the hidden system fields of the message. All non-system information is ignored. This overwrites any existing system fields.
|
|
This routine creates a string representation of the whole compound payload in a form for sending over the network. It stores that string in the given message.
|
|
This routine frees the allocated memory of the given message's entire payload and then initializes the payload components of the message.
|
|
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.
|
|
This routine enables the receiving of messages and delivery to callbacks. The receiving of messages is disabled by default and must be explicitly enabled.
|
|
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.
|
|
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().
|
|
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.
|
|
This routine sets a message's byte array by setting the pointer and NOT copying the data.
|
|
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.
|
|
This routine sets the endianness of the byte array data.
|
|
This routine sets the length of a message's byte array.
|
|
This routine sets the offset of a message's byte array.
|
|
This routine sets the level of debug output. The argument should be one of:
|
|
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.
|
|
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.
|
|
This routine sets whether the send will be reliable (default, TCP) or will be allowed to be unreliable (UDP).
|
|
This routine sets the shutdown handler function.
|
|
This routine sets the subject of a message.
|
|
This routine sets the text of a message.
|
|
This routine sets the type of a message.
|
|
This routine sets a message's user-defined integer.
|
|
This routine sets a message's user-defined time (in seconds since midnight GMT, Jan 1st, 1970).
|
|
Method to shutdown the given clients.
|
|
Method to shutdown the given servers.
|
|
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.
|
|
This routine gets one message from a one-time subscription to the given subject and type.
|
|
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:
Note that this routine allocates memory and cMsgSubscribeConfigDestroy() must be called to free it.
|
|
This routine frees the memory associated with a configuration created by cMsgSubscribeConfigCreate();
|
|
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.
|
|
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.
|
|
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().
|
|
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).
|
|
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.
|
|
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.
|
|
This routine gets the stack size in bytes of the subscription thread. By default the stack size is unspecified (returns 0).
|
|
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.
|
|
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.
|
|
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().
|
|
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).
|
|
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.
|
|
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.
|
|
This routine sets the stack size in bytes of the subscription thread. By default the stack size is unspecified.
|
|
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().
|
|
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.
|
|
This routine unsubscribes to messages of the given handle (which represents a given subject, type, callback, and user argument).
|
|
This routine returns whether a message has been sent over the wire or not.
|