cMsg Messaging System  6.0
 All Files Functions Variables Typedefs Enumerator Macros
cMsg.c File Reference
#include <strings.h>
#include <dlfcn.h>
#include <stdio.h>
#include <stdlib.h>
#include <pthread.h>
#include <string.h>
#include <ctype.h>
#include "cMsgNetwork.h"
#include "cMsgPrivate.h"
#include "cMsgRegex.h"

Macros

#define LOCAL_ARRAY_SIZE   200
 
#define MAX_STR_LEN   2000
 

Typedefs

typedef struct parsedUDL_t parsedUDL
 

Functions

void cMsgTrim (char *s)
 
void cMsgTrimChar (char *s, char trimChar)
 
void cMsgTrimDoubleChars (char *s, char trimChar)
 
char * strndup (const char *s1, size_t count)
 
int cMsgSetUDL (void *domainId, const char *UDL)
 
int cMsgGetCurrentUDL (void *domainId, const char **udl)
 
int cMsgGetServerHost (void *domainId, const char **ipAddress)
 
int cMsgGetServerPort (void *domainId, int *port)
 
int cMsgGetInfo (void *domainId, const char *command, char **string)
 
int cMsgConnect (const char *myUDL, const char *myName, const char *myDescription, void **domainId)
 
int cMsgReconnect (void *domainId)
 
int cMsgDisconnect (void **domainId)
 
int cMsgSend (void *domainId, void *msg)
 
int cMsgSyncSend (void *domainId, void *msg, const struct timespec *timeout, int *response)
 
int cMsgFlush (void *domainId, const struct timespec *timeout)
 
int cMsgSubscribe (void *domainId, const char *subject, const char *type, cMsgCallbackFunc *callback, void *userArg, cMsgSubscribeConfig *config, void **handle)
 
int cMsgUnSubscribe (void *domainId, void *handle)
 
int cMsgSubscriptionPause (void *domainId, void *handle)
 
int cMsgSubscriptionResume (void *domainId, void *handle)
 
int cMsgSubscriptionQueueCount (void *domainId, void *handle, int *count)
 
int cMsgSubscriptionQueueIsFull (void *domainId, void *handle, int *full)
 
int cMsgSubscriptionQueueClear (void *domainId, void *handle)
 
int cMsgSubscriptionMessagesTotal (void *domainId, void *handle, int *total)
 
int cMsgSendAndGet (void *domainId, void *sendMsg, const struct timespec *timeout, void **replyMsg)
 
int cMsgSubscribeAndGet (void *domainId, const char *subject, const char *type, const struct timespec *timeout, void **replyMsg)
 
int cMsgMonitor (void *domainId, const char *command, void **replyMsg)
 
int cMsgReceiveStart (void *domainId)
 
int cMsgReceiveStop (void *domainId)
 
int cMsgGetConnectState (void *domainId, int *connected)
 
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 error)
 
int cMsgSetDebugLevel (int level)
 
int cMsgGetUDL (void *domainId, char **udl)
 
int cMsgGetName (void *domainId, char **name)
 
int cMsgGetDescription (void *domainId, char **description)
 
int cMsgGetReceiveState (void *domainId, int *receiveState)
 
int cMsgFreeMessage (void **vmsg)
 
int cMsgFreeMessage_r (void **vmsg)
 
void * cMsgCopyMessage (const void *vmsg)
 
int cMsgInitMessage (void *vmsg)
 
void * cMsgCreateMessage (void)
 
void * cMsgCreateNewMessage (const void *vmsg)
 
void * cMsgCreateResponseMessage (const void *vmsg)
 
void * cMsgCreateNullResponseMessage (const void *vmsg)
 
int cMsgGetHistoryLengthMax (const void *vmsg, int *len)
 
int cMsgSetHistoryLengthMax (void *vmsg, int len)
 
int cMsgWasSent (const void *vmsg, int *hasBeenSent)
 
int cMsgGetVersion (const void *vmsg, int *version)
 
int cMsgSetGetResponse (void *vmsg, int getResponse)
 
int cMsgGetGetResponse (const void *vmsg, int *getResponse)
 
