src/include/gnunet_scalarproduct_service.h

   1 /*
   2       This file is part of GNUnet.
   3       Copyright (C) 2013, 2014 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  * @author Christian M. Fuchs
  23  * @author Gaurav Kukreja
  24  *
  25  * @file
  26  * API to the scalarproduct service
  27  *
  28  * @defgroup scalarproduct  Scalar Product service
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_SCALARPRODUCT_SERVICE_H
  33 #define GNUNET_SCALARPRODUCT_SERVICE_H
  34 #define GCRYPT_NO_DEPRECATED
  35 #include <gcrypt.h>
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44 /**
  45  * Version of the scalarproduct API.
  46  */
  47 #define GNUNET_SCALARPRODUCT_VERSION 0x00000044
  48
  49 /**
  50  * Result status values for the computation.
  51  */
  52 enum GNUNET_SCALARPRODUCT_ResponseStatus
  53 {
  54
  55   /**
  56    * Operation is still active (never returned, used internally).
  57    */
  58   GNUNET_SCALARPRODUCT_STATUS_INIT = 0,
  59
  60   /**
  61    * Operation is still active (never returned, used internally).
  62    */
  63   GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1,
  64
  65   /**
  66    * The computation was successful.
  67    */
  68   GNUNET_SCALARPRODUCT_STATUS_SUCCESS,
  69
  70   /**
  71    * We encountered some error.
  72    */
  73   GNUNET_SCALARPRODUCT_STATUS_FAILURE,
  74
  75   /**
  76    * We got an invalid response.
  77    */
  78   GNUNET_SCALARPRODUCT_STATUS_INVALID_RESPONSE,
  79
  80   /**
  81    * We got disconnected from the SCALARPRODUCT service.
  82    */
  83   GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED
  84 };
  85
  86
  87 /**
  88  * Opaque declaration of the SP-Handle
  89  */
  90 struct GNUNET_SCALARPRODUCT_Handle;
  91
  92
  93 GNUNET_NETWORK_STRUCT_BEGIN
  94
  95 /**
  96  * An element key-value pair for scalarproduct
  97  */
  98 struct GNUNET_SCALARPRODUCT_Element
  99 {
 100   /**
 101    * Key used to identify matching pairs of values to multiply.
 102    */
 103   struct GNUNET_HashCode key;
 104
 105   /**
 106    * Value to multiply in scalar product, in NBO.
 107    */
 108   int64_t value GNUNET_PACKED;
 109 };
 110
 111 GNUNET_NETWORK_STRUCT_END
 112
 113
 114 /**
 115  * Continuation called to notify client about result of the
 116  * operation.
 117  *
 118  * @param cls closure
 119  * @param status Status of the request
 120  */
 121 typedef void
 122 (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
 123                                                 enum GNUNET_SCALARPRODUCT_ResponseStatus status);
 124
 125
 126 /**
 127  * Process a datum that was stored in the scalarproduct.
 128  *
 129  * @param cls closure
 130  * @param status Status of the request
 131  * @param result result of the computation
 132  */
 133 typedef void
 134 (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
 135                                         enum GNUNET_SCALARPRODUCT_ResponseStatus status,
 136                                         gcry_mpi_t result);
 137
 138
 139 /**
 140  * Entry in the request queue per client
 141  */
 142 struct GNUNET_SCALARPRODUCT_ComputationHandle;
 143
 144
 145 /**
 146  * Request by Alice's client for computing a scalar product
 147  *
 148  * @param cfg the gnunet configuration handle
 149  * @param session_key Session key should be unique to the requesting client
 150  * @param peer PeerID of the other peer
 151  * @param elements Array of elements of the vector
 152  * @param element_count Number of elements in the @a elements vector
 153  * @param cont Callback function
 154  * @param cont_cls Closure for the @a cont callback function
 155  * @return a new handle for this computation
 156  */
 157 struct GNUNET_SCALARPRODUCT_ComputationHandle *
 158 GNUNET_SCALARPRODUCT_start_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
 159                               const struct GNUNET_HashCode *session_key,
 160                               const struct GNUNET_PeerIdentity *peer,
 161                               const struct GNUNET_SCALARPRODUCT_Element *elements,
 162                               uint32_t element_count,
 163                               GNUNET_SCALARPRODUCT_DatumProcessor cont,
 164                               void *cont_cls);
 165
 166
 167 /**
 168  * Used by Bob's client to cooperate with Alice,
 169  *
 170  * @param cfg the gnunet configuration handle
 171  * @param session_key Session key unique to the requesting client
 172  * @param elements Array of elements of the vector
 173  * @param element_count Number of elements in the @a elements vector
 174  * @param cont Callback function
 175  * @param cont_cls Closure for the @a cont callback function
 176  * @return a new handle for this computation
 177  */
 178 struct GNUNET_SCALARPRODUCT_ComputationHandle *
 179 GNUNET_SCALARPRODUCT_accept_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
 180                                          const struct GNUNET_HashCode *key,
 181                                          const struct GNUNET_SCALARPRODUCT_Element *elements,
 182                                          uint32_t element_count,
 183                                          GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
 184                                          void *cont_cls);
 185
 186
 187 /**
 188  * Cancel an ongoing computation or revoke our collaboration offer.
 189  * Closes the connection to the service
 190  *
 191  * @param h computation handle to terminate
 192  */
 193 void
 194 GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h);
 195
 196
 197 #if 0                           /* keep Emacsens' auto-indent happy */
 198 {
 199 #endif
 200 #ifdef __cplusplus
 201 }
 202 #endif
 203
 204 #endif
 205
 206 /** @} */  /* end of group */