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
  16 /**
  17  * @author Christian M. Fuchs
  18  * @author Gaurav Kukreja
  19  *
  20  * @file
  21  * API to the scalarproduct service
  22  *
  23  * @defgroup scalarproduct  Scalar Product service
  24  *
  25  * @{
  26  */
  27 #ifndef GNUNET_SCALARPRODUCT_SERVICE_H
  28 #define GNUNET_SCALARPRODUCT_SERVICE_H
  29 #define GCRYPT_NO_DEPRECATED
  30 #include <gcrypt.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #if 0                           /* keep Emacsens' auto-indent happy */
  35 }
  36 #endif
  37 #endif
  38
  39 /**
  40  * Version of the scalarproduct API.
  41  */
  42 #define GNUNET_SCALARPRODUCT_VERSION 0x00000044
  43
  44 /**
  45  * Result status values for the computation.
  46  */
  47 enum GNUNET_SCALARPRODUCT_ResponseStatus
  48 {
  49
  50   /**
  51    * Operation is still active (never returned, used internally).
  52    */
  53   GNUNET_SCALARPRODUCT_STATUS_INIT = 0,
  54
  55   /**
  56    * Operation is still active (never returned, used internally).
  57    */
  58   GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1,
  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 */