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