3 /* gras/messages.h - Public interface to GRAS messages */
5 /* Authors: Martin Quinson */
6 /* Copyright (C) 2003,2004 Martin Quinson. */
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. */
15 #include <stddef.h> /* offsetof() */
16 #include <sys/types.h> /* size_t */
20 /*! C++ users need love */
23 # define BEGIN_DECL extern "C" {
29 /*! C++ users need love */
37 /* End of cruft for C++ */
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;
46 * A message sent or received to/from the network
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.
56 gras_socket_t *sock; /** the socket on which the message was received (to answer) */
59 gras_msgheader_t *header;
60 gras_msgentry_t *entry;
61 unsigned int *dataCount;
63 e_gras_free_directive_t freeDirective;
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
74 * @Returns: the error code (or no_error).
76 * Registers a message to the GRAS mecanism.
79 gras_msgtype_register(gras_msgid_t msgId,
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).
92 * Create a new message, and send it on the network through the given socket.
95 gras_msg_new_and_send(gras_socket_t *sd,
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
111 * Build a message to be sent
114 gras_msg_t *gras_msg_new(gras_msgid_t msgId,
115 e_gras_free_directive_t free_data_on_free,
122 * Build a new message in the exact same way than gras_msg_new(), but taking its arguments as
125 gras_msg_t *gras_msg_new_va(gras_msgid_t msgId,
126 e_gras_free_directive_t free_data,
132 * @msg: original to copy.
137 gras_msg_t *gras_msg_copy(gras_msg_t *msg);
141 * @msg: poor guy going to diediedie.
143 * Free a msg built with gras_msg_new().
145 void gras_msg_free(gras_msg_t *msg);
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.
154 * Access to the content of a message.
156 #define gras_msg_ctn(msg,sequence,num,type) \
157 ((type *)msg->data[sequence])[num]
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.
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.
168 * If the callback accepts the message, it should free it after use.
171 typedef int (*gras_cb_t)(gras_msg_t *msg);
175 * @message: id of the concerned messages
176 * @TTL: How many time should this callback be used
178 * @Returns: the error code (or no_error).
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)
187 gras_cb_register(gras_msgid_t message,
193 * @timeOut: How long to wait for incoming messages
194 * @Returns: the error code (or no_error).
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()).
199 gras_error_t gras_msg_handle(double timeOut);
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).
209 * Sends the message on the socket sd using an automatic and adaptative timeout.
213 gras_msg_send(gras_socket_t *sd,
215 e_gras_free_directive_t freeDirective);
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).
224 * Waits for a message to come in over a given socket.
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().
230 gras_msg_wait(double timeout,
232 gras_msg_t **message);
237 #endif /* GRAS_MSG_H */