2 This file is part of GNUnet.
3 (C) 2013 Christian Grothoff (and other contributing authors)
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.
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.
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.
22 * @file include/gnunet_scalarproduct_service.h
23 * @brief API to the scalarproduct service
24 * @author Christian M. Fuchs
25 * @author Gaurav Kukreja
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...
35 #if 0 /* keep Emacsens' auto-indent happy */
41 * Version of the scalarproduct API.
43 #define GNUNET_SCALARPRODUCT_VERSION 0x00000042
46 * Message type passed from client to service
47 * to initiate a request or responder role
49 struct GNUNET_SCALARPRODUCT_client_request {
51 * GNUNET message header
53 struct GNUNET_MessageHeader header;
56 * how many elements the vector in payload contains
58 uint16_t element_count GNUNET_PACKED;
61 * how many bytes the mask has
63 uint16_t mask_length GNUNET_PACKED;
66 * the transaction/session key used to identify a session
68 struct GNUNET_HashCode key;
71 * the identity of a remote peer we want to communicate with
73 struct GNUNET_PeerIdentity peer;
76 * followed by long vector[element_count] | [unsigned char mask[mask_bytes]]
81 * Message type passed from service client
82 * to finalize a session as requester or responder
84 struct GNUNET_SCALARPRODUCT_client_response {
86 * GNUNET message header
88 struct GNUNET_MessageHeader header;
91 * 0 if no product attached
93 uint32_t product_length GNUNET_PACKED;
96 * the transaction/session key used to identify a session
98 struct GNUNET_HashCode key;
101 * the identity of a remote peer we want to communicate with
103 struct GNUNET_PeerIdentity peer;
106 * followed by product of length product_length (or nothing)
110 enum GNUNET_SCALARPRODUCT_ResponseStatus {
111 GNUNET_SCALARPRODUCT_Status_Success = 0,
112 GNUNET_SCALARPRODUCT_Status_Failure,
113 GNUNET_SCALARPRODUCT_Status_Timeout,
114 GNUNET_SCALARPRODUCT_Status_InvalidResponse,
115 GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
118 struct GNUNET_SCALARPRODUCT_Handle {
122 const struct GNUNET_CONFIGURATION_Handle *cfg;
125 * Current connection to the scalarproduct service.
127 struct GNUNET_CLIENT_Connection *client;
130 * Handle for statistics.
132 struct GNUNET_STATISTICS_Handle *stats;
135 * Current head of priority queue.
137 struct GNUNET_SCALARPRODUCT_QueueEntry *queue_head;
140 * Current tail of priority queue.
142 struct GNUNET_SCALARPRODUCT_QueueEntry *queue_tail;
145 * Are we currently trying to receive from the service?
150 * Current transmit handle.
152 struct GNUNET_CLIENT_TransmitHandle *th;
155 * TODO: What else should/could go here?
159 typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls,
160 const struct GNUNET_MessageHeader *msg,
161 enum GNUNET_SCALARPRODUCT_ResponseStatus status);
164 * Continuation called to notify client about result of the
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
173 typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
174 const struct GNUNET_HashCode * key,
175 enum GNUNET_SCALARPRODUCT_ResponseStatus status);
177 * Process a datum that was stored in the scalarproduct.
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
187 typedef void (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
188 const struct GNUNET_HashCode * key,
189 const struct GNUNET_PeerIdentity * peer,
190 enum GNUNET_SCALARPRODUCT_ResponseStatus status,
191 const struct GNUNET_SCALARPRODUCT_client_response *msg);
194 * Request the Scalar Product Evaluation
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
207 struct GNUNET_SCALARPRODUCT_QueueEntry *
208 GNUNET_SCALARPRODUCT_request(struct GNUNET_SCALARPRODUCT_Handle *h,
209 const struct GNUNET_HashCode * key,
210 const struct GNUNET_PeerIdentity *peer,
211 uint16_t element_count,
213 int32_t * elements, const unsigned char * mask,
214 struct GNUNET_TIME_Relative timeout,
215 GNUNET_SCALARPRODUCT_DatumProcessor cont,
219 * Called by the responder client to prepare response
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
231 struct GNUNET_SCALARPRODUCT_QueueEntry *
232 GNUNET_SCALARPRODUCT_prepare_response(struct GNUNET_SCALARPRODUCT_Handle *h,
233 const struct GNUNET_HashCode * key,
234 uint16_t element_count,
236 struct GNUNET_TIME_Relative timeout,
237 GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
241 * Connect to the scalarproduct service.
243 * @param cfg configuration to use
244 * @return handle to use to access the service
246 struct GNUNET_SCALARPRODUCT_Handle *
247 GNUNET_SCALARPRODUCT_connect(const struct GNUNET_CONFIGURATION_Handle * cfg);
250 * Disconnect from the scalarproduct service.
252 * @param h handle to the scalarproduct
255 GNUNET_SCALARPRODUCT_disconnect(struct GNUNET_SCALARPRODUCT_Handle * h);
258 #if 0 /* keep Emacsens' auto-indent happy */