/*
This file is part of GNUnet.
- (C) 2013 Christian Grothoff (and other contributing authors)
+ (C) 2013, 2014 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
- by the Free Software Foundation; either version 2, or (at your
+ by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
*/
/**
- * @file include/gnunet_vectorproduct_service.h
- * @brief API to the vectorproduct service
+ * @file include/gnunet_scalarproduct_service.h
+ * @brief API to the scalarproduct service
* @author Christian M. Fuchs
* @author Gaurav Kukreja
*/
-#ifndef GNUNET_VECTORPRODUCT_SERVICE_H
-#define GNUNET_VECTORPRODUCT_SERVICE_H
+#ifndef GNUNET_SCALARPRODUCT_SERVICE_H
+#define GNUNET_SCALARPRODUCT_SERVICE_H
#define GCRYPT_NO_DEPRECATED
-// including gcrypt crashes netbeans after the next restart...
#include <gcrypt.h>
#ifdef __cplusplus
#endif
/**
- * Version of the vectorproduct API.
+ * Version of the scalarproduct API.
*/
-#define GNUNET_VECTORPRODUCT_VERSION 0x00000042
+#define GNUNET_SCALARPRODUCT_VERSION 0x00000044
/**
- * Message type passed from client to service
- * to initiate a request or responder role
+ * Result status values for the computation.
*/
-struct GNUNET_VECTORPRODUCT_client_request {
- /**
- * GNUNET message header
- */
- struct GNUNET_MessageHeader header;
-
+enum GNUNET_SCALARPRODUCT_ResponseStatus
+{
/**
- * how many elements the vector in payload contains
+ * The computation was successful.
*/
- uint16_t element_count GNUNET_PACKED;
+ GNUNET_SCALARPRODUCT_Status_Success = 0,
/**
- * how many bytes the mask has
+ * We encountered some error.
*/
- uint16_t mask_length GNUNET_PACKED;
-
- /**
- * the transaction/session key used to identify a session
- */
- struct GNUNET_HashCode key;
+ GNUNET_SCALARPRODUCT_Status_Failure,
/**
- * the identity of a remote peer we want to communicate with
+ * We got an invalid response.
*/
- struct GNUNET_PeerIdentity peer;
+ GNUNET_SCALARPRODUCT_Status_InvalidResponse,
/**
- * followed by long vector[element_count] | [unsigned char mask[mask_bytes]]
+ * We got disconnected from the SCALARPRODUCT service.
*/
+ GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
};
+
/**
- * Message type passed from service client
- * to finalize a session as requester or responder
+ * Opaque declaration of the SP-Handle
*/
-struct GNUNET_VECTORPRODUCT_client_response {
- /**
- * GNUNET message header
- */
- struct GNUNET_MessageHeader header;
+struct GNUNET_SCALARPRODUCT_Handle;
- /**
- * 0 if no product attached
- */
- uint32_t product_length GNUNET_PACKED;
- /**
- * the transaction/session key used to identify a session
- */
- struct GNUNET_HashCode key;
+GNUNET_NETWORK_STRUCT_BEGIN
+/**
+ * An element key-value pair for scalarproduct
+ */
+struct GNUNET_SCALARPRODUCT_Element
+{
/**
- * the identity of a remote peer we want to communicate with
+ * Key used to identify matching pairs of values to multiply.
*/
- struct GNUNET_PeerIdentity peer;
+ struct GNUNET_HashCode key;
/**
- * followed by product of length product_length (or nothing)
+ * Value to multiply in scalar product.
*/
+ int64_t value GNUNET_PACKED;
};
-enum GNUNET_VECTORPRODUCT_ResponseStatus {
- GNUNET_VECTORPRODUCT_Status_Success = 0,
- GNUNET_VECTORPRODUCT_Status_Failure,
- GNUNET_VECTORPRODUCT_Status_Timeout,
- GNUNET_VECTORPRODUCT_Status_InvalidResponse,
- GNUNET_VECTORPRODUCT_Status_ServiceDisconnected
-};
-
-struct GNUNET_VECTORPRODUCT_Handle {
- /**
- * Our configuration.
- */
- const struct GNUNET_CONFIGURATION_Handle *cfg;
-
- /**
- * Current connection to the vectorproduct service.
- */
- struct GNUNET_CLIENT_Connection *client;
-
- /**
- * Handle for statistics.
- */
- struct GNUNET_STATISTICS_Handle *stats;
-
- /**
- * Current head of priority queue.
- */
- struct GNUNET_VECTORPRODUCT_QueueEntry *queue_head;
-
- /**
- * Current tail of priority queue.
- */
- struct GNUNET_VECTORPRODUCT_QueueEntry *queue_tail;
-
- /**
- * Are we currently trying to receive from the service?
- */
- int in_receive;
-
- /**
- * Current transmit handle.
- */
- struct GNUNET_CLIENT_TransmitHandle *th;
-
- /**
- * TODO: What else should/could go here?
- */
-};
+GNUNET_NETWORK_STRUCT_END
-typedef void (*GNUNET_VECTORPRODUCT_ResponseMessageHandler) (void *cls,
- const struct GNUNET_MessageHeader *msg,
- enum GNUNET_VECTORPRODUCT_ResponseStatus status);
/**
* Continuation called to notify client about result of the
* operation.
*
* @param cls closure
- * @param success GNUNET_SYSERR on failure (including timeout/queue drop)
- * GNUNET_NO if content was already there
- * GNUNET_YES (or other positive value) on success
- * @param msg NULL on success, otherwise an error message
+ * @param status Status of the request
*/
-typedef void (*GNUNET_VECTORPRODUCT_ContinuationWithStatus) (void *cls,
- const struct GNUNET_HashCode * key,
- enum GNUNET_VECTORPRODUCT_ResponseStatus status);
+typedef void
+(*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
+ enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+
+
/**
- * Process a datum that was stored in the vectorproduct.
- *
+ * Process a datum that was stored in the scalarproduct.
+ *
* @param cls closure
- * @param key Sessioon key
- * @param peer PeerID of the peer with whom the scalar product was calculated.
* @param status Status of the request
- * @param size Size of the received message
- * @param data Pointer to the data
- * @param type Type of data
+ * @param result result of the computation
*/
-typedef void (*GNUNET_VECTORPRODUCT_DatumProcessor) (void *cls,
- const struct GNUNET_HashCode * key,
- const struct GNUNET_PeerIdentity * peer,
- enum GNUNET_VECTORPRODUCT_ResponseStatus status,
- const struct GNUNET_VECTORPRODUCT_client_response *msg);
+typedef void
+(*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
+ enum GNUNET_SCALARPRODUCT_ResponseStatus status,
+ gcry_mpi_t result);
+
/**
- * Request the Scalar Product Evaluation
- *
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
- * @param peer PeerID of the other peer
- * @param element_count Number of elements in the vector
- * @param mask_bytes number of bytes in the mask
- * @param elements Array of elements of the vector
- * @param mask Array of the mask
- * @param timeout Relative timeout for the operation
- * @param cont Callback function
- * @param cont_cls Closure for the callback function
+ * Entry in the request queue per client
*/
-struct GNUNET_VECTORPRODUCT_QueueEntry *
-GNUNET_VECTORPRODUCT_request(struct GNUNET_VECTORPRODUCT_Handle *h,
- const struct GNUNET_HashCode * key,
- const struct GNUNET_PeerIdentity *peer,
- uint16_t element_count,
- uint16_t mask_bytes,
- int32_t * elements, const unsigned char * mask,
- struct GNUNET_TIME_Relative timeout,
- GNUNET_VECTORPRODUCT_DatumProcessor cont,
- void *cont_cls);
+struct GNUNET_SCALARPRODUCT_ComputationHandle;
+
/**
- * Called by the responder client to prepare response
- *
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
- * @param element_count Number of elements in the vector
- * @param mask_bytes number of bytes in the mask
+ * Request by Alice's client for computing a scalar product
+ *
+ * @param cfg the gnunet configuration handle
+ * @param session_key Session key should be unique to the requesting client
+ * @param peer PeerID of the other peer
* @param elements Array of elements of the vector
- * @param mask Array of the mask
- * @param timeout Relative timeout for the operation
+ * @param element_count Number of elements in the @a elements vector
* @param cont Callback function
- * @param cont_cls Closure for the callback function
+ * @param cont_cls Closure for the @a cont callback function
+ * @return a new handle for this computation
*/
-struct GNUNET_VECTORPRODUCT_QueueEntry *
-GNUNET_VECTORPRODUCT_prepare_response(struct GNUNET_VECTORPRODUCT_Handle *h,
- const struct GNUNET_HashCode * key,
- uint16_t element_count,
- int32_t* elements,
- struct GNUNET_TIME_Relative timeout,
- GNUNET_VECTORPRODUCT_ContinuationWithStatus cont,
- void *cont_cls);
+struct GNUNET_SCALARPRODUCT_ComputationHandle *
+GNUNET_SCALARPRODUCT_start_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ const struct GNUNET_HashCode *session_key,
+ const struct GNUNET_PeerIdentity *peer,
+ const struct GNUNET_SCALARPRODUCT_Element *elements,
+ uint32_t element_count,
+ GNUNET_SCALARPRODUCT_DatumProcessor cont,
+ void *cont_cls);
+
/**
- * Connect to the vectorproduct service.
+ * Used by Bob's client to cooperate with Alice,
*
- * @param cfg configuration to use
- * @return handle to use to access the service
+ * @param cfg the gnunet configuration handle
+ * @param session_key Session key unique to the requesting client
+ * @param elements Array of elements of the vector
+ * @param element_count Number of elements in the @a elements vector
+ * @param cont Callback function
+ * @param cont_cls Closure for the @a cont callback function
+ * @return a new handle for this computation
*/
-struct GNUNET_VECTORPRODUCT_Handle *
-GNUNET_VECTORPRODUCT_connect(const struct GNUNET_CONFIGURATION_Handle * cfg);
+struct GNUNET_SCALARPRODUCT_ComputationHandle *
+GNUNET_SCALARPRODUCT_accept_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ const struct GNUNET_HashCode *key,
+ const struct GNUNET_SCALARPRODUCT_Element *elements,
+ uint32_t element_count,
+ GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
+ void *cont_cls);
+
/**
- * Disconnect from the vectorproduct service.
- *
- * @param h handle to the vectorproduct
+ * Cancel an ongoing computation or revoke our collaboration offer.
+ * Closes the connection to the service
+ *
+ * @param h computation handle to terminate
*/
void
-GNUNET_VECTORPRODUCT_disconnect(struct GNUNET_VECTORPRODUCT_Handle * h);
-
+GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h);
#if 0 /* keep Emacsens' auto-indent happy */
{