X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_set_service.h;h=44773f1872457753d44769225482e0b58ffe8c5f;hb=7a7ec54a324da4820202582126795a8ac6bbe94d;hp=1e59c02c9a64aff22c5841256f51d439ff3b98ec;hpb=8b22d09975edd5b61ec9d11334628d8ab04fcb09;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index 1e59c02c9..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 notified of the required changes
+   * for both the local and the remote set.
+   *
+   * Only supported for set
+   */
+  GNUNET_SET_RESULT_SYMMETRIC,
+
   /**
-   * Client gets only elements that have been added to the set.
-   * Only works with set union.
+   * Client gets only elements that have been removed from the set.
+   *
+   * Only supported for set intersection.
    */
-  GNUNET_SET_RESULT_ADDED,
+  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
 };
 
 
@@ -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);
 
 
 /**
@@ -181,34 +225,36 @@ 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 element
- * @return GNUNET_YES to continue iterating, GNUNET_NO to stop.
+ * @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);
+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. If a listen error occurs, the 'request' is NULL.
+ * 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
- *        Will be NULL if the listener failed.
+ * @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 can't just return value from the listen callback,
  *        as it is also necessary to specify the set we want to do the
@@ -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.
  *
@@ -242,14 +293,14 @@ 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
- * @return GNUNET_OK on success, GNUNET_SYSERR if the
+ * @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)
  */
 int
@@ -268,8 +319,8 @@ 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
- * @return GNUNET_OK on success, GNUNET_SYSERR if the
+ * @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)
  */
 int
@@ -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);
@@ -289,40 +351,38 @@ GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
 /**
  * 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.
+ * a local set with GNUNET_SET_commit().
  *
  * @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 '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_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);
 
 
 /**
- * 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 *
@@ -334,7 +394,8 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 
 /**
- * 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
  */
@@ -343,17 +404,17 @@ GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 
 
 /**
- * Accept a request we got via GNUNET_SET_listen.  Must be called during
- * GNUNET_SET_listen, as the 'struct GNUNET_SET_Request' becomes invalid
+ * 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. 
+ * 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 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 *
@@ -371,9 +432,9 @@ GNUNET_SET_accept (struct GNUNET_SET_Request *request,
  * set information and call the result callback with the
  * result information.
  *
- * @param oh handle to the set operation 
+ * @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
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
  *         set is invalid (e.g. the set service crashed)
  */
 int
@@ -382,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
  */
@@ -396,16 +457,49 @@ 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 cls closure for 'iter'
- * @return GNUNET_YES if every element was iterated over, GNUNET_NO
- *         if the iterator prematurely stopped, 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 */
@@ -416,3 +510,5 @@ GNUNET_SET_iterate (struct GNUNET_SET_Handle *set, GNUNET_SET_ElementIterator it
 #endif
 
 #endif
+
+/** @} */  /* end of group */