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