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.
#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 "cMsg.h"
#include "regex.h"
Defines | |
#define | CMSG_MAXHOSTNAMELEN 256 |
#define | MAX_STR_LEN 2000 |
Typedefs | |
typedef parsedUDL_t | parsedUDL |
Functions | |
int | cMsgConnect (const char *myUDL, const char *myName, const char *myDescription, void **domainId) |
int | cMsgConnectOrig (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 error) |
int | cMsgSetDebugLevel (int level) |
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) |
int | cMsgFreeMessage (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 | 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 | 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 | cMsgSetByteArrayAndLimits (void *vmsg, char *array, int offset, int length) |
int | cMsgCopyByteArray (void *vmsg, char *array, int offset, 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 (void *vmsg, char **string, int binary) |
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) |
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) |
Variables | |
int | cMsgDebug = CMSG_DEBUG_NONE |
domainTypeInfo | cmsgDomainTypeInfo |
domainTypeInfo | fileDomainTypeInfo |
domainTypeInfo | rcDomainTypeInfo |
|
Because MAXHOSTNAMELEN is defined to be 256 on Solaris and 64 on Linux, use CMSG_MAXHOSTNAMELEN as a substitute that is uniform across all platforms. |
|
|
|
This structure contains the components of a given UDL broken down into its consituent parts. |
|
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 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 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 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 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 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 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!
|
|
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 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 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 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 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.
|
|
Global debug level. |
|
For domain implementations. |
|
|
|
|