/*
This file is part of GNUnet.
- (C) 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009 Christian Grothoff (and other contributing authors)
+ (C) 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
*/
struct GNUNET_CONTAINER_MetaData;
-/**
- * Iterator over meta data.
- *
- * @param cls closure
- * @param type type of the meta data
- * @param data value of the meta data
- * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
- */
-typedef int (*GNUNET_CONTAINER_MetaDataProcessor) (void *cls,
- EXTRACTOR_KeywordType type,
- const char *data);
-
/**
* Create a fresh MetaData token.
*
* @return empty meta-data container
*/
-struct GNUNET_CONTAINER_MetaData *GNUNET_CONTAINER_meta_data_create (void);
+struct GNUNET_CONTAINER_MetaData *
+GNUNET_CONTAINER_meta_data_create (void);
/**
* Duplicate a MetaData token.
* @param md what to duplicate
* @return duplicate meta-data container
*/
-struct GNUNET_CONTAINER_MetaData *GNUNET_CONTAINER_meta_data_duplicate (const
- struct
- GNUNET_CONTAINER_MetaData
- *md);
+struct GNUNET_CONTAINER_MetaData *
+GNUNET_CONTAINER_meta_data_duplicate (const struct
+ GNUNET_CONTAINER_MetaData *md);
/**
* Free meta data.
*
* @param md what to free
*/
-void GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData
- *md);
+void
+GNUNET_CONTAINER_meta_data_destroy (struct GNUNET_CONTAINER_MetaData *md);
/**
- * Test if two MDs are equal.
+ * Test if two MDs are equal. We consider them equal if
+ * the meta types, formats and content match (we do not
+ * include the mime types and plugins names in this
+ * consideration).
*
* @param md1 first value to check
* @param md2 other value to check
* @return GNUNET_YES if they are equal
*/
-int GNUNET_CONTAINER_meta_data_test_equal (const struct
- GNUNET_CONTAINER_MetaData *md1,
- const struct
- GNUNET_CONTAINER_MetaData *md2);
+int
+GNUNET_CONTAINER_meta_data_test_equal (const struct
+ GNUNET_CONTAINER_MetaData *md1,
+ const struct
+ GNUNET_CONTAINER_MetaData *md2);
/**
* Extend metadata.
*
* @param md metadata to extend
- * @param type type of the new entry
- * @param data value for the entry
+ * @param plugin_name name of the plugin that produced this value;
+ * special values can be used (i.e. '<zlib>' for zlib being
+ * used in the main libextractor library and yielding
+ * meta data).
+ * @param type libextractor-type describing the meta data
+ * @param format basic format information about data
+ * @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
* @return GNUNET_OK on success, GNUNET_SYSERR if this entry already exists
+ * data_mime_type and plugin_name are not considered for "exists" checks
+ */
+int
+GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
+ const char *plugin_name,
+ enum EXTRACTOR_MetaType type,
+ enum EXTRACTOR_MetaFormat format,
+ const char *data_mime_type,
+ const char *data,
+ size_t data_len);
+
+
+/**
+ * Extend metadata. Merges the meta data from the second argument
+ * into the first, discarding duplicate key-value pairs.
+ *
+ * @param md metadata to extend
+ * @param in metadata to merge
*/
-int GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
- EXTRACTOR_KeywordType type,
- const char *data);
+void
+GNUNET_CONTAINER_meta_data_merge (struct GNUNET_CONTAINER_MetaData *md,
+ const struct GNUNET_CONTAINER_MetaData *in);
+
/**
* Remove an item.
* @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
* @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,
- EXTRACTOR_KeywordType type,
- const char *data);
+int
+GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
+ enum EXTRACTOR_MetaType type,
+ const char *data,
+ size_t data_len);
+
+
+/**
+ * Remove all items in the container.
+ *
+ * @param md metadata to manipulate
+ */
+void
+GNUNET_CONTAINER_meta_data_clear (struct GNUNET_CONTAINER_MetaData *md);
+
/**
* Add the current time as the publication date
*
* @param md metadata to modify
*/
-void GNUNET_CONTAINER_meta_data_add_publication_date (struct
- GNUNET_CONTAINER_MetaData
- *md);
+void
+GNUNET_CONTAINER_meta_data_add_publication_date (struct
+ GNUNET_CONTAINER_MetaData
+ *md);
+
/**
- * Iterate over MD entries, excluding thumbnails.
+ * Iterate over MD entries.
*
* @param md metadata to inspect
* @param iter function to call on each entry
* @param iter_cls closure for iterator
* @return number of entries
*/
-int GNUNET_CONTAINER_meta_data_get_contents (const struct
- GNUNET_CONTAINER_MetaData *md,
- GNUNET_CONTAINER_MetaDataProcessor
- iter, void *iter_cls);
+int GNUNET_CONTAINER_meta_data_iterate (const struct
+ GNUNET_CONTAINER_MetaData *md,
+ EXTRACTOR_MetaDataProcessor
+ iter, void *iter_cls);
/**
- * Get the first MD entry of the given type.
+ * Get the first MD entry of the given type. Caller
+ * is responsible for freeing the return value.
+ * Also, only meta data items that are strings (0-terminated)
+ * are returned by this function.
*
* @param md metadata to inspect
* @param type type to look for
- * @return NULL if we do not have any such entry,
- * otherwise client is responsible for freeing the value!
+ * @return NULL if no entry was found
*/
-char *GNUNET_CONTAINER_meta_data_get_by_type (const struct
- GNUNET_CONTAINER_MetaData *md,
- EXTRACTOR_KeywordType type);
+char *
+GNUNET_CONTAINER_meta_data_get_by_type (const struct
+ GNUNET_CONTAINER_MetaData *md,
+ enum EXTRACTOR_MetaType type);
+
/**
- * Get the first matching MD entry of the given types.
+ * Get the first matching MD entry of the given types. Caller is
+ * responsible for freeing the return value. Also, only meta data
+ * items that are strings (0-terminated) are returned by this
+ * function.
*
* @param md metadata to inspect
* @param ... -1-terminated list of types
* @return NULL if we do not have any such entry,
* otherwise client is responsible for freeing the value!
*/
-char *GNUNET_CONTAINER_meta_data_get_first_by_types (const struct
- GNUNET_CONTAINER_MetaData
- *md, ...);
+char *
+GNUNET_CONTAINER_meta_data_get_first_by_types (const struct
+ GNUNET_CONTAINER_MetaData
+ *md, ...);
/**
- * Get a thumbnail from the meta-data (if present).
+ * Get a thumbnail from the meta-data (if present). Only matches meta
+ * data with mime type "image" and binary format.
*
* @param md metadata to inspect
* @param thumb will be set to the thumbnail data. Must be
* freed by the caller!
* @return number of bytes in thumbnail, 0 if not available
*/
-size_t GNUNET_CONTAINER_meta_data_get_thumbnail (const struct
- GNUNET_CONTAINER_MetaData
- *md, unsigned char **thumb);
+size_t
+GNUNET_CONTAINER_meta_data_get_thumbnail (const struct
+ GNUNET_CONTAINER_MetaData
+ *md, unsigned char **thumb);
-/**
- * Extract meta-data from a file.
- *
- * @param md metadata to set
- * @param filename name of file to inspect
- * @param extractors plugins to use
- * @return GNUNET_SYSERR on error, otherwise the number
- * of meta-data items obtained
- */
-int GNUNET_CONTAINER_meta_data_extract_from_file (struct
- GNUNET_CONTAINER_MetaData
- *md, const char *filename,
- EXTRACTOR_ExtractorList *
- extractors);
/**
* Serialize meta-data to target.
*
* @param md metadata to serialize
- * @param target where to write the serialized metadata
+ * @param target where to write the serialized metadata;
+ * *target can be NULL, in which case memory is allocated
* @param max maximum number of bytes available
* @param opt is it ok to just write SOME of the
* meta-data to match the size constraint,
*/
ssize_t GNUNET_CONTAINER_meta_data_serialize (const struct
GNUNET_CONTAINER_MetaData *md,
- char *target,
+ char **target,
size_t max,
enum
GNUNET_CONTAINER_MetaDataSerializationOptions
/**
- * Estimate (!) the size of the meta-data in
- * serialized form. The estimate MAY be higher
- * than what is strictly needed.
+ * Get the size of the full meta-data in serialized form.
*
* @param md metadata to inspect
- * @param opt is it ok to just write SOME of the
- * meta-data to match the size constraint,
- * possibly discarding some data?
* @return number of bytes needed for serialization, -1 on error
*/
ssize_t GNUNET_CONTAINER_meta_data_get_serialized_size (const struct
GNUNET_CONTAINER_MetaData
- *md,
- enum
- GNUNET_CONTAINER_MetaDataSerializationOptions
- opt);
+ *md);
+
/**
* Deserialize meta-data. Initializes md.
*GNUNET_CONTAINER_meta_data_deserialize (const char *input,
size_t size);
-/**
- * Does the meta-data claim that this is a directory?
- * Checks if the mime-type is that of a GNUnet directory.
- *
- * @param md metadata to inspect
- * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if
- * we have no mime-type information (treat as 'GNUNET_NO')
- */
-int GNUNET_CONTAINER_meta_data_test_for_directory (const struct
- GNUNET_CONTAINER_MetaData
- *md);
-
/* ******************************* HashMap **************************** */
/**
- * Iterator over HashCodes.
+ * Iterator over hash map entries.
*
* @param cls closure
* @param key current key code
/* ******************** doubly-linked list *************** */
/**
- * Insert an element into a DLL. Assumes
- * that head, tail and element are structs
- * with prev and next fields.
+ * Insert an element at the head of a DLL. Assumes that head, tail and
+ * element are structs with prev and next fields.
*
* @param head pointer to the head of the DLL
* @param tail pointer to the tail of the DLL
* @param element element to insert
*/
-#define GNUNET_CONTAINER_DLL_insert(head,tail,element) \
+#define GNUNET_CONTAINER_DLL_insert(head,tail,element) do { \
(element)->next = (head); \
(element)->prev = NULL; \
if ((tail) == NULL) \
(tail) = element; \
else \
(head)->prev = element; \
- (head) = (element);
+ (head) = (element); } while (0)
/**
- * Insert an element into a DLL after the given other
- * element. Insert at the head if the other
- * element is NULL.
+ * Insert an element into a DLL after the given other element. Insert
+ * at the head if the other element is NULL.
*
* @param head pointer to the head of the DLL
* @param tail pointer to the tail of the DLL
* @param other prior element, NULL for insertion at head of DLL
* @param element element to insert
*/
-#define GNUNET_CONTAINER_DLL_insert_after(head,tail,other,element) \
+#define GNUNET_CONTAINER_DLL_insert_after(head,tail,other,element) do { \
(element)->prev = (other); \
if (NULL == other) \
{ \
if (NULL == (element)->next) \
(tail) = (element); \
else \
- (element)->next->prev = (element);
+ (element)->next->prev = (element); } while (0)
* @param tail pointer to the tail of the DLL
* @param element element to remove
*/
-#define GNUNET_CONTAINER_DLL_remove(head,tail,element) \
+#define GNUNET_CONTAINER_DLL_remove(head,tail,element) do { \
if ((element)->prev == NULL) \
(head) = (element)->next; \
else \
if ((element)->next == NULL) \
(tail) = (element)->prev; \
else \
- (element)->next->prev = (element)->prev;
+ (element)->next->prev = (element)->prev; } while (0)
void *iterator_cls);
+/**
+ * Return a *uniform* random element from the heap. Choose a random
+ * number between 0 and heap size and then walk directly to it.
+ * This cost can be between 0 and n, amortized cost of logN.
+ *
+ * @param heap heap to choose random element from
+ * @param max how many nodes from the heap to choose from
+ *
+ * @return data stored at the chosen random node,
+ * NULL if the heap is empty.
+ *
+ */
+void *
+GNUNET_CONTAINER_heap_get_random (struct GNUNET_CONTAINER_Heap *heap, uint32_t max);
+
/**
* Perform a random walk of the tree. The walk is biased
* towards elements closer to the root of the tree (since
projects / oweals / gnunet.git / blobdiff