include/messages.h

   1 /* $Id$ */
   2
   3 /* gras/messages.h - Public interface to GRAS messages                      */
   4
   5 /* Authors: Martin Quinson                                                  */
   6 /* Copyright (C) 2003 the OURAGAN project.                                  */
   7
   8 /* This program is free software; you can redistribute it and/or modify it
   9    under the terms of the license (GNU LGPL) which comes with this package. */
  10
  11
  12 #ifndef GRAS_MSG_H
  13 #define GRAS_MSG_H
  14
  15 #include <stddef.h>    /* offsetof() */
  16 #include <sys/types.h>  /* size_t */
  17 #include <stdarg.h>
  18
  19
  20 /*! C++ users need love */
  21 #ifndef BEGIN_DECL
  22 # ifdef __cplusplus
  23 #  define BEGIN_DECL extern "C" {
  24 # else
  25 #  define BEGIN_DECL
  26 # endif
  27 #endif
  28
  29 /*! C++ users need love */
  30 #ifndef END_DECL
  31 # ifdef __cplusplus
  32 #  define END_DECL }
  33 # else
  34 #  define END_DECL
  35 # endif
  36 #endif
  37 /* End of cruft for C++ */
  38
  39 BEGIN_DECL
  40
  41 typedef unsigned int gras_msgid_t;
  42 typedef struct gras_msgheader_s gras_msgheader_t;
  43 typedef struct gras_msgentry_s  gras_msgentry_t;
  44
  45 /**
  46  * A message sent or received to/from the network
  47  *
  48  * Do not mess with the content of this structure. Only access it through the following functions:
  49  * @gras_msg_new() or @gras_msg_copy() to create such struct.
  50  * @gras_msg_free() to get ride of it.
  51  * @gras_msg_ctn() to read its content.
  52  *
  53  */
  54 typedef struct {
  55   /* public */
  56   gras_sock_t *sock; /** the socket on which the message was received (to answer) */
  57
  58   /* private */
  59   gras_msgheader_t *header;
  60   gras_msgentry_t *entry;
  61   unsigned int *dataCount;
  62   void **data;
  63   e_gras_free_directive_t freeDirective;
  64 } gras_msg_t;
  65
  66 /**
  67  * gras_msgtype_register:
  68  * @msgId: identificator of such messages
  69  * @name: name as it should be used for logging messages
  70  * @sequence_count: number of groups in variadics
  71  * @Varargs: List of (const DataDescriptor *, int DDcount), describing the
  72  *  elements in each sequence (DDlength is the length of the corresponding
  73  *  DataDescriptor).
  74  * @Returns: the error code (or no_error).
  75  *
  76  * Registers a message to the GRAS mecanism.
  77  */
  78 gras_error_t
  79 gras_msgtype_register(gras_msgid_t msgId,
  80                       const char *name,
  81                       int sequence_count,
  82                       ...);
  83
  84 /**
  85  * gras_msg_new_and_send:
  86  * @sd: Socket on which the message should be sent
  87  * @msgId: identificator this messages
  88  * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
  89  *  The number of sequences is given by the registration of ht
  90  * @Returns: the error code (or no_error).
  91  *
  92  * Create a new message, and send it on the network through the given socket.
  93  */
  94 gras_error_t
  95 gras_msg_new_and_send(gras_sock_t *sd,
  96                       gras_msgid_t msgId,
  97                       int seqCount,
  98                       ...);
  99
 100
 101 /**
 102  * gras_msg_new:
 103  * @msgId: identificator this messages
 104  * @free_data_on_free: boolean indicating wheater the data must be freed when the msg get freed.
 105  * @seqCount: number of sequences in this message (must be the same than the value
 106  *  registered using gras_msgtype_register() for that msgId)
 107  * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
 108  *  The number of sequences is given by the registration of ht
 109  * @Returns: the message built or NULL on error
 110  *
 111  * Build a message to be sent
 112  */
 113
 114 gras_msg_t *gras_msg_new(gras_msgid_t msgId,
 115                          e_gras_free_directive_t free_data_on_free,
 116                          int seqCount,
 117                          ...);
 118
 119 /**
 120  * gras_msg_new_va:
 121  *
 122  * Build a new message in the exact same way than gras_msg_new(), but taking its arguments as
 123  * variadic ones.
 124  */
 125 gras_msg_t *gras_msg_new_va(gras_msgid_t msgId,
 126                         e_gras_free_directive_t free_data,
 127                         int seqCount,
 128                         va_list ap);
 129
 130 /**
 131  * gras_msg_copy:
 132  * @msg: original to copy.
 133  *
 134  * Copy a message.
 135  */
 136
 137 gras_msg_t *gras_msg_copy(gras_msg_t *msg);
 138
 139 /**
 140  * gras_msg_free:
 141  * @msg: poor guy going to diediedie.
 142  *
 143  * Free a msg built with gras_msg_new().
 144  */
 145 void gras_msg_free(gras_msg_t *msg);
 146
 147 /**
 148  * gras_msg_ctn:
 149  * @msg: the carrier of the data
 150  * @sequence: Sequence in which you want to see the data.
 151  * @num: Number in this sequence of the element to access.
 152  * @type: type of the element to access.
 153  *
 154  * Access to the content of a message.
 155  */
 156 #define gras_msg_ctn(msg,sequence,num,type) \
 157   ((type *)msg->data[sequence])[num]
 158
 159 /**
 160  * gras_cb_t:
 161  * @msg: The message itself
 162  * @Returns: true if the message was accepted by the callback and false if it should be passed to the next one.
 163  *
 164  * Type of message callback functions. Once a such a function is registered to
 165  * handle messages of a given type with RegisterCallback(), it will be called
 166  * each time such a message incomes.
 167  *
 168  * If the callback accepts the message, it should free it after use.
 169  */
 170
 171 typedef int (*gras_cb_t)(gras_msg_t *msg);
 172
 173 /**
 174  * gras_cb_register:
 175  * @message: id of the concerned messages
 176  * @TTL: How many time should this callback be used
 177  * @cb: The callback.
 178  * @Returns: the error code (or no_error).
 179  *
 180  * Indicates a desire that the function #cb# be called whenever a
 181  * #message# message comes in.
 182  * #TTL# is how many time this callback should be used. After that, this
 183  * callback will be unregistred. If <0, the callback will never be unregistered.
 184  * (ie, it will be permanent)
 185  */
 186 gras_error_t
 187 gras_cb_register(gras_msgid_t message,
 188                  int TTL,
 189                  gras_cb_t cb);
 190
 191 /**
 192  * gras_msg_handle:
 193  * @timeOut: How long to wait for incoming messages
 194  * @Returns: the error code (or no_error).
 195  *
 196  * Waits up to #timeOut# seconds to see if a message comes in; if so, calls the
 197  * registered listener for that message (see RegisterCallback()).
 198  */
 199 gras_error_t gras_msg_handle(double timeOut);
 200
 201
 202 /**
 203  * gras_msg_send:
 204  * @sd: Socket to write on
 205  * @msg: to send (build it with @gras_msg_new())
 206  * @freeDirective: if the msg passed as argument should be gras_msg_free'ed after sending.
 207  * @Returns: the error code (or no_error).
 208  *
 209  * Sends the message on the socket sd using an automatic and adaptative timeout.
 210  */
 211
 212 gras_error_t
 213 gras_msg_send(gras_sock_t *sd,
 214               gras_msg_t *msg,
 215               e_gras_free_directive_t freeDirective);
 216
 217 /**
 218  * gras_msg_wait:
 219  * @timeout: How long should we wait for this message.
 220  * @id: id of awaited msg
 221  * @message: where to store the message when it comes.
 222  * @Returns: the error code (or no_error).
 223  *
 224  * Waits for a message to come in over a given socket.
 225  *
 226  * Every message of another type received before the one waited will be queued
 227  * and used by subsequent call to this function or MsgHandle().
 228  */
 229 gras_error_t
 230 gras_msg_wait(double timeout,
 231               gras_msgid_t id,
 232               gras_msg_t **message);
 233
 234
 235 END_DECL
 236
 237 #endif /* GRAS_MSG_H */
 238