X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_scalarproduct_service.h;h=5d61946bb2e2813a6c0d888a24afdb41332652a8;hb=634aea297cc983c3d70f65a004f698f215abe590;hp=1146db1e4f46642f78eb6f82706058a87f99325a;hpb=af9252228fabc0b9bea2964fe395ec824c7abffa;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_scalarproduct_service.h b/src/include/gnunet_scalarproduct_service.h index 1146db1e4..5d61946bb 100644 --- a/src/include/gnunet_scalarproduct_service.h +++ b/src/include/gnunet_scalarproduct_service.h @@ -1,28 +1,33 @@ /* 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 3, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - 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. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @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,21 +44,73 @@ 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_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; + +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 * operation. @@ -61,8 +118,11 @@ struct GNUNET_SCALARPRODUCT_Handle; * @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. * @@ -70,55 +130,60 @@ typedef void (*GNUNET_SCALARPRODUCT_ContinuationWithStatus) (void *cls, * @param status Status of the request * @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 cfg the gnunet configuration handle - * @param key Session key should be unique to the requesting client + * @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); + void *cont_cls); + /** * Used by Bob's client to cooperate with Alice, * * @param cfg the gnunet configuration handle - * @param key Session key unique to the requesting client + * @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 @@ -126,14 +191,8 @@ GNUNET_SCALARPRODUCT_response (const struct GNUNET_CONFIGURATION_Handle * cfg, * @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 */ { @@ -143,3 +202,5 @@ GNUNET_SCALARPRODUCT_disconnect (); #endif #endif + +/** @} */ /* end of group */