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