[GNUnet-SVN] r34087 - in gnunet/src: include util

[gnunet]

Author: tg
Date: 2014-07-30 23:18:05 +0200 (Wed, 30 Jul 2014)
New Revision: 34087

Modified:
   gnunet/src/include/gnunet_client_manager_lib.h
   gnunet/src/util/client_manager.c
Log:
client manager: documentation

Modified: gnunet/src/include/gnunet_client_manager_lib.h
===================================================================
--- gnunet/src/include/gnunet_client_manager_lib.h      2014-07-30 18:42:37 UTC 
(rev 34086)
+++ gnunet/src/include/gnunet_client_manager_lib.h      2014-07-30 21:18:05 UTC 
(rev 34087)
@@ -99,11 +99,12 @@
 /**
  * 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
+ * @param cfg
+ *        Configuration to use.
+ * @param service_name
+ *        Service name to connect to.
+ * @param handlers
+ *        Message handlers.
  *
  * @return Client manager connection handle.
  */
@@ -117,22 +118,27 @@
 /**
  * Disconnect from the service.
  *
- * @param mgr             Client manager connection.
- * @param transmit_queue  Transmit pending messages in queue before 
disconnecting.
- * @param disconnect_cb   Function called after disconnected from the service.
- * @param disconnect_cls  Closure for @a disconnect_cb.
+ * @param mgr
+ *        Client manager connection.
+ * @param transmit_queue
+ *        Transmit pending messages in queue before disconnecting.
+ * @param disconnect_cb
+ *        Function called after disconnected from the service.
+ * @param cls
+ *        Closure for @a disconnect_cb.
  */
 void
 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
                                   int transmit_queue,
                                   GNUNET_ContinuationCallback disconnect_cb,
-                                  void *disconnect_cls);
+                                  void *cls);
 
 
 /**
  * Reschedule connect to the service using exponential back-off.
  *
- * @param mgr  Client manager connection.
+ * @param mgr
+ *        Client manager connection.
  */
 void
 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
@@ -141,8 +147,11 @@
 /**
  * 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.
+ * @param mgr
+ *        Client manager connection.
+ * @param msg
+ *        Message to transmit, should be allocated with GNUNET_malloc() or
+ *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
  */
 void
 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
@@ -152,8 +161,11 @@
 /**
  * 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.
+ * @param mgr
+ *        Client manager connection.
+ * @param msg
+ *        Message to transmit, should be allocated with GNUNET_malloc() or
+ *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
  */
 void
 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection 
*mgr,
@@ -163,7 +175,8 @@
 /**
  * Drop all queued messages.
  *
- * @param mgr  Client manager connection.
+ * @param mgr
+ *        Client manager connection.
  */
 void
 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection 
*mgr);
@@ -172,7 +185,8 @@
 /**
  * Obtain client connection handle.
  *
- * @param mgr  Client manager connection handle.
+ * @param mgr
+ *        Client manager connection.
  *
  * @return Client connection handle.
  */
@@ -184,9 +198,10 @@
  * 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.
+ * @param mgr
+ *        Client manager connection.
+ * @param size
+ *        Number of bytes in user context struct (for verification only).
  */
 void *
 GNUNET_CLIENT_MANAGER_get_user_context_ (struct 
GNUNET_CLIENT_MANAGER_Connection *mgr,
@@ -197,9 +212,10 @@
  * 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).
