X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_scalarproduct_service.h;h=21e00ca10666676eba9c482695e10b1213c0fca1;hb=4ffa88828d1f14aeef51a777d553e904549fb03e;hp=3aac679c401956915df10dc0d7e613c58a457743;hpb=9f064f70f7aff38119ebf1b4345118cb61302f2d;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_scalarproduct_service.h b/src/include/gnunet_scalarproduct_service.h index 3aac679c4..21e00ca10 100644 --- a/src/include/gnunet_scalarproduct_service.h +++ b/src/include/gnunet_scalarproduct_service.h @@ -1,6 +1,6 @@ /* 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 @@ -14,15 +14,20 @@ 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 @@ -39,22 +44,72 @@ extern "C" { /** * 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_Timeout, - 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 @@ -63,68 +118,81 @@ typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls, * @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_Handle * -GNUNET_SCALARPRODUCT_request (const struct GNUNET_CONFIGURATION_Handle *h, - const struct GNUNET_HashCode * key, +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 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 the master context - * @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_Handle * -GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle *h, - const struct GNUNET_HashCode * key, - const int32_t * elements, - uint32_t element_count, - GNUNET_SCALARPRODUCT_ContinuationWithStatus cont, - void *cont_cls); +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); + + /** * 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 (const struct GNUNET_SCALARPRODUCT_Handle *h); +void +GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h); + #if 0 /* keep Emacsens' auto-indent happy */ { @@ -134,3 +202,5 @@ GNUNET_SCALARPRODUCT_cancel (const struct GNUNET_SCALARPRODUCT_Handle *h); #endif #endif + +/** @} */ /* end of group */