src/include/gnunet_client_manager_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (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
 103  *        Configuration to use.
 104  * @param service_name
 105  *        Service name to connect to.
 106  * @param handlers
 107  *        Message handlers.
 108  *
 109  * @return Client manager connection handle.
 110  */
 111 struct GNUNET_CLIENT_MANAGER_Connection *
 112 GNUNET_CLIENT_MANAGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 113                                const char *service_name,
 114                                const struct
 115                                GNUNET_CLIENT_MANAGER_MessageHandler *handlers);
 116
 117
 118 /**
 119  * Disconnect from the service.
 120  *
 121  * @param mgr
 122  *        Client manager connection.
 123  * @param transmit_queue
 124  *        Transmit pending messages in queue before disconnecting.
 125  * @param disconnect_cb
 126  *        Function called after disconnected from the service.
 127  * @param cls
 128  *        Closure for @a disconnect_cb.
 129  */
 130 void
 131 GNUNET_CLIENT_MANAGER_disconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 132                                   int transmit_queue,
 133                                   GNUNET_ContinuationCallback disconnect_cb,
 134                                   void *cls);
 135
 136
 137 /**
 138  * Reschedule connect to the service using exponential back-off.
 139  *
 140  * @param mgr
 141  *        Client manager connection.
 142  */
 143 void
 144 GNUNET_CLIENT_MANAGER_reconnect (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 145
 146
 147 /**
 148  * Add a message to the end of the transmission queue.
 149  *
 150  * @param mgr
 151  *        Client manager connection.
 152  * @param msg
 153  *        Message to transmit, should be allocated with GNUNET_malloc() or
 154  *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
 155  */
 156 void
 157 GNUNET_CLIENT_MANAGER_transmit (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 158                                 struct GNUNET_MessageHeader *msg);
 159
 160
 161 /**
 162  * Add a message to the beginning of the transmission queue.
 163  *
 164  * @param mgr
 165  *        Client manager connection.
 166  * @param msg
 167  *        Message to transmit, should be allocated with GNUNET_malloc() or
 168  *        GNUNET_new(), as it is freed with GNUNET_free() after transmission.
 169  */
 170 void
 171 GNUNET_CLIENT_MANAGER_transmit_now (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 172                                     struct GNUNET_MessageHeader *msg);
 173
 174
 175 /**
 176  * Drop all queued messages.
 177  *
 178  * @param mgr
 179  *        Client manager connection.
 180  */
 181 void
 182 GNUNET_CLIENT_MANAGER_drop_queue (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 183
 184
 185 /**
 186  * Obtain client connection handle.
 187  *
 188  * @param mgr
 189  *        Client manager connection.
 190  *
 191  * @return Client connection handle.
 192  */
 193 struct GNUNET_CLIENT_Connection *
 194 GNUNET_CLIENT_MANAGER_get_client (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 195
 196
 197 /**
 198  * Return user context associated with the given client manager.
 199  * Note: you should probably use the macro (call without the underscore).
 200  *
 201  * @param mgr
 202  *        Client manager connection.
 203  * @param size
 204  *        Number of bytes in user context struct (for verification only).
 205  */
 206 void *
 207 GNUNET_CLIENT_MANAGER_get_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 208                                          size_t size);
 209
 210
 211 /**
 212  * Set user context to be associated with the given client manager.
 213  * Note: you should probably use the macro (call without the underscore).
 214  *
 215  * @param mgr
 216  *        Client manager connection.
 217  * @param ctx
 218  *        User context.
 219  * @param size
 220  *        Number of bytes in user context struct (for verification only).
 221  */
 222 void
 223 GNUNET_CLIENT_MANAGER_set_user_context_ (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 224                                          void *ctx,
 225                                          size_t size);
 226
 227
 228 /**
 229  * Return user context associated with the given client manager.
 230  *
 231  * @param mgr
 232  *        Client manager connection.
 233  * @param type
 234  *        Type of context (for size verification).
 235  */
 236 #define GNUNET_CLIENT_MANAGER_get_user_context(mgr, type)               \
 237   (type *) GNUNET_CLIENT_MANAGER_get_user_context_ (mgr, sizeof (type))
 238
 239
 240 /**
 241  * Set user context to be associated with the given client manager.
 242  *
 243  * @param mgr
 244  *        Client manager connection.
 245  * @param ctx
 246  *        Pointer to user context.
 247  */
 248 #define GNUNET_CLIENT_MANAGER_set_user_context(mgr, ctx)                 \
 249   GNUNET_CLIENT_MANAGER_set_user_context_ (mgr, ctx, sizeof (*ctx))
 250
 251
 252 /**
 253  * Get a unique operation ID to distinguish between asynchronous requests.
 254  *
 255  * @param mgr
 256  *        Client manager connection.
 257  *
 258  * @return Operation ID to use.
 259  */
 260 uint64_t
 261 GNUNET_CLIENT_MANAGER_op_get_next_id (struct GNUNET_CLIENT_MANAGER_Connection *mgr);
 262
 263
 264 /**
 265  * Find operation by ID.
 266  *
 267  * @param mgr
 268  *        Client manager connection.
 269  * @param op_id
 270  *        Operation ID to look up.
 271  * @param[out] result_cb
 272  *        If an operation was found, its result callback is returned here.
 273  * @param[out] cls
 274  *        If an operation was found, its closure is returned here.
 275  *
 276  * @return #GNUNET_YES if an operation was found,
 277  *         #GNUNET_NO  if not found.
 278  */
 279 int
 280 GNUNET_CLIENT_MANAGER_op_find (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 281                                uint64_t op_id,
 282                                GNUNET_ResultCallback *result_cb,
 283                                void **cls);
 284
 285
 286 /**
 287  * Add a new operation.
 288  *
 289  * @param mgr
 290  *        Client manager connection.
 291  * @param result_cb
 292  *        Function to call with the result of the operation.
 293  * @param cls
 294  *        Closure for @a result_cb.
 295  *
 296  * @return ID of the new operation.
 297  */
 298 uint64_t
 299 GNUNET_CLIENT_MANAGER_op_add (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 300                               GNUNET_ResultCallback result_cb,
 301                               void *cls);
 302
 303
 304 /**
 305  * Call the result callback and remove the operation.
 306  *
 307  * @param mgr
 308  *        Client manager connection.
 309  * @param op_id
 310  *        Operation ID.
 311  * @param result_code
 312  *        Result of the operation.
 313  * @param data
 314  *        Data result of the operation.
 315  * @param data_size
 316  *        Size of @a data.
 317  *
 318  * @return #GNUNET_YES if the operation was found and removed,
 319  *         #GNUNET_NO  if the operation was not found.
 320  */
 321 int
 322 GNUNET_CLIENT_MANAGER_op_result (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 323                                  uint64_t op_id, int64_t result_code,
 324                                  const void *data, uint16_t data_size);
 325
 326
 327 /**
 328  * Cancel an operation.
 329  *
 330  * @param mgr
 331  *        Client manager connection.
 332  * @param op_id
 333  *        Operation ID.
 334  *
 335  * @return #GNUNET_YES if the operation was found and removed,
 336  *         #GNUNET_NO  if the operation was not found.
 337  */
 338 int
 339 GNUNET_CLIENT_MANAGER_op_cancel (struct GNUNET_CLIENT_MANAGER_Connection *mgr,
 340                                  uint64_t op_id);
 341
 342
 343 #if 0                           /* keep Emacsens' auto-indent happy */
 344 {
 345 #endif
 346 #ifdef __cplusplus
 347 }
 348 #endif
 349
 350 /** @} */ /* end of group client_manager */
 351
 352 /* ifndef GNUNET_CLIENT_MANAGER_LIB_H */
 353 #endif
 354 /* end of gnunet_client_manager_lib.h */