+ * @param mgr
+ *        Client manager connection.
+ * @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,
@@ -210,9 +226,12 @@
 /**
  * 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 *'.
+ * @param mgr
+ *        Client manager connection.
+ * @param ctx
+ *        User context.
+ * @param size
+ *        Number of bytes in user context struct (for verification only).
  */
 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type)               \
   (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
@@ -221,8 +240,10 @@
 /**
  * Set user context to be associated with the given client manager.
  *
- * @param mgr  Client manager connection.
- * @param ctx  Pointer to user context.
+ * @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))

Modified: gnunet/src/util/client_manager.c
===================================================================
--- gnunet/src/util/client_manager.c    2014-07-30 18:42:37 UTC (rev 34086)
+++ gnunet/src/util/client_manager.c    2014-07-30 21:18:05 UTC (rev 34087)
@@ -207,9 +207,12 @@
 /**
  * Transmit next message to service.
  *
- * @param cls  The struct GNUNET_PSYC_Channel.
- * @param size Number of bytes available in @a buf.
- * @param buf  Where to copy the message.
+ * @param cls
+ *        struct GNUNET_CLIENT_MANAGER_Connection
+ * @param size
+ *        Number of bytes available in @a buf.
+ * @param buf
+ *        Where to copy the message.
  *
  * @return Number of bytes copied to @a buf.
  */
@@ -292,8 +295,10 @@
 /**
  * Try again to connect to the service.
  *
- * @param cls Channel handle.
- * @param tc Scheduler context.
+ * @param cls
+ *        Channel handle.
+ * @param tc
+ *        Scheduler context.
  */
 static void
 schedule_reconnect (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
@@ -314,9 +319,12 @@
 /**
  * Connect to service.
  *
- * @param cfg           Configuration to use.
- * @param service_name  Service name to connect to.
- * @param handlers      Message handlers.
+ * @param cfg
+ *        Configuration to use.
+ * @param service_name
+ *        Service name to connect to.
+ * @param handlers
+ *        Message handlers.
  *
  * @return Client manager connection handle.
  */
@@ -340,20 +348,24 @@
 /**
  * Disconnect from the service.
  *
- * @param mgr             Client manager connection.
- * @param transmit_queue  Transmit pending messages in queue before 
disconnecting.
- * @param disconnect_cb   Function called after disconnected from the service.
- * @param disconnect_cls  Closure for @a disconnect_cb.
+ * @param mgr
+ *        Client manager connection.
+ * @param transmit_queue
+ *        Transmit pending messages in queue before disconnecting.
+ * @param disconnect_cb
+ *        Function called after disconnected from the service.
+ * @param cls
+ *        Closure for @a disconnect_cb.
  */
 void
 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
                                   int transmit_queue,
                                   GNUNET_ContinuationCallback disconnect_cb,
-                                  void *disconnect_cls)
+                                  void *cls)
 {
   LOG (GNUNET_ERROR_TYPE_DEBUG, "Disconnecting (%d)\n", transmit_queue);
   mgr->disconnect_cb = disconnect_cb;
-  mgr->disconnect_cls = disconnect_cls;
+  mgr->disconnect_cls = cls;
   if (NULL != mgr->tmit_head)
   {
     if (GNUNET_YES == transmit_queue)
@@ -395,7 +407,8 @@
 /**
  * Reschedule connect to the service using exponential back-off.
  *
- * @param mgr  Client manager connection.
+ * @param mgr
+ *        Client manager connection.
  */
 void
 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr)
@@ -426,8 +439,11 @@
 /**
  * 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.
+ * @param mgr
+ *        Client manager connection.
+ * @param msg
+ *        Message to transmit, should be allocated with GNUNET_malloc() or
+ *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
  */
 void
 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
@@ -443,8 +459,11 @@
 /**
  * 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.
+ * @param mgr
+ *        Client manager connection.
+ * @param msg
+ *        Message to transmit, should be allocated with GNUNET_malloc() or
+ *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
  */
 void
 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection 
*mgr,
@@ -460,7 +479,8 @@
 /**
  * Drop all queued messages.
  *
- * @param mgr  Client manager connection.
+ * @param mgr
+ *        Client manager connection.
  */
 void
 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr)
@@ -479,7 +499,8 @@
 /**
  * Obtain client connection handle.
  *
- * @param mgr  Client manager connection handle.
+ * @param mgr
+ *        Client manager connection.
  *
  * @return Client connection handle.
  */
@@ -494,8 +515,11 @@
  * Return user context associated with the given client.
  * 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).
+ * @param mgr
+ *        Client manager connection.
+ * @param size
+ *        Number of bytes in user context struct (for verification only).
+ *
  * @return User context.
  */
 void *
@@ -514,9 +538,12 @@
  * Set user context to be associated with the given client.
  * 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).
+ * @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,