src/include/gnunet_client_manager_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 GNUnet e.V.
   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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Gabor X Toth
  23  *
  24  * @file
  25  * Client manager; higher level client API with transmission queue
  26  * and message handler registration.
  27  *
  28  * @defgroup client-manager  Client manager library
  29  * Higher level client-side communication with services.
  30  *
  31  * Provides a higher level client API
  32  * with transmission queue and message handler registration.
  33  * @{
  34  */
  35 #ifndef GNUNET_CLIENT_MANAGER_LIB_H
  36 #define GNUNET_CLIENT_MANAGER_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46
  47 /**
  48  * Client manager connection handle.
  49  */
  50 struct GNUNET_CLIENT_MANAGER_Connection;
  51
  52
  53 /**
  54  * Functions with this signature are called whenever a message is
  55  * received.
  56  *
  57  * @param cls closure
  58  * @param client identification of the client
  59  * @param message the actual message
  60  */
  61 typedef void
  62 (*GNUNET_CLIENT_MANAGER_MessageCallback) (void *cls,
  63                                           struct GNUNET_CLIENT_MANAGER_Connection *mgr,
  64                                           const struct GNUNET_MessageHeader *msg);
  65
  66
  67 /**
  68  * Message handler.  Each struct specifies how to handle on particular
  69  * type of message received.
  70  */
  71 struct GNUNET_CLIENT_MANAGER_MessageHandler
  72 {
  73   /**
  74    * Function to call for messages of @a type.
  75    */
  76   GNUNET_CLIENT_MANAGER_MessageCallback callback;
  77
  78   /**
  79    * Closure argument for @a callback.
  80    */
  81   void *callback_cls;
  82
  83   /**
  84    * Type of the message this handler covers.
  85    * Use 0 to handle loss of connection.
  86    */
  87   uint16_t type;
  88
  89   /**
  90    * Expected size of messages of this type.  Use 0 to skip size check.
  91    * If non-zero, messages of the given type will be discarded
  92    * (and the connection closed) if they do not have the right size.
  93    */
  94   uint16_t expected_size;
  95
  96   /**
  97    * #GNUNET_NO for fixed-size messages.
  98    * #GNUNET_YES if the message size can vary.
  99    * In this case @a expected_size is treated as minimum size.
 100    */
 101   uint8_t is_variable_size;
 102 };
 103
 104
 105 /**
 106  * Connect to a service.
 107  *
 108  * @param cfg
 109  *        Configuration to use.
 110  * @param service_name
 111  *        Service name to connect to.
 112  * @param handlers
 113  *        Message handlers.
 114  *
 115  * @return Client manager connection handle.
 116  */
 117 struct GNUNET_CLIENT_MANAGER_Connection *
 118 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 119                                const char *service_name,
 120                                const struct
 121                                GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
 122
 123
 124 /**
 125  * Disconnect from the service.
 126  *
 127  * @param mgr
 128  *        Client manager connection.
 129  * @param transmit_queue
 130  *        Transmit pending messages in queue before disconnecting.
 131  * @param disconnect_cb
 132  *        Function called after disconnected from the service.
 133  * @param cls
 134  *        Closure for @a disconnect_cb.
 135  */
 136 void
 137 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 138                                   int transmit_queue,
 139                                   GNUNET_ContinuationCallback disconnect_cb,
 140                                   void *cls);
 141
 142
 143 /**
 144  * Reschedule connect to the service using exponential back-off.
 145  *
 146  * @param mgr
 147  *        Client manager connection.
 148  */
 149 void
 150 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 151
 152
 153 /**
 154  * Add a message to the end of the transmission queue.
 155  *
 156  * @param mgr
 157  *        Client manager connection.
 158  * @param msg
 159  *        Message to transmit, should be allocated with GNUNET_malloc() or
 160  *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
 161  */
 162 void
 163 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 164                                 struct GNUNET_MessageHeader *msg);
 165
 166
 167 /**
 168  * Add a message to the beginning of the transmission queue.
 169  *
 170  * @param mgr
 171  *        Client manager connection.
 172  * @param msg
 173  *        Message to transmit, should be allocated with GNUNET_malloc() or
 174  *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
 175  */
 176 void
 177 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 178                                     struct GNUNET_MessageHeader *msg);
 179
 180
 181 /**
 182  * Drop all queued messages.
 183  *
 184  * @param mgr
 185  *        Client manager connection.
 186  */
 187 void
 188 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 189
 190
 191 /**
 192  * Obtain client connection handle.
 193  *
 194  * @param mgr
 195  *        Client manager connection.
 196  *
 197  * @return Client connection handle.
 198  */
 199 struct GNUNET_CLIENT_Connection *
 200 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 201
 202
 203 /**
 204  * Return user context associated with the given client manager.
 205  * Note: you should probably use the macro (call without the underscore).
 206  *
 207  * @param mgr
 208  *        Client manager connection.
 209  * @param size
 210  *        Number of bytes in user context struct (for verification only).
 211  */
 212 void *
 213 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 214                                          size_t size);
 215
 216
 217 /**
 218  * Set user context to be associated with the given client manager.
 219  * Note: you should probably use the macro (call without the underscore).
 220  *
 221  * @param mgr
 222  *        Client manager connection.
 223  * @param ctx
 224  *        User context.
 225  * @param size
 226  *        Number of bytes in user context struct (for verification only).
 227  */
 228 void
 229 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 230                                          void *ctx,
 231                                          size_t size);
 232
 233
 234 /**
 235  * Return user context associated with the given client manager.
 236  *
 237  * @param mgr
 238  *        Client manager connection.
 239  * @param type
 240  *        Type of context (for size verification).
 241  */
 242 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type)               \
 243   (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
 244
 245
 246 /**
 247  * Set user context to be associated with the given client manager.
 248  *
 249  * @param mgr
 250  *        Client manager connection.
 251  * @param ctx
 252  *        Pointer to user context.
 253  */
 254 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx)                 \
 255   GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
 256
 257
 258 /**
 259  * Get a unique operation ID to distinguish between asynchronous requests.
 260  *
 261  * @param mgr
 262  *        Client manager connection.
 263  *
 264  * @return Operation ID to use.
 265  */
 266 uint64_t
 267 GNUNET_CLIENT_MANAGER_op_get_next_id (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 268
 269
 270 /**
 271  * Find operation by ID.
 272  *
 273  * @param mgr
 274  *        Client manager connection.
 275  * @param op_id
 276  *        Operation ID to look up.
 277  * @param[out] result_cb
 278  *        If an operation was found, its result callback is returned here.
 279  * @param[out] cls
 280  *        If an operation was found, its closure is returned here.
 281  *
 282  * @return #GNUNET_YES if an operation was found,
 283  *         #GNUNET_NO  if not found.
 284  */
 285 int
 286 GNUNET_CLIENT_MANAGER_op_find (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 287                                uint64_t op_id,
 288                                GNUNET_ResultCallback *result_cb,
 289                                void **cls);
 290
 291
 292 /**
 293  * Add a new operation.
 294  *
 295  * @param mgr
 296  *        Client manager connection.
 297  * @param result_cb
 298  *        Function to call with the result of the operation.
 299  * @param cls
 300  *        Closure for @a result_cb.
 301  *
 302  * @return ID of the new operation.
 303  */
 304 uint64_t
 305 GNUNET_CLIENT_MANAGER_op_add (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 306                               GNUNET_ResultCallback result_cb,
 307                               void *cls);
 308
 309
 310 /**
 311  * Call the result callback and remove the operation.
 312  *
 313  * @param mgr
 314  *        Client manager connection.
 315  * @param op_id
 316  *        Operation ID.
 317  * @param result_code
 318  *        Result of the operation.
 319  * @param data
 320  *        Data result of the operation.
 321  * @param data_size
 322  *        Size of @a data.
 323  *
 324  * @return #GNUNET_YES if the operation was found and removed,
 325  *         #GNUNET_NO  if the operation was not found.
 326  */
 327 int
 328 GNUNET_CLIENT_MANAGER_op_result (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 329                                  uint64_t op_id, int64_t result_code,
 330                                  const void *data, uint16_t data_size);
 331
 332
 333 /**
 334  * Cancel an operation.
 335  *
 336  * @param mgr
 337  *        Client manager connection.
 338  * @param op_id
 339  *        Operation ID.
 340  *
 341  * @return #GNUNET_YES if the operation was found and removed,
 342  *         #GNUNET_NO  if the operation was not found.
 343  */
 344 int
 345 GNUNET_CLIENT_MANAGER_op_cancel (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 346                                  uint64_t op_id);
 347
 348
 349 #if 0                           /* keep Emacsens' auto-indent happy */
 350 {
 351 #endif
 352 #ifdef __cplusplus
 353 }
 354 #endif
 355
 356 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
 357 #endif
 358
 359 /** @} */ /* end of group */