-peer review
[oweals/gnunet.git] / src / include / gnunet_container_lib.h
index 0c7f60a7a3acbd6812bc204f8da1374e7a3290c3..96946d02dec13938f495f2a6307fcf9c2b63ed20 100644 (file)
@@ -62,7 +62,7 @@ struct GNUNET_CONTAINER_BloomFilter;
  * @return GNUNET_YES if next was updated
  *         GNUNET_NO if there are no more entries
  */
-typedef int (*GNUNET_HashCodeIterator) (void *cls, GNUNET_HashCode * next);
+typedef int (*GNUNET_HashCodeIterator) (void *cls, struct GNUNET_HashCode * next);
 
 
 /**
@@ -70,7 +70,8 @@ typedef int (*GNUNET_HashCodeIterator) (void *cls, GNUNET_HashCode * next);
  *
  * @param filename the name of the file (or the prefix)
  * @param size the size of the bloom-filter (number of
- *        bytes of storage space to use)
+ *        bytes of storage space to use); will be rounded up
+ *        to next power of 2
  * @param k the number of GNUNET_CRYPTO_hash-functions to apply per
  *        element (number of bits set per element in the set)
  * @return the bloomfilter
@@ -120,7 +121,7 @@ GNUNET_CONTAINER_bloomfilter_get_raw_data (const struct
  */
 int
 GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
-                                   *bf, const GNUNET_HashCode * e);
+                                   *bf, const struct GNUNET_HashCode * e);
 
 
 /**
@@ -130,7 +131,7 @@ GNUNET_CONTAINER_bloomfilter_test (const struct GNUNET_CONTAINER_BloomFilter
  */
 void
 GNUNET_CONTAINER_bloomfilter_add (struct GNUNET_CONTAINER_BloomFilter *bf,
-                                  const GNUNET_HashCode * e);
+                                  const struct GNUNET_HashCode * e);
 
 
 /**
@@ -140,7 +141,7 @@ GNUNET_CONTAINER_bloomfilter_add (struct GNUNET_CONTAINER_BloomFilter *bf,
  */
 void
 GNUNET_CONTAINER_bloomfilter_remove (struct GNUNET_CONTAINER_BloomFilter *bf,
-                                     const GNUNET_HashCode * e);
+                                     const struct GNUNET_HashCode * e);
 
 
 /**
@@ -293,7 +294,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct GNUNET_CONTAINER_MetaData
  * @param data_mime_type mime-type of data (not of the original file);
  *        can be NULL (if mime-type is not known)
  * @param data actual meta-data found
- * @param data_len number of bytes in data
+ * @param data_size number of bytes in data
  * @return GNUNET_OK on success, GNUNET_SYSERR if this entry already exists
  *         data_mime_type and plugin_name are not considered for "exists" checks
  */
@@ -303,7 +304,7 @@ GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
                                    enum EXTRACTOR_MetaType type,
                                    enum EXTRACTOR_MetaFormat format,
                                    const char *data_mime_type, const char *data,
-                                   size_t data_len);
+                                   size_t data_size);
 
 
 /**
@@ -325,13 +326,13 @@ GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
  * @param type type of the item to remove
  * @param data specific value to remove, NULL to remove all
  *        entries of the given type
- * @param data_len number of bytes in data
+ * @param data_size number of bytes in data
  * @return GNUNET_OK on success, GNUNET_SYSERR if the item does not exist in md
  */
 int
 GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
                                    enum EXTRACTOR_MetaType type,
-                                   const char *data, size_t data_len);
+                                   const char *data, size_t data_size);
 
 
 /**
@@ -533,7 +534,7 @@ enum GNUNET_CONTAINER_MultiHashMapOption
  *         GNUNET_NO if not.
  */
 typedef int (*GNUNET_CONTAINER_HashMapIterator) (void *cls,
-                                                 const GNUNET_HashCode * key,
+                                                 const struct GNUNET_HashCode * key,
                                                  void *value);
 
 