int cMsgSetNullGetResponse (void *vmsg, int nullGetResponse)
 
int cMsgGetNullGetResponse (const void *vmsg, int *nullGetResponse)
 
int cMsgGetGetRequest (const void *vmsg, int *getRequest)
 
int cMsgGetDomain (const void *vmsg, const char **domain)
 
int cMsgGetPayloadText (const void *vmsg, const char **payloadText)
 
int cMsgSetSubject (void *vmsg, const char *subject)
 
int cMsgGetSubject (const void *vmsg, const char **subject)
 
int cMsgSetType (void *vmsg, const char *type)
 
int cMsgGetType (const void *vmsg, const char **type)
 
int cMsgSetText (void *vmsg, const char *text)
 
int cMsgGetText (const void *vmsg, const char **text)
 
int cMsgSetUserInt (void *vmsg, int userInt)
 
int cMsgGetUserInt (const void *vmsg, int *userInt)
 
int cMsgSetUserTime (void *vmsg, const struct timespec *userTime)
 
int cMsgGetUserTime (const void *vmsg, struct timespec *userTime)
 
int cMsgSetByteArrayEndian (void *vmsg, int endian)
 
int cMsgGetByteArrayEndian (const void *vmsg, int *endian)
 
int cMsgNeedToSwap (const void *vmsg, int *swap)
 
int cMsgSetByteArrayLength (void *vmsg, int length)
 
int cMsgResetByteArrayLength (void *vmsg)
 
int cMsgGetByteArrayLength (const void *vmsg, int *length)
 
int cMsgGetByteArrayLengthFull (const void *vmsg, int *length)
 
int cMsgSetByteArrayOffset (void *vmsg, int offset)
 
int cMsgGetByteArrayOffset (const void *vmsg, int *offset)
 
int cMsgSetByteArrayNoCopy (void *vmsg, char *array, int length)
 
int cMsgSetByteArray (void *vmsg, char *array, int length)
 
int cMsgGetByteArray (const void *vmsg, char **array)
 
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 cMsgToString (const void *vmsg, char **string)
 
int cMsgToString2 (const void *vmsg, char **string, int binary, int compact, int noSystemFields)
 
int cMsgPayloadToString (const void *vmsg, char **string, int binary, int compact, int noSystemFields)
 
char * escapeQuotesForXML (char *s)
 
char * escapeCdataForXML (char *s)
 
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)
 
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)
 

Variables

int cMsgDebug = CMSG_DEBUG_ERROR
 
domainTypeInfo cmsgDomainTypeInfo
 
domainTypeInfo fileDomainTypeInfo
 
domainTypeInfo rcDomainTypeInfo
 
domainTypeInfo emuDomainTypeInfo
 

Detailed Description

This file contains the entire cMsg user API.

Introduction

The user API acts as a multiplexor. Depending on the particular UDL used to connect to a specific cMsg server, the API will direct the user's library calls to the appropriate cMsg implementation.

Macro Definition Documentation

#define MAX_STR_LEN   2000

Typedef Documentation

typedef struct parsedUDL_t parsedUDL

This structure contains the components of a given UDL broken down into its consituent parts.

Function Documentation

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
myUDLthe Universal Domain Locator used to uniquely identify the cMsg server to connect to
myNamename of this client
myDescriptiondescription of this client
domainIdpointer to pointer which gets filled with a unique id referring to this connection.
Returns
CMSG_OK if successful
CMSG_ERROR if regular expression compilation fails during UDL parsing or circular UDL references
CMSG_BAD_ARGUMENT if one of the arguments is bad
CMSG_BAD_FORMAT if the UDL is formatted incorrectly
CMSG_OUT_OF_MEMORY if out of memory (allocated or static)
any errors returned from the actual domain dependent implemenation of cMsgConnect

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

void* cMsgCopyMessage ( const void *  vmsg)

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

Parameters
vmsgpointer to message structure being copied
Returns
a pointer to the message copy
NULL if argument is NULL or no memory available

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

Referenced by cMsgCreateNewMessage().

void* cMsgCreateMessage ( void  )

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

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

Referenced by cMsgCreateNullResponseMessage(), and cMsgCreateResponseMessage().

