client manager: higher level client API with a transmission queue and message handler registration

2 files changed, 239 insertions, 0 deletions

diff --git a/src/include/gnunet_client_manager_lib.h b/src/include/gnunet_client_manager_lib.h
new file mode 100644
index 000000000..6ed2ddb17
--- /dev/null
+++ b/src/include/gnunet_client_manager_lib.h
@@ -0,0 +1,238 @@
+/*
+     This file is part of GNUnet.
+     (C) 2013 Christian Grothoff (and other contributing authors)
+
+     GNUnet is free software; you can redistribute it and/or modify
+     it under the terms of the GNU General Public License as published
+     by the Free Software Foundation; either version 3, or (at your
+     option) any later version.
+
+     GNUnet is distributed in the hope that it will be useful, but
+     WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     General Public License for more details.
+
+     You should have received a copy of the GNU General Public License
+     along with GNUnet; see the file COPYING.  If not, write to the
+     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+     Boston, MA 02111-1307, USA.
+*/
+
+/**
+ * @file include/gnunet_client_manager_lib.h
+ * @brief Client manager; higher level client API with transmission queue
+ * and message handler registration.
+ * @author Gabor X Toth
+ * @defgroup client_manager  Higher level client-side communication with services.
+ * @{
+ */
+#ifndef GNUNET_CLIENT_MANAGER_LIB_H
+#define GNUNET_CLIENT_MANAGER_LIB_H
+
+#ifdef __cplusplus
+extern "C"
+{
+#if 0                           /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+
+
+/**
+ * Client manager connection handle.
+ */
+struct GNUNET_CLIENT_MANAGER_Connection;
+
+
+/**
+ * Functions with this signature are called whenever a message is
+ * received.
+ *
+ * @param cls closure
+ * @param client identification of the client
+ * @param message the actual message
+ */
+typedef void
+(*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
+                                          struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                          const struct GNUNET_MessageHeader *msg);
+
+
+/**
+ * Message handler.  Each struct specifies how to handle on particular
+ * type of message received.
+ */
+struct GNUNET_CLIENT_MANAGER_MessageHandler
+{
+  /**
+   * Function to call for messages of @a type.
+   */
+  GNUNET_CLIENT_MANAGER_MessageCallback callback;
+
+  /**
+   * Closure argument for @a callback.
+   */
+  void *callback_cls;
+
+  /**
+   * Type of the message this handler covers.
+   * Use 0 to handle loss of connection.
+   */
+  uint16_t type;
+
+  /**
+   * Expected size of messages of this type.  Use 0 to skip size check.
+   * If non-zero, messages of the given type will be discarded
+   * (and the connection closed) if they do not have the right size.
+   */
+  uint16_t expected_size;
+
+  /**
+   * #GNUNET_NO for fixed-size messages.
+   * #GNUNET_YES if the message size can vary.
+   * In this case @a expected_size is treated as minimum size.
+   */
+  uint8_t is_variable_size;
+};
+
+
+/**
+ * Connect to a service.
+ *
+ * @param cfg                 Configuration to use.
+ * @param service_name        Service name to connect to.
+ * @param connect_msg         FIXME
+ * @param connection_lost_cb  x
+ * @param cls
+ *
+ * @return Client manager connection handle.
+ */
+struct GNUNET_CLIENT_MANAGER_Connection *
+GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                               const char *service_name,
+                               const struct
+                               GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
+
+
+/**
+ * Disconnect from the service.
+ *
+ * @param mgr             Client manager connection.
+ * @param transmit_queue  Transmit pending messages in queue before disconnecting.
+ */
+void
+GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                  int transmit_queue);
+
+
+/**
+ * Reschedule connect to the service using exponential back-off.
+ *
+ * @param mgr  Client manager connection.
+ */
+void
+GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
+
+
+/**
+ * Add a message to the end of the transmission queue.
+ *
+ * @param mgr  Client manager connection.
+ * @param msg  Message to transmit.  It is free()'d after transmission.
+ */
+void
+GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                struct GNUNET_MessageHeader *msg);
+
+
+/**
+ * Add a message to the beginning of the transmission queue.
+ *
+ * @param mgr  Client manager connection.
+ * @param msg  Message to transmit.  It is free()'d after transmission.
+ */
+void
+GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                    struct GNUNET_MessageHeader *msg);
+
+
+/**
+ * Drop all queued messages.
+ *
+ * @param mgr  Client manager connection.
+ */
+void
+GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
+
+
+/**
+ * Obtain client connection handle.
+ *
+ * @param mgr  Client manager connection handle.
+ *
+ * @return Client connection handle.
+ */
+struct GNUNET_CLIENT_Connection *
+GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
+
+
+/**
+ * Return user context associated with the given client manager.
+ * Note: you should probably use the macro (call without the underscore).
+ *
+ * @param mgr  Client manager connection.
+ * @param size Number of bytes in user context struct (for verification only).
+ * @return User context.
+ */
+void *
+GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                         size_t size);
+
+
+/**
+ * Set user context to be associated with the given client manager.
+ * Note: you should probably use the macro (call without the underscore).
+ *
+ * @param mgr  Client manager connection.
+ * @param ctx  User context.
+ * @param size Number of bytes in user context struct (for verification only).
+ */
+void
+GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
+                                         void *ctx,
+                                         size_t size);
+
+
+/**
+ * Return user context associated with the given client manager.
+ *
+ * @param mgr  Client manager connection.
+ * @param type Expected return type (i.e. 'struct Foo')
+ * @return Pointer to user context of type 'type *'.
+ */
+#define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type)               \
+  (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
+
+
+/**
+ * Set user context to be associated with the given client manager.
+ *
+ * @param mgr  Client manager connection.
+ * @param ctx  Pointer to user context.
+ */
+#define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx)                 \
+  GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
+
+
+#if 0                           /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */ /* end of group client_manager */
+
+/* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
+#endif
+/* end of gnunet_client_manager_lib.h */
diff --git a/src/include/gnunet_util_lib.h b/src/include/gnunet_util_lib.h
index 0f62ba8db..352cffdac 100644
--- a/src/include/gnunet_util_lib.h
+++ b/src/include/gnunet_util_lib.h
@@ -41,6 +41,7 @@ extern "C"
 #include "gnunet_bio_lib.h"
 #include "gnunet_connection_lib.h"
 #include "gnunet_client_lib.h"
+#include "gnunet_client_manager_lib.h"
 #include "gnunet_container_lib.h"
 #include "gnunet_getopt_lib.h"
 #include "gnunet_helper_lib.h"