X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_set_service.h;h=44773f1872457753d44769225482e0b58ffe8c5f;hb=7a7ec54a324da4820202582126795a8ac6bbe94d;hp=72d7ee521c667dc6548211631e21fee9448d81b9;hpb=5cce50f3c8b2d0c54230238de5dd19ab8bd2de3b;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h index 72d7ee521..44773f187 100644 --- a/src/include/gnunet_set_service.h +++ b/src/include/gnunet_set_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,14 +14,23 @@ 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_set_service.h - * @brief two-peer set operations * @author Florian Dold + * @author Christian Grothoff + * + * @file + * Two-peer set operations + * + * @defgroup set Set service + * Two-peer set operations + * + * @see [Documentation](https://gnunet.org/set-subsystem) + * + * @{ */ #ifndef GNUNET_SET_SERVICE_H @@ -35,12 +44,17 @@ extern "C" #endif #endif -#include "platform.h" #include "gnunet_common.h" #include "gnunet_time_lib.h" #include "gnunet_configuration_lib.h" +/** + * Maximum size of a context message for set operation requests. + */ +#define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024) + + /** * Opaque handle to a set. */ @@ -67,30 +81,57 @@ struct GNUNET_SET_OperationHandle; */ enum GNUNET_SET_OperationType { + /** + * A purely local set that does not support any operation. + */ + GNUNET_SET_OPERATION_NONE, + /** * Set intersection, only return elements that are in both sets. */ GNUNET_SET_OPERATION_INTERSECTION, + /** * Set union, return all elements that are in at least one of the sets. */ GNUNET_SET_OPERATION_UNION }; + /** * Status for the result callback */ enum GNUNET_SET_Status { /** - * Everything went ok. + * Everything went ok, we are transmitting an element of the + * result (in set, or to be removed from set, depending on + * the `enum GNUNET_SET_ResultMode`). + * + * Only applies to + * #GNUNET_SET_RESULT_FULL, + * #GNUNET_SET_RESULT_ADDED, + * #GNUNET_SET_RESULT_REMOVED, */ GNUNET_SET_STATUS_OK, /** - * There was a timeout. + * Element should be added to the result set + * of the local peer, i.e. the local peer is + * missing an element. + * + * Only applies to #GNUNET_SET_RESULT_SYMMETRIC */ - GNUNET_SET_STATUS_TIMEOUT, + GNUNET_SET_STATUS_ADD_LOCAL, + + /** + * Element should be added to the result set + * of the remove peer, i.e. the remote peer is + * missing an element. + * + * Only applies to #GNUNET_SET_RESULT_SYMMETRIC + */ + GNUNET_SET_STATUS_ADD_REMOTE, /** * The other peer refused to to the operation with us, @@ -99,8 +140,9 @@ enum GNUNET_SET_Status GNUNET_SET_STATUS_FAILURE, /** - * Success, all elements have been returned (but the other - * peer might still be receiving some from us, so we are not done). + * Success, all elements have been returned (but the other peer + * might still be receiving some from us, so we are not done). Only + * used during UNION operation. */ GNUNET_SET_STATUS_HALF_DONE, @@ -110,6 +152,7 @@ enum GNUNET_SET_Status GNUNET_SET_STATUS_DONE }; + /** * The way results are given to the client. */ @@ -117,20 +160,35 @@ enum GNUNET_SET_ResultMode { /** * Client gets every element in the resulting set. + * + * Only supported for set intersection. */ GNUNET_SET_RESULT_FULL, + /** - * Client gets only elements that have been added to the set. - * Only works with set union. + * Client gets notified of the required changes + * for both the local and the remote set. + * + * Only supported for set */ - GNUNET_SET_RESULT_ADDED, + GNUNET_SET_RESULT_SYMMETRIC, + + /** + * Client gets only elements that have been removed from the set. + * + * Only supported for set intersection. + */ + GNUNET_SET_RESULT_REMOVED, + /** * Client gets only elements that have been removed from the set. - * Only works with set intersection. + * + * Only supported for set union. */ - GNUNET_SET_RESULT_REMOVED + GNUNET_SET_RESULT_ADDED }; + /** * Element stored in a set. */ @@ -144,7 +202,7 @@ struct GNUNET_SET_Element /** * Application-specific element type. */ - uint16_t type; + uint16_t element_type; /** * Actual data of the element @@ -156,9 +214,10 @@ struct GNUNET_SET_Element /** * Continuation used for some of the set operations * - * @cls closure + * @param cls closure */ -typedef void (*GNUNET_SET_Continuation) (void *cls); +typedef void +(*GNUNET_SET_Continuation) (void *cls); /** @@ -166,27 +225,41 @@ typedef void (*GNUNET_SET_Continuation) (void *cls); * in the result set. * * @param cls closure - * @param element a result element, only valid if status is GNUNET_SET_STATUS_OK - * @param status see enum GNUNET_SET_Status + * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK + * @param status see `enum GNUNET_SET_Status` */ -typedef void (*GNUNET_SET_ResultIterator) (void *cls, - const struct GNUNET_SET_Element *element, - enum GNUNET_SET_Status status); +typedef void +(*GNUNET_SET_ResultIterator) (void *cls, + const struct GNUNET_SET_Element *element, + enum GNUNET_SET_Status status); + +/** + * Iterator for set elements. + * + * @param cls closure + * @param element the current element, NULL if all elements have been + * iterated over + * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop. + */ +typedef int +(*GNUNET_SET_ElementIterator) (void *cls, + const struct GNUNET_SET_Element *element); /** * Called when another peer wants to do a set operation with the - * local peer + * local peer. If a listen error occurs, the @a request is NULL. * + * @param cls closure * @param other_peer the other peer * @param context_msg message with application specific information from * the other peer - * @param request request from the other peer, use GNUNET_SET_accept + * @param request request from the other peer (never NULL), use GNUNET_SET_accept() * to accept it, otherwise the request will be refused - * Note that we don't use a return value here, as it is also - * necessary to specify the set we want to do the operation with, - * whith sometimes can be derived from the context message. - * Also necessary to specify the timeout. + * Note that we can't just return value from the listen callback, + * as it is also necessary to specify the set we want to do the + * operation with, whith sometimes can be derived from the context + * message. It's necessary to specify the timeout. */ typedef void (*GNUNET_SET_ListenCallback) (void *cls, @@ -196,6 +269,11 @@ typedef void +typedef void +(*GNUNET_SET_CopyReadyCallback) (void *cls, + struct GNUNET_SET_Handle *copy); + + /** * Create an empty set, supporting the specified operation. * @@ -215,15 +293,17 @@ GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg, /** * Add an element to the given set. * After the element has been added (in the sense of being - * transmitted to the set service), cont will be called. - * Calls to add_element can be queued + * transmitted to the set service), @a cont will be called. + * Calls to #GNUNET_SET_add_element can be queued * * @param set set to add element to * @param element element to add to the set * @param cont continuation called after the element has been added - * @param cont_cls closure for cont + * @param cont_cls closure for @a cont + * @return #GNUNET_OK on success, #GNUNET_SYSERR if the + * set is invalid (e.g. the set service crashed) */ -void +int GNUNET_SET_add_element (struct GNUNET_SET_Handle *set, const struct GNUNET_SET_Element *element, GNUNET_SET_Continuation cont, @@ -239,63 +319,70 @@ GNUNET_SET_add_element (struct GNUNET_SET_Handle *set, * @param set set to remove element from * @param element element to remove from the set * @param cont continuation called after the element has been removed - * @param cont_cls closure for cont + * @param cont_cls closure for @a cont + * @return #GNUNET_OK on success, #GNUNET_SYSERR if the + * set is invalid (e.g. the set service crashed) */ -void +int GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set, const struct GNUNET_SET_Element *element, GNUNET_SET_Continuation cont, void *cont_cls); +void +GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set, + GNUNET_SET_CopyReadyCallback cb, + void *cls); + + /** * Destroy the set handle, and free all associated resources. + * Iterations must have completed (or be explicitly canceled) + * before destroying the corresponding set. Operations may + * still be pending when a set is destroyed. + * + * @param set set to destroy */ void GNUNET_SET_destroy (struct GNUNET_SET_Handle *set); /** - * Evaluate a set operation with our set and the set of another peer. + * Prepare a set operation to be evaluated with another peer. + * The evaluation will not start until the client provides + * a local set with GNUNET_SET_commit(). * - * @param set set to use - * @param salt salt for HKDF (explain more here) * @param other_peer peer with the other set * @param app_id hash for the application using the set * @param context_msg additional information for the request - * @param salt salt used for the set operation; sometimes set operations - * fail due to hash collisions, using a different salt for each operation - * makes it harder for an attacker to exploit this - * @param timeout result_cb will be called with GNUNET_SET_STATUS_TIMEOUT - * if the operation is not done after the specified time; @deprecated * @param result_mode specified how results will be returned, - * see 'GNUNET_SET_ResultMode'. + * see `enum GNUNET_SET_ResultMode`. * @param result_cb called on error or success - * @param result_cls closure for result_cb + * @param result_cls closure for @a result_cb * @return a handle to cancel the operation */ struct GNUNET_SET_OperationHandle * -GNUNET_SET_evaluate (struct GNUNET_SET_Handle *set, - const struct GNUNET_PeerIdentity *other_peer, - const struct GNUNET_HashCode *app_id, - const struct GNUNET_MessageHeader *context_msg, - uint16_t salt, - struct GNUNET_TIME_Relative timeout, - enum GNUNET_SET_ResultMode result_mode, - GNUNET_SET_ResultIterator result_cb, - void *result_cls); +GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer, + const struct GNUNET_HashCode *app_id, + const struct GNUNET_MessageHeader *context_msg, + enum GNUNET_SET_ResultMode result_mode, + GNUNET_SET_ResultIterator result_cb, + void *result_cls); /** - * Wait for set operation requests for the given application id - * + * Wait for set operation requests for the given application ID. + * If the connection to the set service is lost, the listener is + * re-created transparently with exponential backoff. + * * @param cfg configuration to use for connecting to * the set service * @param operation operation we want to listen for * @param app_id id of the application that handles set operation requests * @param listen_cb called for each incoming request matching the operation * and application id - * @param listen_cls handle for listen_cb + * @param listen_cls handle for @a listen_cb * @return a handle that can be used to cancel the listen operation */ struct GNUNET_SET_ListenHandle * @@ -306,9 +393,9 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg, void *listen_cls); - /** - * Cancel the given listen operation. + * Cancel the given listen operation. After calling cancel, the + * listen callback for this listen handle will not be called again. * * @param lh handle for the listen operation */ @@ -316,30 +403,49 @@ void GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh); - /** - * Accept a request we got via GNUNET_SET_listen. + * Accept a request we got via GNUNET_SET_listen(). Must be called during + * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid + * afterwards. + * Call GNUNET_SET_commit() to provide the local set to use for the operation, + * and to begin the exchange with the remote peer. * * @param request request to accept - * @param set set used for the requested operation - * @param timeout timeout for the set operation, @deprecated * @param result_mode specified how results will be returned, - * see 'GNUNET_SET_ResultMode'. + * see `enum GNUNET_SET_ResultMode`. * @param result_cb callback for the results - * @param result_cls closure for result_cb + * @param result_cls closure for @a result_cb * @return a handle to cancel the operation */ struct GNUNET_SET_OperationHandle * GNUNET_SET_accept (struct GNUNET_SET_Request *request, - struct GNUNET_SET_Handle *set, - struct GNUNET_TIME_Relative timeout, enum GNUNET_SET_ResultMode result_mode, GNUNET_SET_ResultIterator result_cb, - void *cls); + void *result_cls); /** - * Cancel the given set operation. + * Commit a set to be used with a set operation. + * This function is called once we have fully constructed + * the set that we want to use for the operation. At this + * time, the P2P protocol can then begin to exchange the + * set information and call the result callback with the + * result information. + * + * @param oh handle to the set operation + * @param set the set to use for the operation + * @return #GNUNET_OK on success, #GNUNET_SYSERR if the + * set is invalid (e.g. the set service crashed) + */ +int +GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh, + struct GNUNET_SET_Handle *set); + + +/** + * Cancel the given set operation. May not be called after the + * operation's `GNUNET_SET_ResultIterator` has been called with a + * status that indicates error, timeout or done. * * @param oh set operation to cancel */ @@ -347,6 +453,55 @@ void GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh); +/** + * Iterate over all elements in the given set. + * Note that this operation involves transferring every element of the set + * from the service to the client, and is thus costly. + * Only one iteration per set may be active at the same time. + * + * @param set the set to iterate over + * @param iter the iterator to call for each element + * @param iter_cls closure for @a iter + * @return #GNUNET_YES if the iteration started successfuly, + * #GNUNET_NO if another iteration was still active, + * #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected) + */ +int +GNUNET_SET_iterate (struct GNUNET_SET_Handle *set, + GNUNET_SET_ElementIterator iter, + void *iter_cls); + +/** + * Stop iteration over all elements in the given set. Can only + * be called before the iteration has "naturally" completed its + * turn. + * + * @param set the set to stop iterating over + */ +void +GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set); + +/** + * Create a copy of an element. The copy + * must be GNUNET_free-d by the caller. + * + * @param element the element to copy + * @return the copied element + */ +struct GNUNET_SET_Element * +GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element); + +/** + * Hash a set element. + * + * @param element the element that should be hashed + * @param ret_hash a pointer to where the hash of @a element + * should be stored + */ +void +GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element, struct GNUNET_HashCode *ret_hash); + + #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -355,3 +510,5 @@ GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh); #endif #endif + +/** @} */ /* end of group */