void* cMsgCreateNewMessage ( const void *  vmsg)

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

Parameters
vmsgpointer to message being copied
Returns
a pointer to the new message
NULL if no memory available or message argument is NULL

References cMsgCopyMessage().

void* cMsgCreateNullResponseMessage ( const void *  vmsg)

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

Parameters
vmsgpointer to message to which response fields are set
Returns
a pointer to the new message
NULL if no memory available, message argument is NULL, or message argument is not from calling sendAndGet()

References cMsgCreateMessage().

void* cMsgCreateResponseMessage ( const void *  vmsg)

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

Parameters
vmsgpointer to message to which response fields are set
Returns
a pointer to the new message
NULL if no memory available, message argument is NULL, or message argument is not from calling sendAndGet()

References cMsgCreateMessage().

int cMsgDisconnect ( void **  domainId)

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

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

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

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
domainIddomain connection id
timeoutamount of time to wait for completion
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgFlush

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgFreeMessage ( void **  vmsg)

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

Parameters
vmsgaddress of pointer to message structure being freed
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if msg is NULL

References CMSG_OK.

int cMsgFreeMessage_r ( void **  vmsg)

This routine frees the memory allocated in the creation of a message, but in a way which avoids mutex deadlock when recursively freeing a payload's cMsgMessage items.

Parameters
vmsgaddress of pointer to message structure being freed
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if msg is NULL

References CMSG_OK.

int cMsgGetByteArray ( const void *  vmsg,
char **  array 
)

This routine gets a message's byte array.

Parameters
vmsgpointer to message
arraypointer to be filled with byte array
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
endianint pointer to be filled with byte array data endianness
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
lengthint pointer to be filled with byte array length (in bytes)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
lengthint pointer to be filled with byte array's total length (in bytes)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
offsetint pointer to be filled with byte array offset index
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetConnectState ( void *  domainId,
int *  connected 
)

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

Parameters
domainIddomain connection id
connectedinteger pointer to be filled in with connection state, (1-connected, 0-unconnected)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgGetConnectState

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
udlpointer filled in with current UDL or NULL if no connection
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or udl arg is NULL
any errors returned from the actual domain dependent implemenation of cMsgGetConnectState

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIdid of the domain connection
descriptionpointer to pointer filled with the description
Returns
CMSG_BAD_ARGUMENT if either arg is NULL
CMSG_OK if successful

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
domainpointer to pointer filled with message's cMsg domain
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int 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
vmsgpointer to message
getRequestinteger pointer to be filled in with 1 if message sent by a sendAndGet and 0 otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
getResponseinteger pointer to be filled in 1 if message is a response to a sendAndGet and 0 otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
leninteger pointer to be filled inwith max number of entries this message keeps of its history of various parameters
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
domainIdid of the domain connection
commandcommand whose value determines what is returned in string arg
stringpointer which gets filled in with a return string (may be NULL)
Returns
CMSG_OK if successful
CMSG_NOT_IMPLEMENTED this routine is not implemented

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int 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
domainIdid of the domain connection
namepointer to pointer filled with the name
Returns
CMSG_BAD_ARGUMENT if either arg is NULL
CMSG_OK if successful

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
nullGetResponseinteger pointer to be filled in with 1 if message is a NULL response to a sendAndGet and 0 otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
payloadTextpointer to pointer filled with message's payload text
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
receiverpointer to pointer filled with message's receiver
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
receiverHostpointer to pointer filled with host of the message receiver
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
receiverTimepointer to be filled with time message was received
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReceiveState ( void *  domainId,
int *  receiveState 
)

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

Parameters
domainIdid of the domain connection
receiveStateinteger pointer to be filled in with the receive state
Returns
CMSG_BAD_ARGUMENT if either arg is NULL
CMSG_OK if successful

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetReliableSend ( void *  vmsg,
int *  boolean 
)

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

