/*
This file is part of GNUnet.
- (C) 2013 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2013, 2014 GNUnet e.V.
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_scalarproduct_service.h
- * @brief API to the scalarproduct service
* @author Christian M. Fuchs
* @author Gaurav Kukreja
+ *
+ * @file
+ * API to the scalarproduct service
+ *
+ * @defgroup scalarproduct Scalar Product service
+ *
+ * @{
*/
#ifndef GNUNET_SCALARPRODUCT_SERVICE_H
#define GNUNET_SCALARPRODUCT_SERVICE_H
/**
* Version of the scalarproduct API.
*/
-#define GNUNET_SCALARPRODUCT_VERSION 0x00000042
+#define GNUNET_SCALARPRODUCT_VERSION 0x00000044
+/**
+ * Result status values for the computation.
+ */
enum GNUNET_SCALARPRODUCT_ResponseStatus
{
- GNUNET_SCALARPRODUCT_Status_Success = 0,
- GNUNET_SCALARPRODUCT_Status_Failure,
- GNUNET_SCALARPRODUCT_Status_InvalidResponse,
- GNUNET_SCALARPRODUCT_Status_ServiceDisconnected
+
+ /**
+ * Operation is still active (never returned, used internally).
+ */
+ GNUNET_SCALARPRODUCT_STATUS_INIT = 0,
+
+ /**
+ * Operation is still active (never returned, used internally).
+ */
+ GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1,
+
+ /**
+ * The computation was successful.
+ */
+ GNUNET_SCALARPRODUCT_STATUS_SUCCESS,
+
+ /**
+ * We encountered some error.
+ */
+ GNUNET_SCALARPRODUCT_STATUS_FAILURE,
+
+ /**
+ * We got an invalid response.
+ */
+ GNUNET_SCALARPRODUCT_STATUS_INVALID_RESPONSE,
+
+ /**
+ * We got disconnected from the SCALARPRODUCT service.
+ */
+ GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED
};
+
+/**
+ * Opaque declaration of the SP-Handle
+ */
struct GNUNET_SCALARPRODUCT_Handle;
-typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls,
- const struct GNUNET_MessageHeader *msg,
- enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+
+GNUNET_NETWORK_STRUCT_BEGIN
+
+/**
+ * An element key-value pair for scalarproduct
+ */
+struct GNUNET_SCALARPRODUCT_Element
+{
+ /**
+ * Key used to identify matching pairs of values to multiply.
+ */
+ struct GNUNET_HashCode key;
+
+ /**
+ * Value to multiply in scalar product, in NBO.
+ */
+ int64_t value GNUNET_PACKED;
+};
+
+GNUNET_NETWORK_STRUCT_END
+
/**
* Continuation called to notify client about result of the
* @param cls closure
* @param status Status of the request
*/
-typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
- enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+typedef void
+(*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls,
+ enum GNUNET_SCALARPRODUCT_ResponseStatus status);
+
+
/**
* Process a datum that was stored in the scalarproduct.
- *
+ *
* @param cls closure
* @param status Status of the request
- * @param type result of the computation
+ * @param result result of the computation
*/
-typedef void (*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
- enum GNUNET_SCALARPRODUCT_ResponseStatus status,
- gcry_mpi_t result);
+typedef void
+(*GNUNET_SCALARPRODUCT_DatumProcessor) (void *cls,
+ enum GNUNET_SCALARPRODUCT_ResponseStatus status,
+ gcry_mpi_t result);
+
+
+/**
+ * Entry in the request queue per client
+ */
+struct GNUNET_SCALARPRODUCT_ComputationHandle;
+
/**
* Request by Alice's client for computing a scalar product
- *
- * @param h handle to the master context
- * @param key Session key - unique to the requesting client
+ *
+ * @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 element_count Number of elements in the vector
- * @param mask Array of the mask
- * @param mask_bytes number of bytes in the mask
+ * @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_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const struct GNUNET_HashCode * key,
+GNUNET_SCALARPRODUCT_start_computation (const struct GNUNET_CONFIGURATION_Handle *cfg,
+ const struct GNUNET_HashCode *session_key,
const struct GNUNET_PeerIdentity *peer,
- const int32_t * elements,
+ const struct GNUNET_SCALARPRODUCT_Element *elements,
uint32_t element_count,
- const unsigned char * mask,
- uint32_t mask_bytes,
GNUNET_SCALARPRODUCT_DatumProcessor cont,
void *cont_cls);
+
/**
- * Used by Bob's client to cooperate with Alice,
- *
- * @param h handle to our configuration
- * @param key Session key - unique to the requesting client
+ * Used by Bob's client to cooperate with Alice,
+ *
+ * @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 vector
+ * @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_SCALARPRODUCT_ComputationHandle *
-GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *cfg,
- const struct GNUNET_HashCode * key,
- const int32_t * elements,
- uint32_t element_count,
- GNUNET_SCALARPRODUCT_ContinuationWithStatus cont,
- void *cont_cls);
+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);
+
+
/**
* Cancel an ongoing computation or revoke our collaboration offer.
* Closes the connection to the service
- *
- * @param h handel to terminate
+ *
+ * @param h computation handle to terminate
*/
void
-GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle * h);
+GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h);
-/**
- * Cancel ALL ongoing computation or revoke our collaboration offer.
- * Closes ALL connections to the service
- *
- */
-void
-GNUNET_SCALARPRODUCT_disconnect ();
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
#endif
+
+/** @} */ /* end of group */
projects / oweals / gnunet.git / blobdiff