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