Parameters
vmsgpointer to message
booleanint pointer to be filled with 1 if true (TCP), else 0 (UDP)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
senderpointer to pointer filled with message's sender
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
senderHostpointer to pointer filled with host of the message sender
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
senderTimepointer to be filled with time message was last sent
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
domainIdid of the domain connection
ipAddresspointer filled in with server IP address
Returns
CMSG_OK if successful
CMSG_NOT_IMPLEMENTED if not implemented in the given domain
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgGetServerPort ( void *  domainId,
int *  port 
)

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

Parameters
domainIdid of the domain connection
portpointer filled in with server TCP port
Returns
CMSG_OK if successful
CMSG_NOT_IMPLEMENTED if not implemented in the given domain
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int 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
vmsgpointer to message
subjectpointer to pointer filled with message's subject
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
sizepointer which gets filled with a callback's cue size or -1 if no information is available
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
domainpointer to pointer filled with a subscription's domain or NULL if no information is available
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
subjectpointer to pointer filled with a subscription's subject or NULL if no information is available
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
typepointer to pointer filled with a subscription's type or NULL if no information is available
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
udlpointer to pointer filled with the udl of a subscription's connection or NULL if no information is available
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
textpointer to pointer filled with a message's text
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
typepointer to pointer filled with message's type
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
domainIdid of the domain connection
udlpointer to pointer filled with the UDL
Returns
CMSG_BAD_ARGUMENT if either arg is NULL
CMSG_OK if successful

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgGetUserInt ( const void *  vmsg,
int *  userInt 
)

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

Parameters
vmsgpointer to message
userIntinteger pointer to be filled with message's user-defined integer
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
userTimetime_t pointer to be filled with message's user-defined time
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
versioninteger pointer to be filled in with cMsg major version
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int 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
vmsgpointer to message structure being initialized
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if msg is NULL

References CMSG_OK.

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
domainIddomain connection id
commandstring to monitor data collecting routine
replyMsgmessage received from the domain containing monitor data
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
vmsgpointer to message
swapint pointer to be filled with 1 if byte array needs swapping, else 0
Returns
CMSG_OK if successful
CMSG_ERROR if local endianness is unknown
CMSG_BAD_ARGUMENT if either arg is NULL

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

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

This routine converts the message payload to an XML string.

Parameters
vmsgpointer to message
stringis pointer to char* that will hold the malloc'd string
binaryincludes binary as ASCII if true, else binary is ignored
compactif true (!=0), do not include attributes with null or default integer values
noSystemFieldsif true (!=0), do not include system (metadata) payload fields
Returns
CMSG_OK if successful
CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count
CMSG_BAD_ARGUMENT if message is NULL
CMSG_OUT_OF_MEMORY if out of memory
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
errorerror condition
Returns
error string

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

int cMsgReceiveStart ( void *  domainId)

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

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

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

int cMsgReceiveStop ( void *  domainId)

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

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

References CMSG_BAD_ARGUMENT, CMSG_OK, and LOCAL_ARRAY_SIZE.

int cMsgReconnect ( void *  domainId)

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

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

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgResetByteArrayLength ( void *  vmsg)

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

Parameters
vmsgpointer to message
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSend ( void *  domainId,
void *  msg 
)

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

Parameters
domainIddomain connection id
msgpointer to a message structure
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSend

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
sendMsgmessages to send to all listeners
timeoutamount of time to wait for the response message
replyMsgmessage received from the responder; may be NULL
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
vmsgpointer to message
arraybyte array
lengthnumber of bytes in array
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL, or length < 0
CMSG_OUT_OF_MEMORY if out of memory

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_MEMORY.

int cMsgSetByteArrayEndian ( void *  vmsg,
int  endian 
)

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

Parameters
vmsgpointer to message
endianbyte array's endianness
Returns
CMSG_OK if successful
CMSG_ERROR if local endianness is unknown
CMSG_BAD_ARGUMENT if message is NULL, or endian is not equal to either CMSG_ENDIAN_BIG, CMSG_ENDIAN_LITTLE, CMSG_ENDIAN_LOCAL, CMSG_ENDIAN_NOTLOCAL, or CMSG_ENDIAN_SWITCH

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

int cMsgSetByteArrayLength ( void *  vmsg,
int  length 
)

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

