X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_scalarproduct_service.h;h=21e00ca10666676eba9c482695e10b1213c0fca1;hb=4ffa88828d1f14aeef51a777d553e904549fb03e;hp=9fc8dbd2ad79183372c4a129c18953074ec13c02;hpb=5a0e57891c7f33f03bb25a3ab6b83d0f0b26a05e;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_scalarproduct_service.h b/src/include/gnunet_scalarproduct_service.h index 9fc8dbd2a..21e00ca10 100644 --- a/src/include/gnunet_scalarproduct_service.h +++ b/src/include/gnunet_scalarproduct_service.h @@ -1,10 +1,10 @@ /* 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 - 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 @@ -14,20 +14,24 @@ 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 #define GCRYPT_NO_DEPRECATED -// including gcrypt crashes netbeans after the next restart... #include #ifdef __cplusplus @@ -40,219 +44,154 @@ extern "C" { /** * Version of the scalarproduct API. */ -#define GNUNET_SCALARPRODUCT_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_SCALARPRODUCT_client_request { - /** - * GNUNET message header - */ - struct GNUNET_MessageHeader header; - - /** - * how many elements the vector in payload contains - */ - uint16_t element_count GNUNET_PACKED; - - /** - * how many bytes the mask has - */ - uint16_t mask_length GNUNET_PACKED; - - /** - * the transaction/session key used to identify a session - */ - struct GNUNET_HashCode key; - - /** - * the identity of a remote peer we want to communicate with - */ - struct GNUNET_PeerIdentity peer; +enum GNUNET_SCALARPRODUCT_ResponseStatus +{ /** - * followed by long vector[element_count] | [unsigned char mask[mask_bytes]] + * Operation is still active (never returned, used internally). */ -}; + GNUNET_SCALARPRODUCT_STATUS_INIT = 0, -/** - * Message type passed from service client - * to finalize a session as requester or responder - */ -struct GNUNET_SCALARPRODUCT_client_response { /** - * GNUNET message header + * Operation is still active (never returned, used internally). */ - struct GNUNET_MessageHeader header; + GNUNET_SCALARPRODUCT_STATUS_ACTIVE = 1, /** - * 0 if no product attached + * The computation was successful. */ - uint32_t product_length GNUNET_PACKED; + GNUNET_SCALARPRODUCT_STATUS_SUCCESS, /** - * the transaction/session key used to identify a session + * We encountered some error. */ - 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_INVALID_RESPONSE, /** - * followed by product of length product_length (or nothing) + * We got disconnected from the SCALARPRODUCT service. */ + GNUNET_SCALARPRODUCT_STATUS_DISCONNECTED }; -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 -}; - -struct GNUNET_SCALARPRODUCT_Handle { - /** - * Our configuration. - */ - const struct GNUNET_CONFIGURATION_Handle *cfg; - - /** - * Current connection to the scalarproduct service. - */ - struct GNUNET_CLIENT_Connection *client; - - /** - * Handle for statistics. - */ - struct GNUNET_STATISTICS_Handle *stats; - /** - * Current head of priority queue. - */ - struct GNUNET_SCALARPRODUCT_QueueEntry *queue_head; +/** + * Opaque declaration of the SP-Handle + */ +struct GNUNET_SCALARPRODUCT_Handle; - /** - * Current tail of priority queue. - */ - struct GNUNET_SCALARPRODUCT_QueueEntry *queue_tail; - /** - * Are we currently trying to receive from the service? - */ - int in_receive; +GNUNET_NETWORK_STRUCT_BEGIN +/** + * An element key-value pair for scalarproduct + */ +struct GNUNET_SCALARPRODUCT_Element +{ /** - * Current transmit handle. + * Key used to identify matching pairs of values to multiply. */ - struct GNUNET_CLIENT_TransmitHandle *th; + struct GNUNET_HashCode key; /** - * TODO: What else should/could go here? + * Value to multiply in scalar product, in NBO. */ + int64_t value GNUNET_PACKED; }; -typedef void (*GNUNET_SCALARPRODUCT_ResponseMessageHandler) (void *cls, - const struct GNUNET_MessageHeader *msg, - enum GNUNET_SCALARPRODUCT_ResponseStatus status); +GNUNET_NETWORK_STRUCT_END + /** * 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_SCALARPRODUCT_ContinuationWithStatus) (void *cls, - const struct GNUNET_HashCode * key, - 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 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_SCALARPRODUCT_DatumProcessor) (void *cls, - const struct GNUNET_HashCode * key, - const struct GNUNET_PeerIdentity * peer, - enum GNUNET_SCALARPRODUCT_ResponseStatus status, - const struct GNUNET_SCALARPRODUCT_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_SCALARPRODUCT_QueueEntry * -GNUNET_SCALARPRODUCT_request(struct GNUNET_SCALARPRODUCT_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_SCALARPRODUCT_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_SCALARPRODUCT_QueueEntry * -GNUNET_SCALARPRODUCT_prepare_response(struct GNUNET_SCALARPRODUCT_Handle *h, - const struct GNUNET_HashCode * key, - uint16_t element_count, - int32_t* elements, - struct GNUNET_TIME_Relative timeout, - GNUNET_SCALARPRODUCT_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 scalarproduct 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_SCALARPRODUCT_Handle * -GNUNET_SCALARPRODUCT_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 scalarproduct service. - * - * @param h handle to the scalarproduct + * Cancel an ongoing computation or revoke our collaboration offer. + * Closes the connection to the service + * + * @param h computation handle to terminate */ void -GNUNET_SCALARPRODUCT_disconnect(struct GNUNET_SCALARPRODUCT_Handle * h); +GNUNET_SCALARPRODUCT_cancel (struct GNUNET_SCALARPRODUCT_ComputationHandle *h); #if 0 /* keep Emacsens' auto-indent happy */ @@ -263,3 +202,5 @@ GNUNET_SCALARPRODUCT_disconnect(struct GNUNET_SCALARPRODUCT_Handle * h); #endif #endif + +/** @} */ /* end of group */