src/include/gnunet_op_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2016 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @file
  21  * Asynchronous operations; register callbacks for operations and call them when a response arrives.
  22  *
  23  * @author Gabor X Toth
  24  */
  25
  26 #ifndef GNUNET_OP_H
  27 #define GNUNET_OP_H
  28
  29 #include "gnunet_util_lib.h"
  30
  31 /**
  32  * Operations handle.
  33  */
  34 struct GNUNET_OP_Handle;
  35
  36
  37 /**
  38  * Create new operations handle.
  39  */
  40 struct GNUNET_OP_Handle *
  41 GNUNET_OP_create ();
  42
  43
  44 /**
  45  * Destroy operations handle.
  46  */
  47 void
  48 GNUNET_OP_destroy (struct GNUNET_OP_Handle *h);
  49
  50
  51 /**
  52  * Get a unique operation ID to distinguish between asynchronous requests.
  53  *
  54  * @param h
  55  *        Operations handle.
  56  *
  57  * @return Operation ID to use.
  58  */
  59 uint64_t
  60 GNUNET_OP_get_next_id (struct GNUNET_OP_Handle *h);
  61
  62
  63 /**
  64  * Find operation by ID.
  65  *
  66  * @param h
  67  *        Operations handle.
  68  * @param op_id
  69  *        Operation ID to look up.
  70  * @param[out] result_cb
  71  *        If an operation was found, its result callback is returned here.
  72  * @param[out] cls
  73  *        If an operation was found, its closure is returned here.
  74  * @param[out] ctx
  75  *        User context.
  76  *
  77  * @return #GNUNET_YES if an operation was found,
  78  *         #GNUNET_NO  if not found.
  79  */
  80 int
  81 GNUNET_OP_get (struct GNUNET_OP_Handle *h,
  82                uint64_t op_id,
  83                GNUNET_ResultCallback *result_cb,
  84                void **cls,
  85                void **ctx);
  86
  87
  88 /**
  89  * Add a new operation.
  90  *
  91  * @param h
  92  *        Operations handle.
  93  * @param result_cb
  94  *        Function to call with the result of the operation.
  95  * @param cls
  96  *        Closure for @a result_cb.
  97  * @param ctx
  98  *        User context.
  99  *
 100  * @return ID of the new operation.
 101  */
 102 uint64_t
 103 GNUNET_OP_add (struct GNUNET_OP_Handle *h,
 104                GNUNET_ResultCallback result_cb,
 105                void *cls,
 106                void *ctx);
 107
 108
 109 /**
 110  * Call the result callback of an operation and remove it.
 111  *
 112  * @param h
 113  *        Operations handle.
 114  * @param op_id
 115  *        Operation ID.
 116  * @param result_code
 117  *        Result of the operation.
 118  * @param data
 119  *        Data result of the operation.
 120  * @param data_size
 121  *        Size of @a data.
 122  * @param[out] ctx
 123  *        User context.
 124  *
 125  * @return #GNUNET_YES if the operation was found and removed,
 126  *         #GNUNET_NO  if the operation was not found.
 127  */
 128 int
 129 GNUNET_OP_result (struct GNUNET_OP_Handle *h,
 130                   uint64_t op_id,
 131                   int64_t result_code,
 132                   const void *data,
 133                   uint16_t data_size,
 134                   void **ctx);
 135
 136
 137 /**
 138  * Remove / cancel an operation.
 139  *
 140  * @param h
 141  *        Operations handle.
 142  * @param op_id
 143  *        Operation ID.
 144  *
 145  * @return #GNUNET_YES if the operation was found and removed,
 146  *         #GNUNET_NO  if the operation was not found.
 147  */
 148 int
 149 GNUNET_OP_remove (struct GNUNET_OP_Handle *h,
 150                   uint64_t op_id);
 151
 152
 153 #endif // GNUNET_OP_H