cMsg.h

Go to the documentation of this file.
00001 /*----------------------------------------------------------------------------*
00002  *
00003  *  Copyright (c) 2004        Southeastern Universities Research Association, *
00004  *                            Thomas Jefferson National Accelerator Facility  *
00005  *                                                                            *
00006  *    This software was developed under a United States Government license    *
00007  *    described in the NOTICE file included as part of this distribution.     *
00008  *                                                                            *
00009  *    E.Wolin, 14-Jul-2004, Jefferson Lab                                     *
00010  *                                                                            *
00011  *    Authors: Elliott Wolin                                                  *
00012  *             wolin@jlab.org                    Jefferson Lab, MS-6B         *
00013  *             Phone: (757) 269-7365             12000 Jefferson Ave.         *
00014  *             Fax:   (757) 269-5800             Newport News, VA 23606       *
00015  *                                                                            *
00016  *             Carl Timmer                                                    *
00017  *             timmer@jlab.org                   Jefferson Lab, MS-6B         *
00018  *             Phone: (757) 269-5130             12000 Jefferson Ave.         *
00019  *             Fax:   (757) 269-5800             Newport News, VA 23606       *
00020  *                                                                            *
00021  * Description:                                                               *
00022  *                                                                            *
00023  *  Defines cMsg API and return codes                                         *
00024  *                                                                            *
00025  *                                                                            *
00026  *----------------------------------------------------------------------------*/
00027  
00098 #ifndef _cMsg_h
00099 #define _cMsg_h
00100 
00101 
00102 /* required includes */
00103 #include <stdlib.h>
00104 #include <time.h>
00105 #ifndef _cMsgConstants_h
00106 #include "cMsgConstants.h"
00107 #endif
00108 
00109 #ifndef VXWORKS
00110 #include <inttypes.h>
00111 #endif
00112 
00114 typedef void *cMsgSubscribeConfig;
00115 
00117 typedef void (cMsgShutdownHandler) (void *userArg);
00118 
00120 typedef void (cMsgCallbackFunc) (void *msg, void *userArg);
00121 
00122 /* function prototypes */
00123 #ifdef __cplusplus
00124 extern "C" {
00125 #endif
00126 
00127 #ifdef Darwin
00128 #define CLOCK_REALTIME 0
00129 int clock_gettime(int dummy, struct timespec *t1);
00130 #endif
00131 
00132 #ifdef VXWORKS
00133   char *strdup(const char *s1);
00134   int   strcasecmp(const char *s1, const char *s2);
00135   int   strncasecmp(const char *s1, const char *s2, size_t n);
00136 #endif
00137 
00138   /* basic functions */
00139   int   cMsgConnect           (const char *myUDL, const char *myName, const char *myDescription,
00140                                void **domainId);
00141   int   cMsgReconnect         (void *domainId);
00142   int   cMsgSend              (void *domainId, void *msg);
00143   int   cMsgSyncSend          (void *domainId, void *msg, const struct timespec *timeout, int *response);
00144   int   cMsgFlush             (void *domainId, const struct timespec *timeout);
00145   int   cMsgSubscribe         (void *domainId, const char *subject, const char *type, cMsgCallbackFunc *callback,
00146                                void *userArg, cMsgSubscribeConfig *config, void **handle);
00147   int   cMsgUnSubscribe       (void *domainId, void *handle);
00148   int   cMsgSubscriptionPause (void *domainId, void *handle);
00149   int   cMsgSubscriptionResume(void *domainId, void *handle);
00150   int   cMsgSubscriptionQueueClear(void *domainId, void *handle);
00151   int   cMsgSubscriptionQueueCount(void *domainId, void *handle, int *count);
00152   int   cMsgSubscriptionQueueIsFull(void *domainId, void *handle, int *full);
00153   int   cMsgSubscriptionMessagesTotal(void *domainId, void *handle, int *total);
00154   int   cMsgSendAndGet        (void *domainId, void *sendMsg, const struct timespec *timeout, void **replyMsg);
00155   int   cMsgSubscribeAndGet   (void *domainId, const char *subject, const char *type,
00156                                const struct timespec *timeout, void **replyMsg);
00157   int   cMsgMonitor           (void *domainId, const char *command, void **replyMsg);
00158   int   cMsgReceiveStart      (void *domainId);
00159   int   cMsgReceiveStop       (void *domainId);
00160   int   cMsgDisconnect        (void **domainId);
00161   int   cMsgSetShutdownHandler(void *domainId, cMsgShutdownHandler *handler, void *userArg);
00162   int   cMsgShutdownClients   (void *domainId, const char *client, int flag);
00163   int   cMsgShutdownServers   (void *domainId, const char *server, int flag);
00164   int   cMsgGetConnectState   (void *domainId,  int *connectState);
00165   int   cMsgSetUDL            (void *domainId, const char *udl);
00166   int   cMsgGetCurrentUDL     (void *domainId, const char **udl);
00167   char *cMsgPerror            (int errorCode);
00168   
00169   
00170   /* message access functions */
00171   int    cMsgFreeMessage          (void **vmsg);
00172   void  *cMsgCreateMessage        (void);
00173   void  *cMsgCreateNewMessage     (const void *vmsg);
00174   void  *cMsgCopyMessage          (const void *vmsg);
00175   int    cMsgInitMessage          (void *vmsg);
00176   void  *cMsgCreateResponseMessage(const void *vmsg);
00177   void  *cMsgCreateNullResponseMessage(const void *vmsg);
00178   int    cMsgWasSent              (const void *vmsg, int *hasBeenSent);
00179   
00180   int    cMsgGetVersion           (const void *vmsg, int *version);
00181   int    cMsgGetGetRequest        (const void *vmsg, int *getRequest);
00182   
00183   int    cMsgSetGetResponse       (      void *vmsg, int  getReponse);
00184   int    cMsgGetGetResponse       (const void *vmsg, int *getReponse);
00185   
00186   int    cMsgSetNullGetResponse   (      void *vmsg, int  nullGetResponse);
00187   int    cMsgGetNullGetResponse   (const void *vmsg, int *nullGetResponse);
00188     
00189   int    cMsgGetDomain            (const void *vmsg, const char **domain);
00190   int    cMsgGetPayloadText       (const void *vmsg, const char **payloadText);
00191   
00192   int    cMsgSetSubject           (      void *vmsg, const char  *subject);
00193   int    cMsgGetSubject           (const void *vmsg, const char **subject);
00194   
00195   int    cMsgSetType              (      void *vmsg, const char  *type);
00196   int    cMsgGetType              (const void *vmsg, const char **type);
00197   
00198   int    cMsgSetText              (      void *vmsg, const char  *text);
00199   int    cMsgGetText              (const void *vmsg, const char **text);
00200   
00201   int    cMsgSetUserInt           (      void *vmsg, int  userInt);
00202   int    cMsgGetUserInt           (const void *vmsg, int *userInt);
00203   
00204   int    cMsgSetUserTime          (      void *vmsg, const struct timespec *userTime);
00205   int    cMsgGetUserTime          (const void *vmsg, struct timespec *userTime);
00206   
00207   int    cMsgGetSender            (const void *vmsg, const char  **sender);
00208   int    cMsgGetSenderHost        (const void *vmsg, const char  **senderHost);
00209   int    cMsgGetSenderTime        (const void *vmsg, struct timespec *senderTime);
00210   
00211   int    cMsgGetReceiver          (const void *vmsg, const char  **receiver);
00212   int    cMsgGetReceiverHost      (const void *vmsg, const char  **receiverHost);
00213   int    cMsgGetReceiverTime      (const void *vmsg, struct timespec *receiverTime);
00214   
00215   int    cMsgSetByteArrayLength    (      void *vmsg, int  length);
00216   int    cMsgResetByteArrayLength  (      void *vmsg);
00217   int    cMsgGetByteArrayLength    (const void *vmsg, int *length);
00218   int    cMsgGetByteArrayLengthFull(const void *vmsg, int *length);
00219   
00220   int    cMsgSetByteArrayOffset   (      void *vmsg, int  offset);
00221   int    cMsgGetByteArrayOffset   (const void *vmsg, int *offset);
00222   
00223   int    cMsgSetByteArrayEndian   (      void *vmsg, int endian);
00224   int    cMsgGetByteArrayEndian   (const void *vmsg, int *endian);
00225   int    cMsgNeedToSwap           (const void *vmsg, int *swap);
00226   
00227   int    cMsgSetByteArray         (      void *vmsg, char *array, int length);
00228   int    cMsgSetByteArrayNoCopy   (      void *vmsg, char *array, int length);
00229   int    cMsgGetByteArray         (const void *vmsg, char **array);
00230   
00231   int    cMsgSetReliableSend      (      void *vmsg, int boolean);
00232   int    cMsgGetReliableSend      (      void *vmsg, int *boolean);
00233   
00234   /* message context stuff */
00235   int    cMsgGetSubscriptionDomain (const void *vmsg, const char **domain);
00236   int    cMsgGetSubscriptionSubject(const void *vmsg, const char **subject);
00237   int    cMsgGetSubscriptionType   (const void *vmsg, const char **type);
00238   int    cMsgGetSubscriptionUDL    (const void *vmsg, const char **udl);
00239   int    cMsgGetSubscriptionCueSize(const void *vmsg, int   *size);
00240   
00241   /*  misc. */
00242   int    cMsgToString              (const void *vmsg, char **string);
00243   int    cMsgToString2             (const void *vmsg, char **string, int binary,
00244                                     int compact, int noSystemFields);
00245   int    cMsgPayloadToString       (const void *vmsg, char **string, int binary,
00246                                     int compact, int noSystemFields);
00247   void   cMsgTrim                  (char *s);
00248   void   cMsgTrimChar              (char *s, char trimChar);
00249   void   cMsgTrimDoubleChars       (char *s, char trimChar);
00250  
00251   /* ***************************************** */
00252   /* compound payload stuff - 66 user routines */
00253   /* ***************************************** */
00254   int    cMsgAddHistoryToPayloadText (      void *vmsg, char *name, char *host, int64_t time, char **pTxt);
00255   int    cMsgSetHistoryLengthMax     (      void *vmsg, int len);
00256   int    cMsgGetHistoryLengthMax     (const void *vmsg, int *len);
00257   
00258   int    cMsgPayloadGet              (const void *vmsg, char **names,  int *types,  int len);
00259   int    cMsgPayloadGetInfo          (const void *vmsg, char ***names, int **types, int *len);
00260   int    cMsgPayloadGetCount         (const void *vmsg, int *count);
00261   int    cMsgPayloadContainsName     (const void *vmsg, const char *name);
00262   int    cMsgPayloadGetType          (const void *vmsg, const char *name, int *type);
00263   int    cMsgPayloadRemove           (      void *vmsg, const char *name);
00264   int    cMsgPayloadCopy             (const void *vmsgFrom, void *vmsgTo);
00265 
00266   int    cMsgPayloadUpdateText       (const void *vmsg);
00267   int    cMsgPayloadGetFieldText     (const void *vmsg, const char *name, const char **val);
00268   void   cMsgPayloadPrint            (const void *vmsg);
00269   
00270 const char *cMsgPayloadFieldDescription(const void *vmsg, const char *name);
00271   
00272   /* users should NOT have access to these 3 routines */
00273   int    cMsgPayloadSetFromText             (      void *vmsg, const char *text);
00274   int    cMsgPayloadSetSystemFieldsFromText (      void *vmsg, const char *text);
00275   int    cMsgPayloadSetAllFieldsFromText    (void *vmsg, const char *text);
00276 
00277   void   cMsgPayloadReset            (      void *vmsg);
00278   void   cMsgPayloadClear            (      void *vmsg);
00279   int    cMsgHasPayload              (const void *vmsg, int *hasPayload);
00280  
00281   int    cMsgGetBinary               (const void *vmsg, const char *name, const char **val,
00282                                       int *len, int *endian);
00283   int    cMsgGetBinaryArray          (const void *vmsg, const char *name, const char ***vals,
00284                                       int **sizes, int **endians, int *count);
00285 
00286   int    cMsgGetMessage              (const void *vmsg, const char *name, const void **val);
00287   int    cMsgGetMessageArray         (const void *vmsg, const char *name, const void ***val, int *len);
00288   
00289   int    cMsgGetString               (const void *vmsg, const char *name, const char **val);
00290   int    cMsgGetStringArray          (const void *vmsg, const char *name, const char ***array, int *len);
00291   
00292   int    cMsgGetFloat                (const void *vmsg, const char *name, float  *val);
00293   int    cMsgGetFloatArray           (const void *vmsg, const char *name, const float  **vals, int *len);
00294   int    cMsgGetDouble               (const void *vmsg, const char *name, double *val);
00295   int    cMsgGetDoubleArray          (const void *vmsg, const char *name, const double **vals, int *len);
00296   
00297   int    cMsgGetInt8                 (const void *vmsg, const char *name, int8_t   *val);
00298   int    cMsgGetInt16                (const void *vmsg, const char *name, int16_t  *val);
00299   int    cMsgGetInt32                (const void *vmsg, const char *name, int32_t  *val);
00300   int    cMsgGetInt64                (const void *vmsg, const char *name, int64_t  *val);
00301   int    cMsgGetUint8                (const void *vmsg, const char *name, uint8_t  *val);
00302   int    cMsgGetUint16               (const void *vmsg, const char *name, uint16_t *val);
00303   int    cMsgGetUint32               (const void *vmsg, const char *name, uint32_t *val);
00304   int    cMsgGetUint64               (const void *vmsg, const char *name, uint64_t *val);
00305   
00306   int    cMsgGetInt8Array            (const void *vmsg, const char *name, const int8_t   **vals, int *len);
00307   int    cMsgGetInt16Array           (const void *vmsg, const char *name, const int16_t  **vals, int *len);
00308   int    cMsgGetInt32Array           (const void *vmsg, const char *name, const int32_t  **vals, int *len);
00309   int    cMsgGetInt64Array           (const void *vmsg, const char *name, const int64_t  **vals, int *len);
00310   int    cMsgGetUint8Array           (const void *vmsg, const char *name, const uint8_t  **vals, int *len);
00311   int    cMsgGetUint16Array          (const void *vmsg, const char *name, const uint16_t **vals, int *len);
00312   int    cMsgGetUint32Array          (const void *vmsg, const char *name, const uint32_t **vals, int *len);
00313   int    cMsgGetUint64Array          (const void *vmsg, const char *name, const uint64_t **vals, int *len);
00314 
00315   int    cMsgAddInt8                 (      void *vmsg, const char *name, int8_t   val);
00316   int    cMsgAddInt16                (      void *vmsg, const char *name, int16_t  val);
00317   int    cMsgAddInt32                (      void *vmsg, const char *name, int32_t  val);
00318   int    cMsgAddInt64                (      void *vmsg, const char *name, int64_t  val);
00319   int    cMsgAddUint8                (      void *vmsg, const char *name, uint8_t  val);
00320   int    cMsgAddUint16               (      void *vmsg, const char *name, uint16_t val);
00321   int    cMsgAddUint32               (      void *vmsg, const char *name, uint32_t val);
00322   int    cMsgAddUint64               (      void *vmsg, const char *name, uint64_t val);
00323 
00324   int    cMsgAddInt8Array            (      void *vmsg, const char *name, const int8_t   vals[], int len);
00325   int    cMsgAddInt16Array           (      void *vmsg, const char *name, const int16_t  vals[], int len);
00326   int    cMsgAddInt32Array           (      void *vmsg, const char *name, const int32_t  vals[], int len);
00327   int    cMsgAddInt64Array           (      void *vmsg, const char *name, const int64_t  vals[], int len);
00328   int    cMsgAddUint8Array           (      void *vmsg, const char *name, const uint8_t  vals[], int len);
00329   int    cMsgAddUint16Array          (      void *vmsg, const char *name, const uint16_t vals[], int len);
00330   int    cMsgAddUint32Array          (      void *vmsg, const char *name, const uint32_t vals[], int len);
00331   int    cMsgAddUint64Array          (      void *vmsg, const char *name, const uint64_t vals[], int len);
00332 
00333   int    cMsgAddString               (      void *vmsg, const char *name, const char *val);
00334   int    cMsgAddStringArray          (      void *vmsg, const char *name, const char **vals, int len);
00335 
00336   int    cMsgAddFloat                (      void *vmsg, const char *name, float  val);
00337   int    cMsgAddDouble               (      void *vmsg, const char *name, double val);
00338   int    cMsgAddFloatArray           (      void *vmsg, const char *name, const float vals[],  int len);
00339   int    cMsgAddDoubleArray          (      void *vmsg, const char *name, const double vals[], int len);
00340 
00341   int    cMsgAddBinary               (      void *vmsg, const char *name, const char *src, int size, int endian);
00342   int    cMsgAddBinaryArray          (      void *vmsg, const char *name, const char *src[], int number,
00343                                             const int size[], const int endian[]);
00344   int    cMsgAddMessage              (      void *vmsg, const char *name, const void *vmessage);
00345   int    cMsgAddMessageArray         (      void *vmsg, const char *name, const void *vmessage[], int len);
00346 
00347   char   *cMsgFloatChars(float f);
00348   char   *cMsgDoubleChars(double d);
00349   char   *cMsgIntChars(uint32_t i);
00350 
00351 
00352   /* system and domain info access functions */
00353   int cMsgGetUDL         (void *domainId, char **udl);
00354   int cMsgGetName        (void *domainId, char **name);
00355   int cMsgGetDescription (void *domainId, char **description);
00356   int cMsgGetReceiveState(void *domainId,  int *receiveState);
00357 
00358   
00359   /* subscribe configuration functions */
00360   cMsgSubscribeConfig *cMsgSubscribeConfigCreate(void);
00361   int cMsgSubscribeConfigDestroy       (cMsgSubscribeConfig *config);
00362   
00363   int cMsgSubscribeSetMaxCueSize       (cMsgSubscribeConfig *config, int  size);
00364   int cMsgSubscribeGetMaxCueSize       (cMsgSubscribeConfig *config, int *size);
00365   
00366   int cMsgSubscribeSetSkipSize         (cMsgSubscribeConfig *config, int  size);
00367   int cMsgSubscribeGetSkipSize         (cMsgSubscribeConfig *config, int *size);
00368   
00369   int cMsgSubscribeSetMaySkip          (cMsgSubscribeConfig *config, int  maySkip);
00370   int cMsgSubscribeGetMaySkip          (cMsgSubscribeConfig *config, int *maySkip);
00371   
00372   int cMsgSubscribeSetMustSerialize    (cMsgSubscribeConfig *config, int  serialize);
00373   int cMsgSubscribeGetMustSerialize    (cMsgSubscribeConfig *config, int *serialize);
00374   
00375   int cMsgSubscribeSetMaxThreads       (cMsgSubscribeConfig *config, int  threads);
00376   int cMsgSubscribeGetMaxThreads       (cMsgSubscribeConfig *config, int *threads);
00377   
00378   int cMsgSubscribeSetMessagesPerThread(cMsgSubscribeConfig *config, int  mpt);
00379   int cMsgSubscribeGetMessagesPerThread(cMsgSubscribeConfig *config, int *mpt);
00380 
00381   int cMsgSubscribeSetStackSize        (cMsgSubscribeConfig *config, size_t size);
00382   int cMsgSubscribeGetStackSize        (cMsgSubscribeConfig *config, size_t *size);
00383 
00384 
00385   /* for debugging */
00386   int cMsgSetDebugLevel(int level);
00387 
00388 
00389 #ifdef __cplusplus
00390 }
00391 #endif
00392 
00393 
00394 #endif /* _cMsg_h */

Generated on Fri Oct 21 09:54:16 2011 for cMsg Messaging System by  doxygen 1.3.9.1