src/include/gnunet_scalarproduct_service.h

   1 /*
   2       This file is part of GNUnet.
   3       (C) 2013 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file include/gnunet_scalarproduct_service.h
  23  * @brief API to the scalarproduct service
  24  * @author Christian M. Fuchs
  25  * @author Gaurav Kukreja
  26  */
  27 #ifndef GNUNET_SCALARPRODUCT_SERVICE_H
  28 #define GNUNET_SCALARPRODUCT_SERVICE_H
  29 #define GCRYPT_NO_DEPRECATED
  30 // including gcrypt crashes netbeans after the next restart...
  31 #include <gcrypt.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 /**
  41  * Version of the scalarproduct API.
  42  */
  43 #define GNUNET_SCALARPRODUCT_VERSION 0x00000042
  44
  45 /**
  46  * Message type passed from client to service
  47  * to initiate a request or responder role
  48  */
  49 struct GNUNET_SCALARPRODUCT_client_request
  50 {
  51   /**
  52    * GNUNET message header
  53    */
  54   struct GNUNET_MessageHeader header;
  55
  56   /**
  57    * how many elements the vector in payload contains
  58    */
  59   uint16_t element_count GNUNET_PACKED;
  60
  61   /**
  62    * how many bytes the mask has
  63    */
  64   uint16_t mask_length GNUNET_PACKED;
  65
  66   /**
  67    * the transaction/session key used to identify a session
  68    */
  69   struct GNUNET_HashCode key;
  70
  71   /**
  72    * the identity of a remote peer we want to communicate with
  73    */
  74   struct GNUNET_PeerIdentity peer;
  75
  76   /**
  77    * followed by long vector[element_count] | [unsigned char mask[mask_bytes]]
  78    */
  79 };
  80
  81 /**
  82  * Message type passed from service client
  83  * to finalize a session as requester or responder
  84  */
  85 struct GNUNET_SCALARPRODUCT_client_response
  86 {
  87   /**
  88    * GNUNET message header
  89    */
  90   struct GNUNET_MessageHeader header;
  91
  92   /**
  93    * 0 if no product attached
  94    */
  95   uint32_t product_length GNUNET_PACKED;
  96
  97   /**
  98    * the transaction/session key used to identify a session
  99    */
 100   struct GNUNET_HashCode key;
 101
 102   /**
 103    * the identity of a remote peer we want to communicate with
 104    */
 105   struct GNUNET_PeerIdentity peer;
 106
 107   /**
 108    * Workaround for libgcrypt: -1 if negative, 0 if zero, else 1
 109    */
 110   int8_t range;
 111
 112   /**
 113    * followed by product of length product_length (or nothing)
 114    */
 115 };
 116
 117 enum GNUNET_SCALARPRODUCT_ResponseStatus
 118 {
 119   GNUNET_SCALARPRODUCT_Status_Success = 0,
 120   GNUNET_SCALARPRODUCT_Status_Failure,
 121   GNUNET_SCALARPRODUCT_Status_Timeout,
 122   GNUNET_SCALARPRODUCT_Status_InvalidResponse,
 123   GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
 124 };
 125
 126 struct GNUNET_SCALARPRODUCT_Handle
 127 {
 128   /**
 129    * Our configuration.
 130    */
 131   const struct GNUNET_CONFIGURATION_Handle *cfg;
 132
 133   /**
 134    * Current connection to the scalarproduct service.
 135    */
 136   struct GNUNET_CLIENT_Connection *client;
 137
 138   /**
 139    * Handle for statistics.
 140    */
 141   struct GNUNET_STATISTICS_Handle *stats;
 142
 143   /**
 144    * Current transmit handle.
 145    */
 146   struct GNUNET_CLIENT_TransmitHandle *th;
 147
 148   /**
 149    * Handle to the master context.
 150    */
 151   struct GNUNET_SCALARPRODUCT_Handle *h;
 152
 153   /**
 154    * The shared session key identifying this computation
 155    */
 156   struct GNUNET_HashCode * key;
 157
 158   /**
 159    * The message to be transmitted
 160    */
 161   void * msg;
 162
 163   union
 164   {
 165     /**
 166      * Function to call after transmission of the request.
 167      */
 168     GNUNET_SCALARPRODUCT_ContinuationWithStatus cont_status;
 169
 170     /**
 171      * Function to call after transmission of the request.
 172      */
 173     GNUNET_SCALARPRODUCT_DatumProcessor cont_datum;
 174   };
 175
 176   /**
 177    * Closure for 'cont'.
 178    */
 179   void *cont_cls;
 180
 181   /**
 182    * Response Processor for response from the service. This function calls the
 183    * continuation function provided by the client.
 184    */
 185   GNUNET_SCALARPRODUCT_ResponseMessageHandler response_proc;
 186 };
 187
 188 typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls,
 189                                                              const struct GNUNET_MessageHeader *msg,
 190                                                              enum GNUNET_SCALARPRODUCT_ResponseStatus status);
 191
 192 /**
 193  * Continuation called to notify client about result of the
 194  * operation.
 195  *
 196  * @param cls closure
 197  * @param success GNUNET_SYSERR on failure (including timeout/queue drop)
 198  *                GNUNET_NO if content was already there
 199  *                GNUNET_YES (or other positive value) on success
 200  * @param msg NULL on success, otherwise an error message
 201  */
 202 typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
 203                                                              enum GNUNET_SCALARPRODUCT_ResponseStatus status);
 204 /**
 205  * Process a datum that was stored in the scalarproduct.
 206  *
 207  * @param cls closure
 208  * @param key Sessioon key
 209  * @param peer PeerID of the peer with whom the scalar product was calculated.
 210  * @param status Status of the request
 211  * @param size Size of the received message
 212  * @param data Pointer to the data
 213  * @param type Type of data
 214  */
 215 typedef void (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
 216                                                      enum GNUNET_SCALARPRODUCT_ResponseStatus status,
 217                                                      gcry_mpi_t result);
 218
 219 /**
 220  * Request by Alice's client for computing a scalar product
 221  *
 222  * @param h handle to the master context
 223  * @param key Session key - unique to the requesting client
 224  * @param peer PeerID of the other peer
 225  * @param elements Array of elements of the vector
 226  * @param element_count Number of elements in the vector
 227  * @param mask Array of the mask
 228  * @param mask_bytes number of bytes in the mask
 229  * @param cont Callback function
 230  * @param cont_cls Closure for the callback function
 231  */
 232 struct GNUNET_SCALARPRODUCT_Handle *
 233 GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *h,
 234                               const struct GNUNET_HashCode * key,
 235                               const struct GNUNET_PeerIdentity *peer,
 236                               const int32_t * elements,
 237                               uint32_t element_count,
 238                               const unsigned char * mask,
 239                               uint32_t mask_bytes,
 240                               GNUNET_SCALARPRODUCT_DatumProcessor cont,
 241                               void *cont_cls);
 242
 243 /**
 244  * Used by Bob's client to cooperate with Alice,
 245  *
 246  * @param h handle to the master context
 247  * @param key Session key - unique to the requesting client
 248  * @param elements Array of elements of the vector
 249  * @param element_count Number of elements in the vector
 250  * @param cont Callback function
 251  * @param cont_cls Closure for the callback function
 252  */
 253 struct GNUNET_SCALARPRODUCT_Handle *
 254 GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *h,
 255                                const struct GNUNET_HashCode * key,
 256                                const int32_t * elements,
 257                                uint32_t element_count,
 258                                GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
 259                                void *cont_cls);
 260 /**
 261  * Cancel an ongoing computation or revoke our collaboration offer.
 262  * Closes the connection to the service
 263  *
 264  * @param h handel to terminate
 265  */
 266 void
 267 GNUNET_SCALARPRODUCT_cancel (const struct GNUNET_SCALARPRODUCT_Handle *h);
 268
 269 #if 0                           /* keep Emacsens' auto-indent happy */
 270 {
 271 #endif
 272 #ifdef __cplusplus
 273 }
 274 #endif
 275
 276 #endif