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 2, 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_vectorproduct_service.h
  23  * @brief API to the vectorproduct service
  24  * @author Christian M. Fuchs
  25  * @author Gaurav Kukreja
  26  */
  27 #ifndef GNUNET_VECTORPRODUCT_SERVICE_H
  28 #define GNUNET_VECTORPRODUCT_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 vectorproduct API.
  42  */
  43 #define GNUNET_VECTORPRODUCT_VERSION 0x00000042
  44
  45 /**
  46  * Message type passed from client to service
  47  * to initiate a request or responder role
  48  */
  49 struct GNUNET_VECTORPRODUCT_client_request {
  50   /**
  51    * GNUNET message header
  52    */
  53   struct GNUNET_MessageHeader header;
  54
  55   /**
  56    * how many elements the vector in payload contains
  57    */
  58   uint16_t element_count GNUNET_PACKED;
  59
  60   /**
  61    * how many bytes the mask has
  62    */
  63   uint16_t mask_length GNUNET_PACKED;
  64
  65   /**
  66    * the transaction/session key used to identify a session
  67    */
  68   struct GNUNET_HashCode key;
  69
  70   /**
  71    * the identity of a remote peer we want to communicate with
  72    */
  73   struct GNUNET_PeerIdentity peer;
  74
  75   /**
  76    * followed by long vector[element_count] | [unsigned char mask[mask_bytes]]
  77    */
  78 };
  79
  80 /**
  81  * Message type passed from service client
  82  * to finalize a session as requester or responder
  83  */
  84 struct GNUNET_VECTORPRODUCT_client_response {
  85   /**
  86    * GNUNET message header
  87    */
  88   struct GNUNET_MessageHeader header;
  89
  90   /**
  91    * 0 if no product attached
  92    */
  93   uint32_t product_length GNUNET_PACKED;
  94
  95   /**
  96    * the transaction/session key used to identify a session
  97    */
  98   struct GNUNET_HashCode key;
  99
 100   /**
 101    * the identity of a remote peer we want to communicate with
 102    */
 103   struct GNUNET_PeerIdentity peer;
 104
 105   /**
 106    * followed by product of length product_length (or nothing)
 107    */
 108 };
 109
 110 enum GNUNET_VECTORPRODUCT_ResponseStatus {
 111   GNUNET_VECTORPRODUCT_Status_Success = 0,
 112   GNUNET_VECTORPRODUCT_Status_Failure,
 113   GNUNET_VECTORPRODUCT_Status_Timeout,
 114   GNUNET_VECTORPRODUCT_Status_InvalidResponse,
 115   GNUNET_VECTORPRODUCT_Status_ServiceDisconnected
 116 };
 117
 118 struct GNUNET_VECTORPRODUCT_Handle {
 119   /**
 120    * Our configuration.
 121    */
 122   const struct GNUNET_CONFIGURATION_Handle *cfg;
 123
 124   /**
 125    * Current connection to the vectorproduct service.
 126    */
 127   struct GNUNET_CLIENT_Connection *client;
 128
 129   /**
 130    * Handle for statistics.
 131    */
 132   struct GNUNET_STATISTICS_Handle *stats;
 133
 134   /**
 135    * Current head of priority queue.
 136    */
 137   struct GNUNET_VECTORPRODUCT_QueueEntry *queue_head;
 138
 139   /**
 140    * Current tail of priority queue.
 141    */
 142   struct GNUNET_VECTORPRODUCT_QueueEntry *queue_tail;
 143
 144   /**
 145    * Are we currently trying to receive from the service?
 146    */
 147   int in_receive;
 148
 149   /**
 150    * Current transmit handle.
 151    */
 152   struct GNUNET_CLIENT_TransmitHandle *th;
 153
 154   /**
 155    * TODO: What else should/could go here?
 156    */
 157 };
 158
 159 typedef void (*GNUNET_VECTORPRODUCT_ResponseMessageHandler) (void *cls,
 160         const struct GNUNET_MessageHeader *msg,
 161         enum GNUNET_VECTORPRODUCT_ResponseStatus status);
 162
 163 /**
 164  * Continuation called to notify client about result of the
 165  * operation.
 166  *
 167  * @param cls closure
 168  * @param success GNUNET_SYSERR on failure (including timeout/queue drop)
 169  *                GNUNET_NO if content was already there
 170  *                GNUNET_YES (or other positive value) on success
 171  * @param msg NULL on success, otherwise an error message
 172  */
 173 typedef void (*GNUNET_VECTORPRODUCT_ContinuationWithStatus) (void *cls,
 174         const struct GNUNET_HashCode * key,
 175         enum GNUNET_VECTORPRODUCT_ResponseStatus status);
 176 /**
 177  * Process a datum that was stored in the vectorproduct.
 178  *
 179  * @param cls closure
 180  * @param key Sessioon key
 181  * @param peer PeerID of the peer with whom the scalar product was calculated.
 182  * @param status Status of the request
 183  * @param size Size of the received message
 184  * @param data Pointer to the data
 185  * @param type Type of data
 186  */
 187 typedef void (*GNUNET_VECTORPRODUCT_DatumProcessor) (void *cls,
 188         const struct GNUNET_HashCode * key,
 189         const struct GNUNET_PeerIdentity * peer,
 190         enum GNUNET_VECTORPRODUCT_ResponseStatus status,
 191         const struct GNUNET_VECTORPRODUCT_client_response *msg);
 192
 193 /**
 194  * Request the Scalar Product Evaluation
 195  *
 196  * @param h handle to the master context
 197  * @param key Session key - unique to the requesting client
 198  * @param peer PeerID of the other peer
 199  * @param element_count Number of elements in the vector
 200  * @param mask_bytes number of bytes in the mask
 201  * @param elements Array of elements of the vector
 202  * @param mask Array of the mask
 203  * @param timeout Relative timeout for the operation
 204  * @param cont Callback function
 205  * @param cont_cls Closure for the callback function
 206  */
 207 struct GNUNET_VECTORPRODUCT_QueueEntry *
 208 GNUNET_VECTORPRODUCT_request(struct GNUNET_VECTORPRODUCT_Handle *h,
 209         const struct GNUNET_HashCode * key,
 210         const struct GNUNET_PeerIdentity *peer,
 211         uint16_t element_count,
 212         uint16_t mask_bytes,
 213         int32_t * elements, const unsigned char * mask,
 214         struct GNUNET_TIME_Relative timeout,
 215         GNUNET_VECTORPRODUCT_DatumProcessor cont,
 216         void *cont_cls);
 217
 218 /**
 219  * Called by the responder client to prepare response
 220  *
 221  * @param h handle to the master context
 222  * @param key Session key - unique to the requesting client
 223  * @param element_count Number of elements in the vector
 224  * @param mask_bytes number of bytes in the mask
 225  * @param elements Array of elements of the vector
 226  * @param mask Array of the mask
 227  * @param timeout Relative timeout for the operation
 228  * @param cont Callback function
 229  * @param cont_cls Closure for the callback function
 230  */
 231 struct GNUNET_VECTORPRODUCT_QueueEntry *
 232 GNUNET_VECTORPRODUCT_prepare_response(struct GNUNET_VECTORPRODUCT_Handle *h,
 233         const struct GNUNET_HashCode * key,
 234         uint16_t element_count,
 235         int32_t* elements,
 236         struct GNUNET_TIME_Relative timeout,
 237         GNUNET_VECTORPRODUCT_ContinuationWithStatus cont,
 238         void *cont_cls);
 239
 240 /**
 241  * Connect to the vectorproduct service.
 242  *
 243  * @param cfg configuration to use
 244  * @return handle to use to access the service
 245  */
 246 struct GNUNET_VECTORPRODUCT_Handle *
 247 GNUNET_VECTORPRODUCT_connect(const struct GNUNET_CONFIGURATION_Handle * cfg);
 248
 249 /**
 250  * Disconnect from the vectorproduct service.
 251  *
 252  * @param h handle to the vectorproduct
 253  */
 254 void
 255 GNUNET_VECTORPRODUCT_disconnect(struct GNUNET_VECTORPRODUCT_Handle * h);
 256
 257
 258 #if 0                           /* keep Emacsens' auto-indent happy */
 259 {
 260 #endif
 261 #ifdef __cplusplus
 262 }
 263 #endif
 264
 265 #endif