/* $Id$ */
-/* gras/messages.h - Public interface to GRAS messages */
+/* messaging - high level communication (send/receive messages) */
+
+/* module's public interface exported to end user. */
/* Authors: Martin Quinson */
-/* Copyright (C) 2003,2004 Martin Quinson. */
+/* Copyright (C) 2003, 2004 Martin Quinson. */
/* This program is free software; you can redistribute it and/or modify it
under the terms of the license (GNU LGPL) which comes with this package. */
-#ifndef GRAS_MSG_H
-#define GRAS_MSG_H
-
-#include <stddef.h> /* offsetof() */
-#include <sys/types.h> /* size_t */
-#include <stdarg.h>
-
+#ifndef GRAS_MESSAGES_H
+#define GRAS_MESSAGES_H
/*! C++ users need love */
#ifndef BEGIN_DECL
BEGIN_DECL
-typedef unsigned int gras_msgid_t;
-typedef struct gras_msgheader_s gras_msgheader_t;
-typedef struct gras_msgentry_s gras_msgentry_t;
-
-/**
- * A message sent or received to/from the network
- *
- * Do not mess with the content of this structure. Only access it through the following functions:
- * @gras_msg_new() or @gras_msg_copy() to create such struct.
- * @gras_msg_free() to get ride of it.
- * @gras_msg_ctn() to read its content.
- *
- */
-typedef struct {
- /* public */
- gras_socket_t *sock; /** the socket on which the message was received (to answer) */
-
- /* private */
- gras_msgheader_t *header;
- gras_msgentry_t *entry;
- unsigned int *dataCount;
- void **data;
- e_gras_free_directive_t freeDirective;
-} gras_msg_t;
-
-/**
- * gras_msgtype_register:
- * @msgId: identificator of such messages
- * @name: name as it should be used for logging messages
- * @sequence_count: number of groups in variadics
- * @Varargs: List of (const DataDescriptor *, int DDcount), describing the
- * elements in each sequence (DDlength is the length of the corresponding
- * DataDescriptor).
- * @Returns: the error code (or no_error).
- *
- * Registers a message to the GRAS mecanism.
- */
-gras_error_t
-gras_msgtype_register(gras_msgid_t msgId,
- const char *name,
- int sequence_count,
- ...);
-
-/**
- * gras_msg_new_and_send:
- * @sd: Socket on which the message should be sent
- * @msgId: identificator this messages
- * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
- * The number of sequences is given by the registration of ht
- * @Returns: the error code (or no_error).
- *
- * Create a new message, and send it on the network through the given socket.
- */
-gras_error_t
-gras_msg_new_and_send(gras_socket_t *sd,
- gras_msgid_t msgId,
- int seqCount,
- ...);
-
-
-/**
- * gras_msg_new:
- * @msgId: identificator this messages
- * @free_data_on_free: boolean indicating wheater the data must be freed when the msg get freed.
- * @seqCount: number of sequences in this message (must be the same than the value
- * registered using gras_msgtype_register() for that msgId)
- * @Varargs: List of (void **data, int seqLen) forming the payload of the message.
- * The number of sequences is given by the registration of ht
- * @Returns: the message built or NULL on error
- *
- * Build a message to be sent
- */
-
-gras_msg_t *gras_msg_new(gras_msgid_t msgId,
- e_gras_free_directive_t free_data_on_free,
- int seqCount,
- ...);
-
-/**
- * gras_msg_new_va:
- *
- * Build a new message in the exact same way than gras_msg_new(), but taking its arguments as
- * variadic ones.
- */
-gras_msg_t *gras_msg_new_va(gras_msgid_t msgId,
- e_gras_free_directive_t free_data,
- int seqCount,
- va_list ap);
-
-/**
- * gras_msg_copy:
- * @msg: original to copy.
- *
- * Copy a message.
- */
+/* msgtype declaration and retrival */
+typedef struct s_gras_msgtype gras_msgtype_t;
-gras_msg_t *gras_msg_copy(gras_msg_t *msg);
+gras_error_t gras_msgtype_declare (const char *name,
+ gras_datadesc_type_t *payload,
+ gras_msgtype_t **dst);
+gras_error_t gras_msgtype_declare_v(const char *name,
+ short int version,
+ gras_datadesc_type_t *payload,
+ gras_msgtype_t **dst);
-/**
- * gras_msg_free:
- * @msg: poor guy going to diediedie.
- *
- * Free a msg built with gras_msg_new().
- */
-void gras_msg_free(gras_msg_t *msg);
+gras_error_t gras_msgtype_by_name (const char *name,
+ gras_msgtype_t **dst);
+gras_error_t gras_msgtype_by_namev(const char *name,
+ short int version,
+ gras_msgtype_t **dst);
-/**
- * gras_msg_ctn:
- * @msg: the carrier of the data
- * @sequence: Sequence in which you want to see the data.
- * @num: Number in this sequence of the element to access.
- * @type: type of the element to access.
- *
- * Access to the content of a message.
- */
-#define gras_msg_ctn(msg,sequence,num,type) \
- ((type *)msg->data[sequence])[num]
/**
* gras_cb_t:
* @msg: The message itself
- * @Returns: true if the message was accepted by the callback and false if it should be passed to the next one.
+ * @Returns: true if the message was consumed by the callback.
*
* Type of message callback functions. Once a such a function is registered to
* handle messages of a given type with RegisterCallback(), it will be called
*
* If the callback accepts the message, it should free it after use.
*/
-
-typedef int (*gras_cb_t)(gras_msg_t *msg);
-
-/**
- * gras_cb_register:
- * @message: id of the concerned messages
- * @TTL: How many time should this callback be used
- * @cb: The callback.
- * @Returns: the error code (or no_error).
- *
- * Indicates a desire that the function #cb# be called whenever a
- * #message# message comes in.
- * #TTL# is how many time this callback should be used. After that, this
- * callback will be unregistred. If <0, the callback will never be unregistered.
- * (ie, it will be permanent)
- */
-gras_error_t
-gras_cb_register(gras_msgid_t message,
- int TTL,
- gras_cb_t cb);
-
-/**
- * gras_msg_handle:
- * @timeOut: How long to wait for incoming messages
- * @Returns: the error code (or no_error).
- *
- * Waits up to #timeOut# seconds to see if a message comes in; if so, calls the
- * registered listener for that message (see RegisterCallback()).
- */
+typedef int (*gras_cb_t)(gras_socket_t *expeditor,
+ void *payload);
+gras_error_t gras_cb_register (gras_msgtype_t *msgtype,
+ gras_cb_t cb);
+void gras_cb_unregister(gras_msgtype_t *msgtype,
+ gras_cb_t cb);
+
+gras_error_t gras_msg_send(gras_socket_t *sock,
+ gras_msgtype_t *msgtype,
+ void *payload);
+gras_error_t gras_msg_wait(double timeout,
+ gras_msgtype_t *msgt_want,
+ gras_socket_t **expeditor,
+ void *payload);
gras_error_t gras_msg_handle(double timeOut);
-/**
- * gras_msg_send:
- * @sd: Socket to write on
- * @msg: to send (build it with @gras_msg_new())
- * @freeDirective: if the msg passed as argument should be gras_msg_free'ed after sending.
- * @Returns: the error code (or no_error).
- *
- * Sends the message on the socket sd using an automatic and adaptative timeout.
- */
-
-gras_error_t
-gras_msg_send(gras_socket_t *sd,
- gras_msg_t *msg,
- e_gras_free_directive_t freeDirective);
-
-/**
- * gras_msg_wait:
- * @timeout: How long should we wait for this message.
- * @id: id of awaited msg
- * @message: where to store the message when it comes.
- * @Returns: the error code (or no_error).
- *
- * Waits for a message to come in over a given socket.
- *
- * Every message of another type received before the one waited will be queued
- * and used by subsequent call to this function or MsgHandle().
- */
-gras_error_t
-gras_msg_wait(double timeout,
- gras_msgid_t id,
- gras_msg_t **message);
-
-
END_DECL
#endif /* GRAS_MSG_H */