@@ -570,7 +571,7 @@ GNUNET_CONTAINER_multihashmap_destroy (struct GNUNET_CONTAINER_MultiHashMap
  */
 void *
 GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
-                                   *map, const GNUNET_HashCode * key);
+                                   *map, const struct GNUNET_HashCode * key);
 
 
 /**
@@ -586,7 +587,7 @@ GNUNET_CONTAINER_multihashmap_get (const struct GNUNET_CONTAINER_MultiHashMap
  */
 int
 GNUNET_CONTAINER_multihashmap_remove (struct GNUNET_CONTAINER_MultiHashMap *map,
-                                      const GNUNET_HashCode * key, void *value);
+                                      const struct GNUNET_HashCode * key, void *value);
 
 /**
  * Remove all entries for the given key from the map.
@@ -598,7 +599,7 @@ GNUNET_CONTAINER_multihashmap_remove (struct GNUNET_CONTAINER_MultiHashMap *map,
  */
 int
 GNUNET_CONTAINER_multihashmap_remove_all (struct GNUNET_CONTAINER_MultiHashMap
-                                          *map, const GNUNET_HashCode * key);
+                                          *map, const struct GNUNET_HashCode * key);
 
 
 /**
@@ -613,7 +614,7 @@ GNUNET_CONTAINER_multihashmap_remove_all (struct GNUNET_CONTAINER_MultiHashMap
 int
 GNUNET_CONTAINER_multihashmap_contains (const struct
                                         GNUNET_CONTAINER_MultiHashMap *map,
-                                        const GNUNET_HashCode * key);
+                                        const struct GNUNET_HashCode * key);
 
 
 /**
@@ -629,7 +630,7 @@ GNUNET_CONTAINER_multihashmap_contains (const struct
 int
 GNUNET_CONTAINER_multihashmap_contains_value (const struct
                                               GNUNET_CONTAINER_MultiHashMap
-                                              *map, const GNUNET_HashCode * key,
+                                              *map, const struct GNUNET_HashCode * key,
                                               const void *value);
 
 
@@ -647,7 +648,7 @@ GNUNET_CONTAINER_multihashmap_contains_value (const struct
  */
 int
 GNUNET_CONTAINER_multihashmap_put (struct GNUNET_CONTAINER_MultiHashMap *map,
-                                   const GNUNET_HashCode * key, void *value,
+                                   const struct GNUNET_HashCode * key, void *value,
                                    enum GNUNET_CONTAINER_MultiHashMapOption
                                    opt);
 
@@ -691,7 +692,7 @@ GNUNET_CONTAINER_multihashmap_iterate (const struct
 int
 GNUNET_CONTAINER_multihashmap_get_multiple (const struct
                                             GNUNET_CONTAINER_MultiHashMap *map,
-                                            const GNUNET_HashCode * key,
+                                            const struct GNUNET_HashCode * key,
                                             GNUNET_CONTAINER_HashMapIterator it,
                                             void *it_cls);
 
@@ -1054,7 +1055,24 @@ struct GNUNET_CONTAINER_SList;
 /**
  * Handle to a singly linked list iterator
  */
-struct GNUNET_CONTAINER_SList_Iterator;
+struct GNUNET_CONTAINER_SList_Iterator
+{
+  /**
+   * Linked list that we are iterating over.
+   */
+  struct GNUNET_CONTAINER_SList *list;
+
+  /**
+   * Last element accessed.
+   */
+  struct GNUNET_CONTAINER_SList_Elem *last;
+
+  /**
+   * Current list element.
+   */
+  struct GNUNET_CONTAINER_SList_Elem *elem;
+};
+
 
 
 /**
@@ -1113,9 +1131,11 @@ GNUNET_CONTAINER_slist_destroy (struct GNUNET_CONTAINER_SList *l);
  * Return the beginning of a list
  *
  * @param l list
- * @return iterator pointing to the beginning, free using "GNUNET_free"
+ * @return iterator pointing to the beginning (by value! Either allocate the
+ *   structure on the stack, or use GNUNET_malloc() yourself! All other
+ *   functions do take pointer to this struct though)
  */
-struct GNUNET_CONTAINER_SList_Iterator *
+struct GNUNET_CONTAINER_SList_Iterator
 GNUNET_CONTAINER_slist_begin (struct GNUNET_CONTAINER_SList *l);
 
 
@@ -1133,12 +1153,28 @@ GNUNET_CONTAINER_slist_clear (struct GNUNET_CONTAINER_SList *l);
  * @param l list
  * @param buf payload buffer to find
  * @param len length of the payload (number of bytes in buf)
+ *
+ * @return GNUNET_YES if found, GNUNET_NO otherwise
  */
 int
 GNUNET_CONTAINER_slist_contains (const struct GNUNET_CONTAINER_SList *l,
                                  const void *buf, size_t len);
 
-
+/**
+ * Check if a list contains a certain element using 'compare' function
+ *
+ * @param l list
+ * @param buf payload buffer to find
+ * @param len length of the payload (number of bytes in buf)
+ * @param compare comparison function
+ *
+ * @return NULL if the 'buf' could not be found, pointer to the
+ *         list element, if found
+ */
+void *
+GNUNET_CONTAINER_slist_contains2 (const struct GNUNET_CONTAINER_SList *l,
+                                  const void *buf, size_t len,
+                                  int (*compare)(const void *, const size_t, const void *, const size_t));
 /**
  * Count the elements of a list
  * @param l list