introducing GNUNET_CRYPTO_ecdhe_create2() to avoid malloc nonsense

[oweals/gnunet.git] / src / include / gnunet_set_service.h

diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index e28fad754c3287da785b6b7c765560e080539256..44773f1872457753d44769225482e0b58ffe8c5f 100644 (file)
--- a/src/include/gnunet_set_service.h
+++ b/src/include/gnunet_set_service.h
@@ -1,6 +1,6 @@
 /*
       This file is part of GNUnet
-      Copyright (C) 2013, 2014 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
@@ -19,10 +19,18 @@
  */
 
 /**
- * @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
@@ -99,9 +107,32 @@ enum GNUNET_SET_Status
    * 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,
 
+  /**
+   * 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_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,
    * or something went wrong.
@@ -129,20 +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_SYMMETRIC,
+
+  /**
+   * 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
 };
 
 
@@ -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,6 +330,12 @@ 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)
@@ -424,6 +481,26 @@ GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
 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 */
 {
@@ -433,3 +510,5 @@ GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
 #endif
 
 #endif
+
+/** @} */  /* end of group */