src/include/gnunet_client_manager_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2013 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_client_manager_lib.h
  23  * @brief Client manager; higher level client API with transmission queue
  24  * and message handler registration.
  25  * @author Gabor X Toth
  26  * @defgroup client_manager  Higher level client-side communication with services.
  27  * @{
  28  */
  29 #ifndef GNUNET_CLIENT_MANAGER_LIB_H
  30 #define GNUNET_CLIENT_MANAGER_LIB_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40
  41 /**
  42  * Client manager connection handle.
  43  */
  44 struct GNUNET_CLIENT_MANAGER_Connection;
  45
  46
  47 /**
  48  * Functions with this signature are called whenever a message is
  49  * received.
  50  *
  51  * @param cls closure
  52  * @param client identification of the client
  53  * @param message the actual message
  54  */
  55 typedef void
  56 (*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
  57                                           struct GNUNET_CLIENT_MANAGER_Connection *mgr,
  58                                           const struct GNUNET_MessageHeader *msg);
  59
  60
  61 /**
  62  * Message handler.  Each struct specifies how to handle on particular
  63  * type of message received.
  64  */
  65 struct GNUNET_CLIENT_MANAGER_MessageHandler
  66 {
  67   /**
  68    * Function to call for messages of @a type.
  69    */
  70   GNUNET_CLIENT_MANAGER_MessageCallback callback;
  71
  72   /**
  73    * Closure argument for @a callback.
  74    */
  75   void *callback_cls;
  76
  77   /**
  78    * Type of the message this handler covers.
  79    * Use 0 to handle loss of connection.
  80    */
  81   uint16_t type;
  82
  83   /**
  84    * Expected size of messages of this type.  Use 0 to skip size check.
  85    * If non-zero, messages of the given type will be discarded
  86    * (and the connection closed) if they do not have the right size.
  87    */
  88   uint16_t expected_size;
  89
  90   /**
  91    * #GNUNET_NO for fixed-size messages.
  92    * #GNUNET_YES if the message size can vary.
  93    * In this case @a expected_size is treated as minimum size.
  94    */
  95   uint8_t is_variable_size;
  96 };
  97
  98
  99 /**
 100  * Connect to a service.
 101  *
 102  * @param cfg                 Configuration to use.
 103  * @param service_name        Service name to connect to.
 104  * @param connect_msg         FIXME
 105  * @param connection_lost_cb  x
 106  * @param cls
 107  *
 108  * @return Client manager connection handle.
 109  */
 110 struct GNUNET_CLIENT_MANAGER_Connection *
 111 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 112                                const char *service_name,
 113                                const struct
 114                                GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
 115
 116
 117 /**
 118  * Disconnect from the service.
 119  *
 120  * @param mgr             Client manager connection.
 121  * @param transmit_queue  Transmit pending messages in queue before disconnecting.
 122  */
 123 void
 124 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 125                                   int transmit_queue);
 126
 127
 128 /**
 129  * Reschedule connect to the service using exponential back-off.
 130  *
 131  * @param mgr  Client manager connection.
 132  */
 133 void
 134 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 135
 136
 137 /**
 138  * Add a message to the end of the transmission queue.
 139  *
 140  * @param mgr  Client manager connection.
 141  * @param msg  Message to transmit.  It is free()'d after transmission.
 142  */
 143 void
 144 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 145                                 struct GNUNET_MessageHeader *msg);
 146
 147
 148 /**
 149  * Add a message to the beginning of the transmission queue.
 150  *
 151  * @param mgr  Client manager connection.
 152  * @param msg  Message to transmit.  It is free()'d after transmission.
 153  */
 154 void
 155 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 156                                     struct GNUNET_MessageHeader *msg);
 157
 158
 159 /**
 160  * Drop all queued messages.
 161  *
 162  * @param mgr  Client manager connection.
 163  */
 164 void
 165 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 166
 167
 168 /**
 169  * Obtain client connection handle.
 170  *
 171  * @param mgr  Client manager connection handle.
 172  *
 173  * @return Client connection handle.
 174  */
 175 struct GNUNET_CLIENT_Connection *
 176 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 177
 178
 179 /**
 180  * Return user context associated with the given client manager.
 181  * Note: you should probably use the macro (call without the underscore).
 182  *
 183  * @param mgr  Client manager connection.
 184  * @param size Number of bytes in user context struct (for verification only).
 185  * @return User context.
 186  */
 187 void *
 188 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 189                                          size_t size);
 190
 191
 192 /**
 193  * Set user context to be associated with the given client manager.
 194  * Note: you should probably use the macro (call without the underscore).
 195  *
 196  * @param mgr  Client manager connection.
 197  * @param ctx  User context.
 198  * @param size Number of bytes in user context struct (for verification only).
 199  */
 200 void
 201 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 202                                          void *ctx,
 203                                          size_t size);
 204
 205
 206 /**
 207  * Return user context associated with the given client manager.
 208  *
 209  * @param mgr  Client manager connection.
 210  * @param type Expected return type (i.e. 'struct Foo')
 211  * @return Pointer to user context of type 'type *'.
 212  */
 213 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type)               \
 214   (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
 215
 216
 217 /**
 218  * Set user context to be associated with the given client manager.
 219  *
 220  * @param mgr  Client manager connection.
 221  * @param ctx  Pointer to user context.
 222  */
 223 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx)                 \
 224   GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
 225
 226
 227 #if 0                           /* keep Emacsens' auto-indent happy */
 228 {
 229 #endif
 230 #ifdef __cplusplus
 231 }
 232 #endif
 233
 234 /** @} */ /* end of group client_manager */
 235
 236 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
 237 #endif
 238 /* end of gnunet_client_manager_lib.h */