Parameters
vmsgpointer to message
lengthbyte array's length (in bytes)
Returns
CMSG_OK if successful
CMSG_OUT_OF_RANGE if offset + length is beyond array bounds
CMSG_BAD_ARGUMENT if message is NULL or length < 0

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_RANGE.

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

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

Parameters
vmsgpointer to message
arraybyte array
lengthnumber of bytes in array
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL or length is < 0

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetByteArrayOffset ( void *  vmsg,
int  offset 
)

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

Parameters
vmsgpointer to message
offsetbyte array's offset index
Returns
CMSG_OK if successful
CMSG_OUT_OF_RANGE if offset + length is beyond array bounds
CMSG_BAD_ARGUMENT if message is NULL or offset < 0

References CMSG_BAD_ARGUMENT, CMSG_OK, and CMSG_OUT_OF_RANGE.

int cMsgSetDebugLevel ( int  level)

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

Parameters
leveldebug level desired
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if debug level is bad

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

int cMsgSetGetResponse ( void *  vmsg,
int  getResponse 
)

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

Parameters
vmsgpointer to message
getResponseset to 1 if message is a response to a sendAndGet, anything else otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message argument is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetHistoryLengthMax ( void *  vmsg,
int  len 
)

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

Parameters
vmsgpointer to message
lenmax number of entries this message keeps of its history of various parameters
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message argument is NULL
CMSG_OUT_OF_RANGE if len < 0 or > CMSG_HISTORY_LENGTH_ABS_MAX

References CMSG_OK, and CMSG_OUT_OF_RANGE.

int cMsgSetNullGetResponse ( void *  vmsg,
int  nullGetResponse 
)

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

Parameters
vmsgpointer to message
nullGetResponseset to 1 if message is a null get response to a sendAndGet, anything else otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message argument is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSetReliableSend ( void *  vmsg,
int  boolean 
)

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

Parameters
vmsgpointer to message
boolean0 if false (use UDP), anything else true (use TCP)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

This routine sets the shutdown handler function.

Parameters
domainIddomain connection id
handlershutdown handler function
userArgargument to shutdown handler
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

This routine sets the subject of a message.

Parameters
vmsgpointer to message
subjectmessage subject
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

This routine sets the text of a message.

Parameters
vmsgpointer to message
textmessage text
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

This routine sets the type of a message.

Parameters
vmsgpointer to message
typemessage type
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

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

References CMSG_BAD_ARGUMENT, CMSG_OK, CMSG_WRONG_DOMAIN_TYPE, and LOCAL_ARRAY_SIZE.

int cMsgSetUserInt ( void *  vmsg,
int  userInt 
)

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

Parameters
vmsgpointer to message
userIntmessage's user-defined integer
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

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

Parameters
vmsgpointer to message
userTimemessage's user-defined time
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if message is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

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

Method to shutdown the given clients.

Parameters
domainIddomain connection id
clientclient(s) to be shutdown
flagflag describing the mode of shutdown: 0 to not include self, CMSG_SHUTDOWN_INCLUDE_ME to include self in shutdown.
Returns
CMSG_OK if successful
CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement shutdown
CMSG_NETWORK_ERROR if error in communicating with the server
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or flag argument improper value
any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, CMSG_SHUTDOWN_INCLUDE_ME, and LOCAL_ARRAY_SIZE.

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

Method to shutdown the given servers.

Parameters
domainIddomain connection id
serverserver(s) to be shutdown
flagflag describing the mode of shutdown: 0 to not include self, CMSG_SHUTDOWN_INCLUDE_ME to include self in shutdown.
Returns
CMSG_OK if successful
CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement shutdown
CMSG_NETWORK_ERROR if error in communicating with the server
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called or flag argument improper value
any errors returned from the actual domain dependent implemenation of cMsgDisconnect

References CMSG_BAD_ARGUMENT, CMSG_SHUTDOWN_INCLUDE_ME, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
subjectsubject of messages subscribed to
typetype of messages subscribed to
callbackpointer to callback to be executed on receipt of message
userArguser-specified pointer to be passed to the callback
configpointer to callback configuration structure
handlepointer to handle (void pointer) to be used for unsubscribing from this subscription
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSubscribe

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
subjectsubject of message subscribed to
typetype of message subscribed to
timeoutamount of time to wait for the message
replyMsgmessage received
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSendAndGet

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

