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