X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_set_service.h;h=44773f1872457753d44769225482e0b58ffe8c5f;hb=7a7ec54a324da4820202582126795a8ac6bbe94d;hp=b088e335f5faea126b64db000c6d0793a04360bc;hpb=5ccd7acfa1ed8157feda8ff53dff7d2772f3d1ed;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h index b088e335f..44773f187 100644 --- a/src/include/gnunet_set_service.h +++ b/src/include/gnunet_set_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,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 @@ -74,8 +82,7 @@ struct GNUNET_SET_OperationHandle; enum GNUNET_SET_OperationType { /** - * A purely local set that does not support any - * operation. + * A purely local set that does not support any operation. */ GNUNET_SET_OPERATION_NONE, @@ -90,20 +97,41 @@ enum GNUNET_SET_OperationType 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, @@ -112,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, @@ -131,18 +160,32 @@ 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 works with set intersection. + * + * Only supported for set intersection. */ - GNUNET_SET_RESULT_REMOVED + GNUNET_SET_RESULT_REMOVED, + + /** + * Client gets only elements that have been removed from the set. + * + * Only supported for set union. + */ + GNUNET_SET_RESULT_ADDED }; @@ -159,7 +202,7 @@ struct GNUNET_SET_Element /** * Application-specific element type. */ - uint16_t type; + uint16_t element_type; /** * Actual data of the element @@ -173,7 +216,8 @@ struct GNUNET_SET_Element * * @param cls closure */ -typedef void (*GNUNET_SET_Continuation) (void *cls); +typedef void +(*GNUNET_SET_Continuation) (void *cls); /** @@ -184,9 +228,10 @@ typedef void (*GNUNET_SET_Continuation) (void *cls); * @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. @@ -196,8 +241,9 @@ typedef void (*GNUNET_SET_ResultIterator) (void *cls, * 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); +typedef int +(*GNUNET_SET_ElementIterator) (void *cls, + const struct GNUNET_SET_Element *element); /** @@ -223,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. * @@ -279,8 +330,19 @@ GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set, 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); @@ -294,9 +356,6 @@ GNUNET_SET_destroy (struct GNUNET_SET_Handle *set); * @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 result_mode specified how results will be returned, * see `enum GNUNET_SET_ResultMode`. * @param result_cb called on error or success @@ -307,7 +366,6 @@ struct GNUNET_SET_OperationHandle * GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer, const struct GNUNET_HashCode *app_id, const struct GNUNET_MessageHeader *context_msg, - uint16_t salt, enum GNUNET_SET_ResultMode result_mode, GNUNET_SET_ResultIterator result_cb, void *result_cls); @@ -324,7 +382,7 @@ GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer, * @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 * @@ -336,9 +394,8 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg, /** - * Cancel the given listen operation. - * After calling cancel, the listen callback for this listen handle - * will not be called again. + * 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 */ @@ -386,9 +443,9 @@ GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh, /** - * 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. + * 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 */ @@ -404,12 +461,45 @@ GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh); * * @param set the set to iterate over * @param iter the iterator to call for each element - * @param cls closure for 'iter' - * @return GNUNET_YES if the iteration started successfuly, - * GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected) + * @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 *cls); +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 */ @@ -420,3 +510,5 @@ GNUNET_SET_iterate (struct GNUNET_SET_Handle *set, GNUNET_SET_ElementIterator it #endif #endif + +/** @} */ /* end of group */