cMsgSubscribeConfig* cMsgSubscribeConfigCreate ( void  )

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

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

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

Returns
NULL if no memory available
pointer to configuration if successful
int cMsgSubscribeConfigDestroy ( cMsgSubscribeConfig config)

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

Parameters
configpointer to configuration
Returns
CMSG_OK

References CMSG_OK.

int cMsgSubscribeGetMaxCueSize ( cMsgSubscribeConfig config,
int *  size 
)

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

Parameters
configpointer to configuration
sizeinteger pointer to be filled with configuration's maximum cue size
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMaxThreads ( cMsgSubscribeConfig config,
int *  threads 
)

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

Parameters
configpointer to configuration
threadsinteger pointer to be filled with the maximum number of threads a parallelized subscribe's callback can run at once
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMaySkip ( cMsgSubscribeConfig config,
int *  maySkip 
)

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

Parameters
configpointer to configuration
maySkipinteger pointer to be filled with 0 if messages may NOT be skipped (deleted), or anything else otherwise
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMessagesPerThread ( cMsgSubscribeConfig config,
int *  mpt 
)

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

Parameters
configpointer to configuration
mptinteger pointer to be filled with the maximum number of unprocessed messages per thread before starting another thread
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetMustSerialize ( cMsgSubscribeConfig config,
int *  serialize 
)

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

Parameters
configpointer to configuration
serializeinteger pointer to be filled with 0 if callback may be parallelized, or anything else if callback must be serialized
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetSkipSize ( cMsgSubscribeConfig config,
int *  size 
)

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

Parameters
configpointer to configuration
sizeinteger pointer to be filled with the number of messages to skip (delete)
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeGetStackSize ( cMsgSubscribeConfig config,
size_t *  size 
)

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

Parameters
configpointer to configuration
sizepointer to be filled with stack size in bytes of subscription thread
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

int cMsgSubscribeSetMaxCueSize ( cMsgSubscribeConfig config,
int  size 
)

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

Parameters
configpointer to configuration
sizemaximum cue size
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL or size < 1

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMaxThreads ( cMsgSubscribeConfig config,
int  threads 
)

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

Parameters
configpointer to configuration
threadsthe maximum number of threads a parallelized subscribe's callback can run at once
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL or threads < 0

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMaySkip ( cMsgSubscribeConfig config,
int  maySkip 
)

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

Parameters
configpointer to configuration
maySkipset to 0 if messages may NOT be skipped, set to anything else otherwise
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMessagesPerThread ( cMsgSubscribeConfig config,
int  mpt 
)

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

Parameters
configpointer to configuration
mptset to maximum number of unprocessed messages per thread before starting another thread
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL or mpt < 1

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetMustSerialize ( cMsgSubscribeConfig config,
int  serialize 
)

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

Parameters
configpointer to configuration
serializeset to 0 if callback may be parallelized, or set to anything else if callback must be serialized
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetSkipSize ( cMsgSubscribeConfig config,
int  size 
)

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

Parameters
configpointer to configuration
sizenumber of messages to skip (delete)
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL or size < 0

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

int cMsgSubscribeSetStackSize ( cMsgSubscribeConfig config,
size_t  size 
)

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

Parameters
configpointer to configuration
sizestack size in bytes of subscription thread
Returns
CMSG_OK if successful
CMSG_NOT_INITIALIZED if configuration was not initialized
CMSG_BAD_ARGUMENT if configuration is NULL or size < 1 byte

References CMSG_BAD_ARGUMENT, CMSG_NOT_INITIALIZED, and CMSG_OK.

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

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
totalint pointer filled in with total number of messages sent to a subscription callback
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionPause ( void *  domainId,
void *  handle 
)

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement this function
any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionQueueClear ( void *  domainId,
void *  handle 
)

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if the id/handle is bad or handle is NULL

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
countint pointer filled in with number of messages in subscription callback queue
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
fullint pointer filled in with 1 if subscription callback queue full, else 0
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

int cMsgSubscriptionResume ( void *  domainId,
void *  handle 
)

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
CMSG_NOT_IMPLEMENTED if the subdomain used does NOT implement this function
any errors returned from the actual domain dependent implemenation of cMsgSubscriptionPause

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
domainIddomain connection id
msgpointer to a message structure
timeoutamount of time to wait for the response
responseinteger pointer that gets filled with the response
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgSyncSend

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
vmsgpointer to message
stringis pointer to char* that will hold the malloc'd string
Returns
CMSG_OK if successful
CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count
CMSG_BAD_ARGUMENT if message is NULL
CMSG_OUT_OF_MEMORY if out of memory
int cMsgToString2 ( const void *  vmsg,
char **  string,
int  binary,
int  compact,
int  noSystemFields 
)

This routine converts the message to an XML string.

Parameters
vmsgpointer to message
stringis pointer to char* that will hold the malloc'd string
binaryincludes binary as ASCII if true, else binary is ignored
compactif true (!=0), do not include attributes with null or default integer values
noSystemFieldsif true (!=0), do not include system (metadata) payload fields
Returns
CMSG_OK if successful
CMSG_ERROR if internal payload parsing error, or cannot get a payload item's type or count
CMSG_BAD_ARGUMENT if message is NULL
CMSG_OUT_OF_MEMORY if out of memory
void cMsgTrim ( char *  s)

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

Parameters
sstring to be trimmed
void cMsgTrimChar ( char *  s,
char  trimChar 
)

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

Parameters
sstring to be trimmed
trimCharcharacter to be trimmed
void cMsgTrimDoubleChars ( char *  s,
char  trimChar 
)

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

Parameters
sstring to be trimmed
trimCharcharacter to be trimmed
int cMsgUnSubscribe ( void *  domainId,
void *  handle 
)

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

Parameters
domainIddomain connection id
handlevoid pointer obtained from cMsgSubscribe
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if bad domainId or cMsgDisconnect() already called
any errors returned from the actual domain dependent implemenation of cMsgUnSubscribe

References CMSG_BAD_ARGUMENT, and LOCAL_ARRAY_SIZE.

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

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

Parameters
vmsgpointer to message
hasBeenSentpointer which gets filled with 1 if msg has been sent, else 0
Returns
CMSG_OK if successful
CMSG_BAD_ARGUMENT if either arg is NULL

References CMSG_BAD_ARGUMENT, and CMSG_OK.

char* escapeCdataForXML ( char *  s)

This routine escapes CDATA constructs which will appear inside of XML CDATA sections. It is not possible to have nested cdata sections. Actually the CDATA ending sequence, ]]> , is what cannot be containing in a surrounding CDATA section. This restriction can be cleverly circumvented by inserting "&lt;![CDATA[]]]]&gt;&lt;![CDATA[&gt;" after each CDATA ending sequence. This creates independent CDATA sections which are not nested.

This routine assumes that there are no nested cdata sections in the input string. Nothing is done to the string if:

  • there is no ]]> so no escaping is necessary
  • there is no <![CDATA[ so s contains malformed XML
  • a particular <![CDATA[ has no corresponding ]]> so s contains malformed XML
  • ]]> comes before <![CDATA[ so s contains malformed XML
Parameters
sstring to be escaped
Returns
escaped string, NULL if no memory or arg is NULL
char* escapeQuotesForXML ( char *  s)

This routine escapes the " char for putting strings into XML. If no quotes are found, the original string is returned (no memory is allocated). If quotes are found, a new string is returned which must be freed by the caller.

Parameters
sstring to be escaped
Returns
escaped string, NULL if no memory or arg is NULL
char* strndup ( const char *  s1,
size_t  count 
)

Variable Documentation

int cMsgDebug = CMSG_DEBUG_ERROR

Global debug level.

Referenced by cMsgPerror(), and cMsgSetDebugLevel().

domainTypeInfo cmsgDomainTypeInfo

For domain implementations.

domainTypeInfo emuDomainTypeInfo
domainTypeInfo fileDomainTypeInfo
domainTypeInfo rcDomainTypeInfo