even nicer indentation, thanks to LRN's indent patch

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

diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index 5449f632436457c57380ad56fcd2406408de86cf..e8026a66f60e696399c0dcd086023363704d9029 100644 (file)
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -4,7 +4,7 @@
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published

-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -21,10 +21,6 @@
  * @file include/gnunet_fs_service.h
  * @brief API for file-sharing via GNUnet 
  * @author Christian Grothoff
  * @file include/gnunet_fs_service.h
  * @brief API for file-sharing via GNUnet 
  * @author Christian Grothoff

- *
- * TODO:
- * - extend API with support for publish simulation (-s)
- *   and URI-argument binding to keyword/namespace (-u)

  */
 #ifndef GNUNET_FS_LIB_H
 #define GNUNET_FS_LIB_H
  */
 #ifndef GNUNET_FS_LIB_H
 #define GNUNET_FS_LIB_H


@@ -83,9 +79,8 @@ struct GNUNET_FS_Uri;
  * @param is_mandatory is the keyword mandatory (in a search)
  * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
  */
  * @param is_mandatory is the keyword mandatory (in a search)
  * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
  */

-typedef int (*GNUNET_FS_KeywordIterator) (void *cls,
-                                         const char *keyword,
-                                         int is_mandatory);
+typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword,
+                                          int is_mandatory);

 
 /**
  * Get a unique key from a URI.  This is for putting URIs
 
 /**
  * Get a unique key from a URI.  This is for putting URIs


@@ -94,9 +89,8 @@ typedef int (*GNUNET_FS_KeywordIterator) (void *cls,
  * @param uri uri to convert to a unique key
  * @param key wherer to store the unique key
  */
  * @param uri uri to convert to a unique key
  * @param key wherer to store the unique key
  */

-void 
-GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri,
-                     GNUNET_HashCode * key);
+void
+GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, GNUNET_HashCode * key);

 
 /**
  * Convert a URI to a UTF-8 String.
 
 /**
  * Convert a URI to a UTF-8 String.


@@ -118,6 +112,31 @@ char *
 GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
 
 

+/**
+ * Add the given keyword to the set of keywords represented by the URI.
+ * Does nothing if the keyword is already present.
+ *
+ * @param uri ksk uri to modify
+ * @param keyword keyword to add
+ * @param is_mandatory is this keyword mandatory?
+ */
+void
+GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri, const char *keyword,
+                               int is_mandatory);
+
+
+/**
+ * Remove the given keyword from the set of keywords represented by the URI.
+ * Does nothing if the keyword is not present.
+ *
+ * @param uri ksk uri to modify
+ * @param keyword keyword to add
+ */
+void
+GNUNET_FS_uri_ksk_remove_keyword (struct GNUNET_FS_Uri *uri,
+                                  const char *keyword);
+
+

 /**
  * Convert a UTF-8 String to a URI.
  *
 /**
  * Convert a UTF-8 String to a URI.
  *


@@ -126,15 +145,14 @@ GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
  * @return NULL on error
  */
 struct GNUNET_FS_Uri *
  * @return NULL on error
  */
 struct GNUNET_FS_Uri *

-GNUNET_FS_uri_parse (const char *uri,
-                    char **emsg);
+GNUNET_FS_uri_parse (const char *uri, char **emsg);

 
 /**
  * Free URI.
  *
  * @param uri uri to free
  */
 
 /**
  * Free URI.
  *
  * @param uri uri to free
  */

-void 
+void

 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
 
 


@@ -144,7 +162,7 @@ GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri);
  * @param uri ksk uri to get the number of keywords from
  * @return 0 if this is not a keyword URI
  */
  * @param uri ksk uri to get the number of keywords from
  * @return 0 if this is not a keyword URI
  */

-unsigned int 
+unsigned int

 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
 
 


@@ -157,10 +175,10 @@ GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
  * @return -1 if this is not a keyword URI, otherwise number of
  *   keywords iterated over until iterator aborted
  */
  * @return -1 if this is not a keyword URI, otherwise number of
  *   keywords iterated over until iterator aborted
  */

-int 
+int

 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
 GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,

-                               GNUNET_FS_KeywordIterator iterator, 
-                               void *iterator_cls);
+                                GNUNET_FS_KeywordIterator iterator,
+                                void *iterator_cls);

 
 
 /**
 
 
 /**


@@ -172,7 +190,7 @@ GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
  */
 int
 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
  */
 int
 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,

-                                    struct GNUNET_PeerIdentity * peer);
+                                     struct GNUNET_PeerIdentity *peer);

 
 
 /**
 
 
 /**


@@ -205,8 +223,8 @@ GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
  */
 struct GNUNET_FS_Uri *
 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,
  */
 struct GNUNET_FS_Uri *
 GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri,

-                         struct GNUNET_CONFIGURATION_Handle *cfg,
-                         struct GNUNET_TIME_Absolute expiration_time);
+                          const struct GNUNET_CONFIGURATION_Handle *cfg,
+                          struct GNUNET_TIME_Absolute expiration_time);

 
 
 /**
 
 
 /**


@@ -232,7 +250,7 @@ GNUNET_FS_uri_ksk_canonicalize (const struct GNUNET_FS_Uri *uri);
  */
 struct GNUNET_FS_Uri *
 GNUNET_FS_uri_ksk_merge (const struct GNUNET_FS_Uri *u1,
  */
 struct GNUNET_FS_Uri *
 GNUNET_FS_uri_ksk_merge (const struct GNUNET_FS_Uri *u1,

-                        const struct GNUNET_FS_Uri *u2);
+                         const struct GNUNET_FS_Uri *u2);

 
 
 /**
 
 
 /**


@@ -263,8 +281,7 @@ GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri);
  *  if keywords is not legal (i.e. empty).
  */
 struct GNUNET_FS_Uri *
  *  if keywords is not legal (i.e. empty).
  */
 struct GNUNET_FS_Uri *

-GNUNET_FS_uri_ksk_create (const char *keywords,
-                         char **emsg);
+GNUNET_FS_uri_ksk_create (const char *keywords, char **emsg);

 
 
 /**
 
 
 /**


@@ -285,8 +302,7 @@ GNUNET_FS_uri_ksk_create (const char *keywords,
  *  if keywords is not legal (i.e. empty).
  */
 struct GNUNET_FS_Uri *
  *  if keywords is not legal (i.e. empty).
  */
 struct GNUNET_FS_Uri *

-GNUNET_FS_uri_ksk_create_from_args (unsigned int argc,
-                                   const char **argv);
+GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, const char **argv);

 
 
 /**
 
 
 /**


@@ -296,9 +312,9 @@ GNUNET_FS_uri_ksk_create_from_args (unsigned int argc,
  * @param u2 the other URI
  * @return GNUNET_YES if the URIs are equal
  */
  * @param u2 the other URI
  * @return GNUNET_YES if the URIs are equal
  */

-int 
+int

 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,

-                         const struct GNUNET_FS_Uri *u2);
+                          const struct GNUNET_FS_Uri *u2);

 
 
 /**
 
 
 /**


@@ -311,6 +327,36 @@ int
 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
 
 

+/**
+ * Handle to one of our namespaces.
+ */
+struct GNUNET_FS_Namespace;
+
+
+/**
+ * Create an SKS URI from a namespace and an identifier.
+ *
+ * @param ns namespace
+ * @param id identifier
+ * @param emsg where to store an error message
+ * @return an FS URI for the given namespace and identifier
+ */
+struct GNUNET_FS_Uri *
+GNUNET_FS_uri_sks_create (struct GNUNET_FS_Namespace *ns, const char *id,
+                          char **emsg);
+
+
+/**
+ * Create an SKS URI from a namespace ID and an identifier.
+ *
+ * @param nsid namespace ID
+ * @param id identifier
+ * @return an FS URI for the given namespace and identifier
+ */
+struct GNUNET_FS_Uri *
+GNUNET_FS_uri_sks_create_from_nsid (GNUNET_HashCode * nsid, const char *id);
+
+

 /**
  * Get the ID of a namespace from the given
  * namespace URI.
 /**
  * Get the ID of a namespace from the given
  * namespace URI.


@@ -319,9 +365,9 @@ GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
  * @param nsid where to store the ID of the namespace
  * @return GNUNET_OK on success
  */
  * @param nsid where to store the ID of the namespace
  * @return GNUNET_OK on success
  */

-int 
+int

 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,

-                                GNUNET_HashCode * nsid);
+                                 GNUNET_HashCode * nsid);

 
 
 /**
 
 
 /**


@@ -344,7 +390,7 @@ GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
  */
 char *
 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
  */
 char *
 GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,

-                                  const struct GNUNET_FS_Uri *uri);
+                                   const struct GNUNET_FS_Uri *uri);

 
 
 /**
 
 
 /**


@@ -353,7 +399,7 @@ GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
  * @param uri the uri
  * @return GNUNET_YES if this is a KSK uri
  */
  * @param uri the uri
  * @return GNUNET_YES if this is a KSK uri
  */

-int 
+int

 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
 
 


@@ -363,7 +409,7 @@ GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
  * @param uri the uri to check
  * @return GNUNET_YES if this is a CHK uri
  */
  * @param uri the uri to check
  * @return GNUNET_YES if this is a CHK uri
  */

-int 
+int

 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
 
 


@@ -374,7 +420,7 @@ GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
  * @param uri the CHK (or LOC) URI to inspect
  * @return size of the file as specified in the CHK URI
  */
  * @param uri the CHK (or LOC) URI to inspect
  * @return size of the file as specified in the CHK URI
  */

-uint64_t 
+uint64_t

 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
 
 


@@ -384,7 +430,7 @@ GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
  * @param uri the uri to check
  * @return GNUNET_YES if this is a LOC uri
  */
  * @param uri the uri to check
  * @return GNUNET_YES if this is a LOC uri
  */

-int 
+int

 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
 
 
 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
 
 


@@ -397,7 +443,8 @@ GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
  * @return NULL on error, otherwise a KSK URI
  */
 struct GNUNET_FS_Uri *
  * @return NULL on error, otherwise a KSK URI
  */
 struct GNUNET_FS_Uri *

-GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData *md);
+GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
+                                         *md);

 
 
 /* ******************** command-line option parsing API *********************** */
 
 
 /* ******************** command-line option parsing API *********************** */


@@ -415,10 +462,9 @@ GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
  * @return GNUNET_OK on success
  */
 int
  * @return GNUNET_OK on success
  */
 int

-GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext* ctx, 
-                                        void *scls,
-                                        const char *option,
-                                        const char *value);
+GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
+                               *ctx, void *scls, const char *option,
+                               const char *value);

 
 
 /**
 
 
 /**


@@ -434,10 +480,9 @@ GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext*
  * @return GNUNET_OK on success
  */
 int
  * @return GNUNET_OK on success
  */
 int

-GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext* ctx, 
-                                        void *scls,
-                                        const char *option,
-                                        const char *value);
+GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext
+                               *ctx, void *scls, const char *option,
+                               const char *value);

 
 
 
 
 
 


@@ -536,6 +581,26 @@ enum GNUNET_FS_Status
    */
   GNUNET_FS_STATUS_DOWNLOAD_STOPPED,
 
    */
   GNUNET_FS_STATUS_DOWNLOAD_STOPPED,
 

+  /**
+   * Notification that this download is now actively being
+   * pursued (as opposed to waiting in the queue).
+   */
+  GNUNET_FS_STATUS_DOWNLOAD_ACTIVE,
+
+  /**
+   * Notification that this download is no longer actively
+   * being pursued (back in the queue).
+   */
+  GNUNET_FS_STATUS_DOWNLOAD_INACTIVE,
+
+  /**
+   * Notification that this download is no longer part of a
+   * recursive download or search but now a 'stand-alone'
+   * download (and may thus need to be moved in the GUI
+   * into a different category).
+   */
+  GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT,
+

   /**
    * First event generated when a client requests 
    * a search to begin or when a namespace result
   /**
    * First event generated when a client requests 
    * a search to begin or when a namespace result


@@ -562,12 +627,6 @@ enum GNUNET_FS_Status
    * be generated in this case.
    */
   GNUNET_FS_STATUS_SEARCH_SUSPEND,
    * be generated in this case.
    */
   GNUNET_FS_STATUS_SEARCH_SUSPEND,

-  
-  /**
-   * Event generated for each search result
-   * when the respective search is suspended.
-   */
-  GNUNET_FS_STATUS_SEARCH_SUSPEND_RESULT,

 
   /**
    * This search has yielded a result.
 
   /**
    * This search has yielded a result.


@@ -606,6 +665,12 @@ enum GNUNET_FS_Status
    */
   GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED,
 
    */
   GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED,
 

+  /**
+   * Event generated for each search result
+   * when the respective search is suspended.
+   */
+  GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND,
+

   /**
    * Last message from a search; this signals
    * that there will be no further events associated
   /**
    * Last message from a search; this signals
    * that there will be no further events associated


@@ -615,7 +680,7 @@ enum GNUNET_FS_Status
 
   /**
    * Notification that we started to unindex a file.
 
   /**
    * Notification that we started to unindex a file.

-   */ 
+   */

   GNUNET_FS_STATUS_UNINDEX_START,
 
   /**
   GNUNET_FS_STATUS_UNINDEX_START,
 
   /**


@@ -650,16 +715,9 @@ enum GNUNET_FS_Status
    * was stopped (final event for this action).
    */
   GNUNET_FS_STATUS_UNINDEX_STOPPED
    * was stopped (final event for this action).
    */
   GNUNET_FS_STATUS_UNINDEX_STOPPED

-

 };
 
 
 };
 
 

-/**
- * Handle to one of our namespaces.
- */
-struct GNUNET_FS_Namespace;
-
-

 /**
  * Handle for controlling an upload.
  */
 /**
  * Handle for controlling an upload.
  */


@@ -678,6 +736,14 @@ struct GNUNET_FS_UnindexContext;
 struct GNUNET_FS_SearchContext;
 
 
 struct GNUNET_FS_SearchContext;
 
 

+/**
+ * Result from a search.  Opaque handle to refer to the search
+ * (typically used when starting a download associated with the search
+ * result).
+ */
+struct GNUNET_FS_SearchResult;
+
+

 /**
  * Context for controlling a download.
  */
 /**
  * Context for controlling a download.
  */


@@ -697,22 +763,24 @@ struct GNUNET_FS_FileInformation;
  * information about what is going on.
  */
 struct GNUNET_FS_ProgressInfo
  * information about what is going on.
  */
 struct GNUNET_FS_ProgressInfo

-{  
+{

 
   /**
    * Values that depend on the event type.
    */
 
   /**
    * Values that depend on the event type.
    */

-  union {
-    
+  union
+  {
+

     /**
      * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events.
      */
     /**
      * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events.
      */

-    struct {
+    struct
+    {

 
       /**
        * Context for controlling the upload.
        */
 
       /**
        * Context for controlling the upload.
        */

-      struct GNUNET_FS_PublishContext *sc;
+      struct GNUNET_FS_PublishContext *pc;

 
       /**
        * Information about the file that is being publishd.
 
       /**
        * Information about the file that is being publishd.


@@ -720,9 +788,8 @@ struct GNUNET_FS_ProgressInfo
       const struct GNUNET_FS_FileInformation *fi;
 
       /**
       const struct GNUNET_FS_FileInformation *fi;
 
       /**

-       * Client context pointer (set the last time
-       * by the client for this operation; initially
-       * NULL on START/RESUME events).
+       * Client context pointer (set the last time by the client for
+       * this operation; initially NULL on START/RESUME events).

        */
       void *cctx;
 
        */
       void *cctx;
 


@@ -736,7 +803,7 @@ struct GNUNET_FS_ProgressInfo
        * Name of the file being published; can be NULL.
        */
       const char *filename;
        * Name of the file being published; can be NULL.
        */
       const char *filename;

-      
+

       /**
        * How large is the file overall?  For directories,
        * this is only the size of the directory itself,
       /**
        * How large is the file overall?  For directories,
        * this is only the size of the directory itself,


@@ -749,7 +816,7 @@ struct GNUNET_FS_ProgressInfo
        * At what time do we expect to finish the upload?
        * (will be a value in the past for completed
        * uploads).
        * At what time do we expect to finish the upload?
        * (will be a value in the past for completed
        * uploads).

-       */ 
+       */

       struct GNUNET_TIME_Relative eta;
 
       /**
       struct GNUNET_TIME_Relative eta;
 
       /**


@@ -771,92 +838,96 @@ struct GNUNET_FS_ProgressInfo
       /**
        * Additional values for specific events.
        */
       /**
        * Additional values for specific events.
        */

-      union {
+      union
+      {

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Data block we just published.
           */
           * Data block we just published.
           */

-         const void *data;
-         
-         /**
+          const void *data;
+
+          /**

           * At what offset in the file is "data"?
           */
           * At what offset in the file is "data"?
           */

-         uint64_t offset;
-         
-         /**
+          uint64_t offset;
+
+          /**

           * Length of the data block.
           */
           * Length of the data block.
           */

-         uint64_t data_len;
+          uint64_t data_len;

 
 

-         /**
+          /**

           * Depth of the given block in the tree; 
           * Depth of the given block in the tree; 

-          * 0 would be the highest level (the first
-          * call is guaranteed to be for the lowest
-          * level).
+          * 0 would be the lowest level (DBLOCKs).

           */
           */

-         unsigned int depth;
+          unsigned int depth;

 
 

-       } progress;
+        } progress;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_RESUME events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_RESUME events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Error message, NULL if no error was encountered so far.
           */
           * Error message, NULL if no error was encountered so far.
           */

-         const char *message;
-         
-         /**
+          const char *message;
+
+          /**

           * URI of the file (if the download had been completed)
           */
           * URI of the file (if the download had been completed)
           */

-         const struct GNUNET_FS_Uri *chk_uri;
+          const struct GNUNET_FS_Uri *chk_uri;

 
 

-       } resume;
+        } resume;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * URI of the file.
           */
           * URI of the file.
           */

-         const struct GNUNET_FS_Uri *chk_uri;
+          const struct GNUNET_FS_Uri *chk_uri;

 
 

-       } completed;
+        } completed;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_ERROR events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_PUBLISH_ERROR events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Error message, never NULL.
           */
           * Error message, never NULL.
           */

-         const char *message;
+          const char *message;

 
 

-       } error;
+        } error;

 
       } specifics;
 
     } publish;
 
 
       } specifics;
 
     } publish;
 

-    
+

     /**
      * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
      */
     /**
      * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events.
      */

-    struct {
+    struct
+    {

 
       /**
        * Context for controlling the download.
 
       /**
        * Context for controlling the download.


@@ -875,7 +946,15 @@ struct GNUNET_FS_ProgressInfo
        * (if this is a file in a directory or a subdirectory).
        */
       void *pctx;
        * (if this is a file in a directory or a subdirectory).
        */
       void *pctx;

-      
+
+      /**
+       * Client context pointer for the associated search operation
+       * (specifically, context pointer for the specific search
+       * result, not the overall search); only set if this 
+       * download was started from a search result.
+       */
+      void *sctx;
+

       /**
        * URI used for this download.
        */
       /**
        * URI used for this download.
        */


@@ -885,24 +964,24 @@ struct GNUNET_FS_ProgressInfo
        * Name of the file that we are downloading.
        */
       const char *filename;
        * Name of the file that we are downloading.
        */
       const char *filename;

-      
+

       /**
        * How large is the download overall?  This
        * is NOT necessarily the size from the
        * URI since we may be doing a partial download.
        */
       /**
        * How large is the download overall?  This
        * is NOT necessarily the size from the
        * URI since we may be doing a partial download.
        */

-      uint64_t length;
+      uint64_t size;

 
       /**
        * At what time do we expect to finish the download?
        * (will be a value in the past for completed
        * uploads).
 
       /**
        * At what time do we expect to finish the download?
        * (will be a value in the past for completed
        * uploads).

-       */ 
+       */

       struct GNUNET_TIME_Relative eta;
 
       /**
        * How long has this download been active?
       struct GNUNET_TIME_Relative eta;
 
       /**
        * How long has this download been active?

-       */ 
+       */

       struct GNUNET_TIME_Relative duration;
 
       /**
       struct GNUNET_TIME_Relative duration;
 
       /**


@@ -915,85 +994,96 @@ struct GNUNET_FS_ProgressInfo
        */
       uint32_t anonymity;
 
        */
       uint32_t anonymity;
 

+      /**
+       * Is the download currently active.
+       */
+      int is_active;
+

       /**
        * Additional values for specific events.
        */
       /**
        * Additional values for specific events.
        */

-      union {
-       
-       /**
+      union
+      {
+
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
         */

-       struct {
-  
-         /**
-          * Data block we just obtained.
+        struct
+        {
+
+          /**
+          * Data block we just obtained, can be NULL (even if
+          * data_len > 0) if we found the entire block 'intact' on
+          * disk.  In this case, it is also possible for 'data_len'
+          * to be larger than an individual (32k) block.

           */
           */

-         const void *data;
-         
-         /**
+          const void *data;
+
+          /**

           * At what offset in the file is "data"?
           */
           * At what offset in the file is "data"?
           */

-         uint64_t offset;
-         
-         /**
+          uint64_t offset;
+
+          /**

           * Length of the data block.
           */
           * Length of the data block.
           */

-         uint64_t data_len;
+          uint64_t data_len;

 
 

-         /**
+          /**

           * Depth of the given block in the tree; 
           * Depth of the given block in the tree; 

-          * 0 would be the highest level (the first
-          * call is guaranteed to be for the lowest
-          * level).
+          * 0 would be the lowest level (DBLOCKS).

           */
           */

-         unsigned int depth;
+          unsigned int depth;

 
 

-       } progress;
+        } progress;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_START events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_START events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Known metadata for the download.
           */
           * Known metadata for the download.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
-         
-       } start;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-       /**
+        } start;
+
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Known metadata for the download.
           */
           * Known metadata for the download.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * Error message, NULL if we have not encountered any error yet.
           */
           * Error message, NULL if we have not encountered any error yet.
           */

-         const char *message;
+          const char *message;

 
 

-       } resume;
+        } resume;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Error message.
           */
           * Error message.
           */

-         const char *message;
+          const char *message;

 
 

-       } error;
+        } error;

 
       } specifics;
 
 
       } specifics;
 


@@ -1002,7 +1092,8 @@ struct GNUNET_FS_ProgressInfo
     /**
      * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
      */
     /**
      * Values for all "GNUNET_FS_STATUS_SEARCH_*" events.
      */

-    struct {
+    struct
+    {

 
       /**
        * Context for controlling the search, NULL for
 
       /**
        * Context for controlling the search, NULL for


@@ -1023,8 +1114,10 @@ struct GNUNET_FS_ProgressInfo
 
       /**
        * Client parent-context pointer; NULL for top-level searches,
 
       /**
        * Client parent-context pointer; NULL for top-level searches,

-       * non-NULL for automatically triggered searches for updates in
-       * namespaces.
+       * refers to the client context of the associated search result
+       * for automatically triggered searches for updates in
+       * namespaces.  In this case, 'presult' refers to that search
+       * result.

        */
       void *pctx;
 
        */
       void *pctx;
 


@@ -1049,107 +1142,127 @@ struct GNUNET_FS_ProgressInfo
       /**
        * Additional values for specific events.
        */
       /**
        * Additional values for specific events.
        */

-      union {
-       
-       /**
+      union
+      {
+
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Metadata for the search result.
           */
           * Metadata for the search result.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * URI for the search result.
           */
           * URI for the search result.
           */

-         const struct GNUNET_FS_Uri *uri;
+          const struct GNUNET_FS_Uri *uri;
+
+          /**
+          * Handle to the result (for starting downloads).
+          */
+          struct GNUNET_FS_SearchResult *result;

 
 

-       } result;
-       
-       /**
+          /**
+          * Applicability rank (the larger, the better the result
+          * fits the search criteria).
+          */
+          uint32_t applicability_rank;
+
+        } result;
+
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Metadata for the search result.
           */
           * Metadata for the search result.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * URI for the search result.
           */
           * URI for the search result.
           */

-         const struct GNUNET_FS_Uri *uri;
+          const struct GNUNET_FS_Uri *uri;

 
 

-         /**
+          /**
+          * Handle to the result (for starting downloads).
+          */
+          struct GNUNET_FS_SearchResult *result;
+
+          /**

           * Current availability rank (negative:
           * unavailable, positive: available)
           */
           * Current availability rank (negative:
           * unavailable, positive: available)
           */

-         int32_t availability_rank;
- 
-         /**
+          int32_t availability_rank;
+
+          /**

           * On how many total queries is the given
           * availability_rank based?
           */
           * On how many total queries is the given
           * availability_rank based?
           */

-         uint32_t availabiliy_certainty;
+          uint32_t availability_certainty;

 
 

-         /**
+          /**

           * Updated applicability rank (the larger,
           * the better the result fits the search
           * criteria).
           */
           * Updated applicability rank (the larger,
           * the better the result fits the search
           * criteria).
           */

-         uint32_t applicabiliy_rank;     
-         
-       } resume_result;
-       
-       /**
+          uint32_t applicability_rank;
+
+        } resume_result;
+
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_UPDATE events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_UPDATE events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Private context set for for this result
           * during the "RESULT" event.
           */
           * Private context set for for this result
           * during the "RESULT" event.
           */

-         void *cctx;
-         
-         /**
+          void *cctx;
+
+          /**

           * Metadata for the search result.
           */
           * Metadata for the search result.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * URI for the search result.
           */
           * URI for the search result.
           */

-         const struct GNUNET_FS_Uri *uri;
+          const struct GNUNET_FS_Uri *uri;

 
 

-         /**
+          /**

           * Current availability rank (negative:
           * unavailable, positive: available)
           */
           * Current availability rank (negative:
           * unavailable, positive: available)
           */

-         int32_t availability_rank;
- 
-         /**
+          int32_t availability_rank;
+
+          /**

           * On how many total queries is the given
           * availability_rank based?
           */
           * On how many total queries is the given
           * availability_rank based?
           */

-         uint32_t availability_certainty;
+          uint32_t availability_certainty;

 
 

-         /**
+          /**

           * Updated applicability rank (the larger,
           * the better the result fits the search
           * criteria).
           */
           * Updated applicability rank (the larger,
           * the better the result fits the search
           * criteria).
           */

-         uint32_t applicability_rank;
+          uint32_t applicability_rank;
+
+        } update;

 
 

-       } update;
-       
-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
         * These events are automatically triggered for
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
         * These events are automatically triggered for


@@ -1158,27 +1271,28 @@ struct GNUNET_FS_ProgressInfo
         * happens primarily to give the client a chance
         * to clean up the "cctx" (if needed).
         */
         * happens primarily to give the client a chance
         * to clean up the "cctx" (if needed).
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Private context set for for this result
           * during the "RESULT" event.
           */
           * Private context set for for this result
           * during the "RESULT" event.
           */

-         void *cctx;
-         
-         /**
+          void *cctx;
+
+          /**

           * Metadata for the search result.
           */
           * Metadata for the search result.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * URI for the search result.
           */
           * URI for the search result.
           */

-         const struct GNUNET_FS_Uri *uri;
+          const struct GNUNET_FS_Uri *uri;
+
+        } result_suspend;

 
 

-       } result_suspend;
-       
-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
         * These events are automatically triggered for
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
         * These events are automatically triggered for


@@ -1187,89 +1301,93 @@ struct GNUNET_FS_ProgressInfo
         * happens primarily to give the client a chance
         * to clean up the "cctx" (if needed).
         */
         * happens primarily to give the client a chance
         * to clean up the "cctx" (if needed).
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Private context set for for this result
           * during the "RESULT" event.
           */
           * Private context set for for this result
           * during the "RESULT" event.
           */

-         void *cctx;
-         
-         /**
+          void *cctx;
+
+          /**

           * Metadata for the search result.
           */
           * Metadata for the search result.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
+          const struct GNUNET_CONTAINER_MetaData *meta;

 
 

-         /**
+          /**

           * URI for the search result.
           */
           * URI for the search result.
           */

-         const struct GNUNET_FS_Uri *uri;
+          const struct GNUNET_FS_Uri *uri;

 
 

-       } result_stopped;
+        } result_stopped;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESUME events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_RESUME events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Error message, NULL if we have not encountered any error yet.
           */
           * Error message, NULL if we have not encountered any error yet.
           */

-         const char *message;
+          const char *message;

 
 

-         /**
+          /**

           * Is this search currently paused?
           */
           * Is this search currently paused?
           */

-         int is_paused;
+          int is_paused;

 
 

-       } resume;
+        } resume;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_ERROR events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_SEARCH_ERROR events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Error message.
           */
           * Error message.
           */

-         const char *message;
+          const char *message;
+
+        } error;

 
 

-       } error;
-    
-       /**
+        /**

         * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events.
         */
         * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events.
         */

-       struct {
-         
-         /**
+        struct
+        {
+
+          /**

           * Handle to the namespace (NULL if it is not a local
           * namespace).
           */
           * Handle to the namespace (NULL if it is not a local
           * namespace).
           */

-         struct GNUNET_FS_Namespace *ns;
-         
-         /**
+          struct GNUNET_FS_Namespace *ns;
+
+          /**

           * Short, human-readable name of the namespace.
           */
           * Short, human-readable name of the namespace.
           */

-         const char *name;
-         
-         /**
+          const char *name;
+
+          /**

           * Root identifier for the namespace, can be NULL.
           */
           * Root identifier for the namespace, can be NULL.
           */

-         const char *root;
-         
-         /**
+          const char *root;
+
+          /**

           * Metadata for the namespace.
           */
           * Metadata for the namespace.
           */

-         const struct GNUNET_CONTAINER_MetaData *meta;
-         
-         /**
+          const struct GNUNET_CONTAINER_MetaData *meta;
+
+          /**

           * Hash-identifier for the namespace.
           */
           * Hash-identifier for the namespace.
           */

-         GNUNET_HashCode id;      
-         
-       } namespace;
+          GNUNET_HashCode id;
+
+        } namespace;

 
       } specifics;
 
 
       } specifics;
 


@@ -1278,7 +1396,8 @@ struct GNUNET_FS_ProgressInfo
     /**
      * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
      */
     /**
      * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events.
      */

-    struct {
+    struct
+    {

 
       /**
        * Context for controlling the unindexing.
 
       /**
        * Context for controlling the unindexing.


@@ -1306,7 +1425,7 @@ struct GNUNET_FS_ProgressInfo
        * At what time do we expect to finish unindexing?
        * (will be a value in the past for completed
        * unindexing opeations).
        * At what time do we expect to finish unindexing?
        * (will be a value in the past for completed
        * unindexing opeations).

-       */ 
+       */

       struct GNUNET_TIME_Relative eta;
 
       /**
       struct GNUNET_TIME_Relative eta;
 
       /**


@@ -1323,64 +1442,66 @@ struct GNUNET_FS_ProgressInfo
       /**
        * Additional values for specific events.
        */
       /**
        * Additional values for specific events.
        */

-      union {
+      union
+      {

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
         */

-       struct {
-  
-         /**
+        struct
+        {
+
+          /**

           * Data block we just unindexed.
           */
           * Data block we just unindexed.
           */

-         const void *data;
-         
-         /**
+          const void *data;
+
+          /**

           * At what offset in the file is "data"?
           */
           * At what offset in the file is "data"?
           */

-         uint64_t offset;
-         
-         /**
+          uint64_t offset;
+
+          /**

           * Length of the data block.
           */
           * Length of the data block.
           */

-         uint64_t data_len;
+          uint64_t data_len;

 
 

-         /**
+          /**

           * Depth of the given block in the tree; 
           * Depth of the given block in the tree; 

-          * 0 would be the highest level (the first
-          * call is guaranteed to be for the lowest
-          * level).
+          * 0 would be the lowest level (DBLOCKS).

           */
           */

-         unsigned int depth;
+          unsigned int depth;

 
 

-       } progress;
+        } progress;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_RESUME events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_RESUME events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Error message, NULL if we have not encountered any error yet.
           */
           * Error message, NULL if we have not encountered any error yet.
           */

-         const char *message;
+          const char *message;

 
 

-       } resume;
+        } resume;

 
 

-       /**
+        /**

         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_ERROR events.
         */
         * These values are only valid for
         * GNUNET_FS_STATUS_UNINDEX_ERROR events.
         */

-       struct {
+        struct
+        {

 
 

-         /**
+          /**

           * Error message.
           */
           * Error message.
           */

-         const char *message;
+          const char *message;

 
 

-       } error;
+        } error;

 
       } specifics;
 
 
       } specifics;
 


@@ -1390,7 +1511,7 @@ struct GNUNET_FS_ProgressInfo
 
   /**
    * Specific status code (determines the event type).
 
   /**
    * Specific status code (determines the event type).

-   */  
+   */

   enum GNUNET_FS_Status status;
 
 };
   enum GNUNET_FS_Status status;
 
 };


@@ -1411,49 +1532,123 @@ struct GNUNET_FS_ProgressInfo
  *         will be passed to future callbacks in the respective
  *         field in the GNUNET_FS_ProgressInfo struct.
  */
  *         will be passed to future callbacks in the respective
  *         field in the GNUNET_FS_ProgressInfo struct.
  */

-typedef void* (*GNUNET_FS_ProgressCallback)
-  (void *cls,
-   const struct GNUNET_FS_ProgressInfo *info);
+typedef void *(*GNUNET_FS_ProgressCallback) (void *cls,
+                                             const struct GNUNET_FS_ProgressInfo
+                                             * info);

 
 
 /**
  * General (global) option flags for file-sharing.
  */
 enum GNUNET_FS_Flags
 
 
 /**
  * General (global) option flags for file-sharing.
  */
 enum GNUNET_FS_Flags

-  {
+{

     /**
      * No special flags set.
      */
     /**
      * No special flags set.
      */

-    GNUNET_FS_FLAGS_NONE = 0,
+  GNUNET_FS_FLAGS_NONE = 0,

 
     /**
      * Is persistence of operations desired?
      * (will create SUSPEND/RESUME events).
      */
 
     /**
      * Is persistence of operations desired?
      * (will create SUSPEND/RESUME events).
      */

-    GNUNET_FS_FLAGS_PERSISTENCE = 1
+  GNUNET_FS_FLAGS_PERSISTENCE = 1,

 
 

-  };
+    /**
+     * Should we automatically trigger probes for search results
+     * to determine availability?
+     * (will create GNUNET_FS_STATUS_SEARCH_UPDATE events).
+     */
+  GNUNET_FS_FLAGS_DO_PROBES = 2
+};

 
 /**
 
 /**

- * Options specified in the VARARGs
- * portion of GNUNET_FS_start.
+ * Options specified in the VARARGs portion of GNUNET_FS_start.

  */
 enum GNUNET_FS_OPTIONS
  */
 enum GNUNET_FS_OPTIONS

-  {
-    
+{
+

     /**
      * Last option in the VARARG list.
      */
     /**
      * Last option in the VARARG list.
      */

-    GNUNET_FS_OPTIONS_END = 0,
+  GNUNET_FS_OPTIONS_END = 0,

 
     /**
      * Select the desired amount of parallelism (this option should be
      * followed by an "unsigned int" giving the desired maximum number
      * of parallel downloads).
      */
 
     /**
      * Select the desired amount of parallelism (this option should be
      * followed by an "unsigned int" giving the desired maximum number
      * of parallel downloads).
      */

-    GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1
+  GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1,
+
+    /**
+     * Maximum number of requests that should be pending at a given
+     * point in time (invidivual downloads may go above this, but
+     * if we are above this threshold, we should not activate any
+     * additional downloads.
+     */
+  GNUNET_FS_OPTIONS_REQUEST_PARALLELISM = 2
+};
+
+
+/**
+ * Settings for publishing a block (which may of course also
+ * apply to an entire directory or file).
+ */
+struct GNUNET_FS_BlockOptions
+{
+
+  /**
+   * At what time should the block expire?  Data blocks (DBLOCKS and
+   * IBLOCKS) may still be used even if they are expired (however,
+   * they'd be removed quickly from the datastore if we are short on
+   * space), all other types of blocks will no longer be returned
+   * after they expire.
+   */
+  struct GNUNET_TIME_Absolute expiration_time;

 
 

-  };
+  /**
+   * At which anonymity level should the block be shared?
+   * (0: no anonymity, 1: normal GAP, >1: with cover traffic).
+   */
+  uint32_t anonymity_level;
+
+  /**
+   * How important is it for us to store the block?  If we run
+   * out of space, the highest-priority, non-expired blocks will
+   * be kept.
+   */
+  uint32_t content_priority;
+
+  /**
+   * How often should we try to migrate the block to other peers?
+   * Only used if "CONTENT_PUSHING" is set to YES, in which case we
+   * first push each block to other peers according to their
+   * replication levels.  Once each block has been pushed that many
+   * times to other peers, blocks are chosen for migration at random.
+   * Naturally, there is no guarantee that the other peers will keep
+   * these blocks for any period of time (since they won't have any
+   * priority or might be too busy to even store the block in the
+   * first place).
+   */
+  uint32_t replication_level;
+
+};
+
+
+/**
+ * Return the current year (i.e. '2011').
+ */
+unsigned int
+GNUNET_FS_get_current_year (void);
+
+
+/**
+ * Convert a year to an expiration time of January 1st of that year.
+ *
+ * @param year a year (after 1970, please ;-)).
+ * @return absolute time for January 1st of that year.
+ */
+struct GNUNET_TIME_Absolute
+GNUNET_FS_year_to_time (unsigned int year);

 
 
 /**
 
 
 /**


@@ -1465,7 +1660,6 @@ struct GNUNET_FS_Handle;
 /**
  * Setup a connection to the file-sharing service.
  *
 /**
  * Setup a connection to the file-sharing service.
  *

- * @param sched scheduler to use

  * @param cfg configuration to use
  * @param client_name unique identifier for this client 
  * @param upcb function to call to notify about FS actions
  * @param cfg configuration to use
  * @param client_name unique identifier for this client 
  * @param upcb function to call to notify about FS actions


@@ -1475,13 +1669,9 @@ struct GNUNET_FS_Handle;
  * @return NULL on error
  */
 struct GNUNET_FS_Handle *
  * @return NULL on error
  */
 struct GNUNET_FS_Handle *

-GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched,
-                const struct GNUNET_CONFIGURATION_Handle *cfg,
-                const char *client_name,
-                GNUNET_FS_ProgressCallback upcb,
-                void *upcb_cls,
-                enum GNUNET_FS_Flags flags,
-                ...);
+GNUNET_FS_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                 const char *client_name, GNUNET_FS_ProgressCallback upcb,
+                 void *upcb_cls, enum GNUNET_FS_Flags flags, ...);

 
 
 /**
 
 
 /**


@@ -1490,9 +1680,24 @@ GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched,
  * called after this function returns.
  *
  * @param h handle that was returned from GNUNET_FS_start
  * called after this function returns.
  *
  * @param h handle that was returned from GNUNET_FS_start

- */                    
-void 
-GNUNET_FS_stop (struct GNUNET_FS_Handle *h); 
+ */
+void
+GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
+
+
+/**
+ * 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_FS_meta_data_extract_from_file (struct GNUNET_CONTAINER_MetaData *md,
+                                       const char *filename,
+                                       struct EXTRACTOR_PluginList *extractors);

 
 
 /**
 
 
 /**


@@ -1503,33 +1708,24 @@ GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
  * @param length length of the file or directory
  * @param meta metadata for the file or directory (can be modified)
  * @param uri pointer to the keywords that will be used for this entry (can be modified)
  * @param length length of the file or directory
  * @param meta metadata for the file or directory (can be modified)
  * @param uri pointer to the keywords that will be used for this entry (can be modified)

- * @param anonymity pointer to selected anonymity level (can be modified)
- * @param priority pointer to selected priority (can be modified)
- * @param expirationTime pointer to selected expiration time (can be modified)
+ * @param bo block options (can be modified)
+ * @param do_index should we index (can be modified)

  * @param client_info pointer to client context set upon creation (can be modified)
  * @return GNUNET_OK to continue, GNUNET_NO to remove
  *         this entry from the directory, GNUNET_SYSERR
  *         to abort the iteration
  */
  * @param client_info pointer to client context set upon creation (can be modified)
  * @return GNUNET_OK to continue, GNUNET_NO to remove
  *         this entry from the directory, GNUNET_SYSERR
  *         to abort the iteration
  */

-typedef int (*GNUNET_FS_FileInformationProcessor)(void *cls,
-                                                 struct GNUNET_FS_FileInformation *fi,
-                                                 uint64_t length,
-                                                 struct GNUNET_CONTAINER_MetaData *meta,
-                                                 struct GNUNET_FS_Uri **uri,
-                                                 uint32_t *anonymity,
-                                                 uint32_t *priority,
-                                                 struct GNUNET_TIME_Absolute *expirationTime,
-                                                 void **client_info);
-
-
-/**
- * Recover file information structure from disk.
- *
- * @param fn filename for the structure on disk
- * @return NULL on error 
- */
-struct GNUNET_FS_FileInformation *
-GNUNET_FS_file_information_recover (const char *fn);
+typedef int (*GNUNET_FS_FileInformationProcessor) (void *cls,
+                                                   struct
+                                                   GNUNET_FS_FileInformation *
+                                                   fi, uint64_t length,
+                                                   struct
+                                                   GNUNET_CONTAINER_MetaData *
+                                                   meta,
+                                                   struct GNUNET_FS_Uri ** uri,
+                                                   struct GNUNET_FS_BlockOptions
+                                                   * bo, int *do_index,
+                                                   void **client_info);

 
 
 /**
 
 
 /**


@@ -1546,73 +1742,61 @@ const char *
 GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
 
 
 GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
 
 

-/**
- * Synchronize this file-information struct with its mirror
- * on disk.  Note that all internal FS-operations that change
- * file information data should already call "sync" internally,
- * so this function is likely not useful for clients.
- * 
- * @param fi the struct to sync
- */
-void
-GNUNET_FS_file_information_sync (struct GNUNET_FS_FileInformation *f);
-

 
 /**
  * Create an entry for a file in a publish-structure.
  *
 
 /**
  * Create an entry for a file in a publish-structure.
  *

+ * @param h handle to the file sharing subsystem
+ * @param client_info initial client-info value for this entry

  * @param filename name of the file or directory to publish
  * @param keywords under which keywords should this file be available
  *         directly; can be NULL
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation
  * @param filename name of the file or directory to publish
  * @param keywords under which keywords should this file be available
  *         directly; can be NULL
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation

- * @param anonymity what is the desired anonymity level for sharing?
- * @param priority what is the priority for OUR node to
- *   keep this file available?  Use 0 for maximum anonymity and
- *   minimum reliability...
- * @param expirationTime when should this content expire?
+ * @param bo block options

  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *
  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *

-GNUNET_FS_file_information_create_from_file (void *client_info,
-                                            const char *filename,
-                                            const struct GNUNET_FS_Uri *keywords,
-                                            const struct GNUNET_CONTAINER_MetaData *meta,
-                                            int do_index,
-                                            uint32_t anonymity,
-                                            uint32_t priority,
-                                            struct GNUNET_TIME_Absolute expirationTime);
+GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
+                                             void *client_info,
+                                             const char *filename,
+                                             const struct GNUNET_FS_Uri
+                                             *keywords,
+                                             const struct
+                                             GNUNET_CONTAINER_MetaData *meta,
+                                             int do_index,
+                                             const struct GNUNET_FS_BlockOptions
+                                             *bo);

 
 
 /**
  * Create an entry for a file in a publish-structure.
  *
 
 
 /**
  * Create an entry for a file in a publish-structure.
  *

+ * @param h handle to the file sharing subsystem
+ * @param client_info initial client-info value for this entry

  * @param length length of the file
  * @param data data for the file (should not be used afterwards by
  * @param length length of the file
  * @param data data for the file (should not be used afterwards by

- *        the caller; caller will "free")
+ *        the caller; callee will "free")

  * @param keywords under which keywords should this file be available
  *         directly; can be NULL
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation
  * @param keywords under which keywords should this file be available
  *         directly; can be NULL
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation

- * @param anonymity what is the desired anonymity level for sharing?
- * @param priority what is the priority for OUR node to
- *   keep this file available?  Use 0 for maximum anonymity and
- *   minimum reliability...
- * @param expirationTime when should this content expire?
+ * @param bo block options

  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *
  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *

-GNUNET_FS_file_information_create_from_data (void *client_info,
-                                            uint64_t length,
-                                            void *data,
-                                            const struct GNUNET_FS_Uri *keywords,
-                                            const struct GNUNET_CONTAINER_MetaData *meta,
-                                            int do_index,
-                                            uint32_t anonymity,
-                                            uint32_t priority,
-                                            struct GNUNET_TIME_Absolute expirationTime);
+GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
+                                             void *client_info, uint64_t length,
+                                             void *data,
+                                             const struct GNUNET_FS_Uri
+                                             *keywords,
+                                             const struct
+                                             GNUNET_CONTAINER_MetaData *meta,
+                                             int do_index,
+                                             const struct GNUNET_FS_BlockOptions
+                                             *bo);

 
 
 /**
 
 
 /**


@@ -1631,16 +1815,15 @@ GNUNET_FS_file_information_create_from_data (void *client_info,
  * @param emsg location for the reader to store an error message
  * @return number of bytes written, usually "max", 0 on error
  */
  * @param emsg location for the reader to store an error message
  * @return number of bytes written, usually "max", 0 on error
  */

-typedef size_t (*GNUNET_FS_DataReader)(void *cls, 
-                                      uint64_t offset,
-                                      size_t max, 
-                                      void *buf,
-                                      char **emsg);
+typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max,
+                                        void *buf, char **emsg);

 
 
 /**
  * Create an entry for a file in a publish-structure.
  *
 
 
 /**
  * Create an entry for a file in a publish-structure.
  *

+ * @param h handle to the file sharing subsystem
+ * @param client_info initial client-info value for this entry

  * @param length length of the file
  * @param reader function that can be used to obtain the data for the file 
  * @param reader_cls closure for "reader"
  * @param length length of the file
  * @param reader function that can be used to obtain the data for the file 
  * @param reader_cls closure for "reader"


@@ -1649,24 +1832,22 @@ typedef size_t (*GNUNET_FS_DataReader)(void *cls,
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation
  * @param meta metadata for the file
  * @param do_index GNUNET_YES for index, GNUNET_NO for insertion,
  *                GNUNET_SYSERR for simulation

- * @param anonymity what is the desired anonymity level for sharing?
- * @param priority what is the priority for OUR node to
- *   keep this file available?  Use 0 for maximum anonymity and
- *   minimum reliability...
- * @param expirationTime when should this content expire?
+ * @param bo block options

  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *
  * @return publish structure entry for the file
  */
 struct GNUNET_FS_FileInformation *

-GNUNET_FS_file_information_create_from_reader (void *client_info,
-                                              uint64_t length,
-                                              GNUNET_FS_DataReader reader,
-                                              void *reader_cls,
-                                              const struct GNUNET_FS_Uri *keywords,
-                                              const struct GNUNET_CONTAINER_MetaData *meta,
-                                              int do_index,
-                                              uint32_t anonymity,
-                                              uint32_t priority,
-                                              struct GNUNET_TIME_Absolute expirationTime);
+GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
+                                               void *client_info,
+                                               uint64_t length,
+                                               GNUNET_FS_DataReader reader,
+                                               void *reader_cls,
+                                               const struct GNUNET_FS_Uri
+                                               *keywords,
+                                               const struct
+                                               GNUNET_CONTAINER_MetaData *meta,
+                                               int do_index,
+                                               const struct
+                                               GNUNET_FS_BlockOptions *bo);

 
 
 /**
 
 
 /**


@@ -1679,34 +1860,29 @@ GNUNET_FS_file_information_create_from_reader (void *client_info,
  * @param fi information about the file (should not be
  *        used henceforth by the caller)
  */
  * @param fi information about the file (should not be
  *        used henceforth by the caller)
  */

-typedef void (*GNUNET_FS_FileProcessor)(void *cls,
-                                       const char *filename,
-                                       struct GNUNET_FS_FileInformation *fi);
+typedef void (*GNUNET_FS_FileProcessor) (void *cls, const char *filename,
+                                         struct GNUNET_FS_FileInformation * fi);

 
 
 /**
  * Type of a function that will be used to scan a directory.
  * 
  * @param cls closure
 
 
 /**
  * Type of a function that will be used to scan a directory.
  * 
  * @param cls closure

+ * @param h handle to the file sharing subsystem

  * @param dirname name of the directory to scan
  * @param do_index should files be indexed or inserted
  * @param dirname name of the directory to scan
  * @param do_index should files be indexed or inserted

- * @param anonymity desired anonymity level
- * @param priority priority for publishing
- * @param expirationTime expiration for publication
+ * @param bo block options

  * @param proc function to call on each entry
  * @param proc_cls closure for proc
  * @param emsg where to store an error message (on errors)
  * @return GNUNET_OK on success
  */
  * @param proc function to call on each entry
  * @param proc_cls closure for proc
  * @param emsg where to store an error message (on errors)
  * @return GNUNET_OK on success
  */

-typedef int (*GNUNET_FS_DirectoryScanner)(void *cls,
-                                         const char *dirname,
-                                         int do_index,
-                                         uint32_t anonymity,
-                                         uint32_t priority,
-                                         struct GNUNET_TIME_Absolute expirationTime,
-                                         GNUNET_FS_FileProcessor proc,
-                                         void *proc_cls,
-                                         char **emsg);
+typedef int (*GNUNET_FS_DirectoryScanner) (void *cls,
+                                           struct GNUNET_FS_Handle * h,
+                                           const char *dirname, int do_index,
+                                           const struct GNUNET_FS_BlockOptions *
+                                           bo, GNUNET_FS_FileProcessor proc,
+                                           void *proc_cls, char **emsg);

 
 
 
 
 
 


@@ -1722,26 +1898,21 @@ typedef int (*GNUNET_FS_DirectoryScanner)(void *cls,
  * convenience function.
  *
  * @param cls must be of type "struct EXTRACTOR_Extractor*"
  * convenience function.
  *
  * @param cls must be of type "struct EXTRACTOR_Extractor*"

+ * @param h handle to the file sharing subsystem

  * @param dirname name of the directory to scan
  * @param do_index should files be indexed or inserted
  * @param dirname name of the directory to scan
  * @param do_index should files be indexed or inserted

- * @param anonymity desired anonymity level
- * @param priority priority for publishing
- * @param expirationTime expiration for publication
+ * @param bo block options

  * @param proc function called on each entry
  * @param proc_cls closure for proc
  * @param emsg where to store an error message (on errors)
  * @return GNUNET_OK on success
  */
 int
  * @param proc function called on each entry
  * @param proc_cls closure for proc
  * @param emsg where to store an error message (on errors)
  * @return GNUNET_OK on success
  */
 int

-GNUNET_FS_directory_scanner_default (void *cls,
-                                    const char *dirname,
-                                    int do_index,
-                                    uint32_t anonymity,
-                                    uint32_t priority,
-                                    struct GNUNET_TIME_Absolute expirationTime,
-                                    GNUNET_FS_FileProcessor proc,
-                                    void *proc_cls,
-                                    char **emsg);
+GNUNET_FS_directory_scanner_default (void *cls, struct GNUNET_FS_Handle *h,
+                                     const char *dirname, int do_index,
+                                     const struct GNUNET_FS_BlockOptions *bo,
+                                     GNUNET_FS_FileProcessor proc,
+                                     void *proc_cls, char **emsg);

 
 
 /**
 
 
 /**


@@ -1754,28 +1925,26 @@ GNUNET_FS_directory_scanner_default (void *cls,
  * passed (GNUNET_FS_directory_scanner_default).  This is strictly a
  * convenience function.
  *
  * passed (GNUNET_FS_directory_scanner_default).  This is strictly a
  * convenience function.
  *

+ * @param h handle to the file sharing subsystem
+ * @param client_info initial client-info value for this entry

  * @param filename name of the top-level file or directory
  * @param scanner function used to get a list of files in a directory
  * @param scanner_cls closure for scanner
  * @param do_index should files in the hierarchy be indexed?
  * @param filename name of the top-level file or directory
  * @param scanner function used to get a list of files in a directory
  * @param scanner_cls closure for scanner
  * @param do_index should files in the hierarchy be indexed?

- * @param anonymity what is the desired anonymity level for sharing?
- * @param priority what is the priority for OUR node to
- *   keep this file available?  Use 0 for maximum anonymity and
- *   minimum reliability...
- * @param expirationTime when should this content expire?
+ * @param bo block options

  * @param emsg where to store an error message
  * @return publish structure entry for the directory, NULL on error
  */
 struct GNUNET_FS_FileInformation *
  * @param emsg where to store an error message
  * @return publish structure entry for the directory, NULL on error
  */
 struct GNUNET_FS_FileInformation *

-GNUNET_FS_file_information_create_from_directory (void *client_info,
-                                                 const char *filename,
-                                                 GNUNET_FS_DirectoryScanner scanner,
-                                                 void *scanner_cls,
-                                                 int do_index,
-                                                 uint32_t anonymity,
-                                                 uint32_t priority,
-                                                 struct GNUNET_TIME_Absolute expirationTime,
-                                                 char **emsg);
+GNUNET_FS_file_information_create_from_directory (struct GNUNET_FS_Handle *h,
+                                                  void *client_info,
+                                                  const char *filename,
+                                                  GNUNET_FS_DirectoryScanner
+                                                  scanner, void *scanner_cls,
+                                                  int do_index,
+                                                  const struct
+                                                  GNUNET_FS_BlockOptions *bo,
+                                                  char **emsg);

 
 
 /**
 
 
 /**


@@ -1784,23 +1953,35 @@ GNUNET_FS_file_information_create_from_directory (void *client_info,
  * use of "GNUNET_FS_file_information_create_from_directory"
  * is not appropriate.
  *
  * use of "GNUNET_FS_file_information_create_from_directory"
  * is not appropriate.
  *

- * @param meta metadata for the directory
+ * @param h handle to the file sharing subsystem
+ * @param client_info initial client-info value for this entry

  * @param keywords under which keywords should this directory be available
  *         directly; can be NULL
  * @param keywords under which keywords should this directory be available
  *         directly; can be NULL

- * @param anonymity what is the desired anonymity level for sharing?
- * @param priority what is the priority for OUR node to
- *   keep this file available?  Use 0 for maximum anonymity and
- *   minimum reliability...
- * @param expirationTime when should this content expire?
+ * @param meta metadata for the directory
+ * @param bo block options

  * @return publish structure entry for the directory , NULL on error
  */
 struct GNUNET_FS_FileInformation *
  * @return publish structure entry for the directory , NULL on error
  */
 struct GNUNET_FS_FileInformation *

-GNUNET_FS_file_information_create_empty_directory (void *client_info,
-                                                  const struct GNUNET_CONTAINER_MetaData *meta,
-                                                  const struct GNUNET_FS_Uri *keywords,
-                                                  uint32_t anonymity,
-                                                  uint32_t priority,
-                                                  struct GNUNET_TIME_Absolute expirationTime);
+GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
+                                                   void *client_info,
+                                                   const struct GNUNET_FS_Uri
+                                                   *keywords,
+                                                   const struct
+                                                   GNUNET_CONTAINER_MetaData
+                                                   *meta,
+                                                   const struct
+                                                   GNUNET_FS_BlockOptions *bo);
+
+
+/**
+ * Test if a given entry represents a directory.
+ *
+ * @param ent check if this FI represents a directory
+ * @return GNUNET_YES if so, GNUNET_NO if not
+ */
+int
+GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation
+                                         *ent);

 
 
 /**
 
 
 /**


@@ -1816,7 +1997,7 @@ GNUNET_FS_file_information_create_empty_directory (void *client_info,
  */
 int
 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
  */
 int
 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,

-                               struct GNUNET_FS_FileInformation *ent);
+                                struct GNUNET_FS_FileInformation *ent);

 
 
 /**
 
 
 /**


@@ -1835,8 +2016,8 @@ GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
  */
 void
 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
  */
 void
 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,

-                                   GNUNET_FS_FileInformationProcessor proc,
-                                   void *proc_cls);
+                                    GNUNET_FS_FileInformationProcessor proc,
+                                    void *proc_cls);

 
 
 /**
 
 
 /**


@@ -1851,34 +2032,32 @@ GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
  */
 void
 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
  */
 void
 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,

-                                   GNUNET_FS_FileInformationProcessor cleaner,
-                                   void *cleaner_cls);
+                                    GNUNET_FS_FileInformationProcessor cleaner,
+                                    void *cleaner_cls);

 
 
 /**
  * Options for publishing.  Compatible options
  * can be OR'ed together.
  */
 
 
 /**
  * Options for publishing.  Compatible options
  * can be OR'ed together.
  */

-enum GNUNET_FS_PublishOptions 
-  {
+enum GNUNET_FS_PublishOptions
+{

     /**
      * No options (use defaults for everything).
      */
     /**
      * No options (use defaults for everything).
      */

-    GNUNET_FS_PUBLISH_OPTION_NONE = 0,
-    
+  GNUNET_FS_PUBLISH_OPTION_NONE = 0,
+

     /**
      * Simulate publishing.  With this option, no data will be stored
      * in the datastore.  Useful for computing URIs from files.
      */
     /**
      * Simulate publishing.  With this option, no data will be stored
      * in the datastore.  Useful for computing URIs from files.
      */

-    GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1
-  };
+  GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1
+};

 
 /**
  * Publish a file or directory.
  *
  * @param h handle to the file sharing subsystem
 
 /**
  * Publish a file or directory.
  *
  * @param h handle to the file sharing subsystem

- * @param ctx initial value to use for the '*ctx'
- *        in the callback (for the GNUNET_FS_STATUS_PUBLISH_START event).

  * @param fi information about the file or directory structure to publish
  * @param namespace namespace to publish the file in, NULL for no namespace
  * @param nid identifier to use for the publishd content in the namespace
  * @param fi information about the file or directory structure to publish
  * @param namespace namespace to publish the file in, NULL for no namespace
  * @param nid identifier to use for the publishd content in the namespace


@@ -1890,23 +2069,22 @@ enum GNUNET_FS_PublishOptions
  */
 struct GNUNET_FS_PublishContext *
 GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,
  */
 struct GNUNET_FS_PublishContext *
 GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,

-                        void *ctx,
-                        struct GNUNET_FS_FileInformation *fi,
-                        struct GNUNET_FS_Namespace *namespace,
-                        const char *nid,
-                        const char *nuid,
-                        enum GNUNET_FS_PublishOptions options);
+                         struct GNUNET_FS_FileInformation *fi,
+                         struct GNUNET_FS_Namespace *namespace, const char *nid,
+                         const char *nuid,
+                         enum GNUNET_FS_PublishOptions options);

 
 
 /**
 
 
 /**

- * Stop an upload.  Will abort incomplete uploads (but 
- * not remove blocks that have already been publishd) or
- * simply clean up the state for completed uploads.
+ * Stop a publication.  Will abort incomplete publications (but 
+ * not remove blocks that have already been published) or
+ * simply clean up the state for completed publications.
+ * Must NOT be called from within the event callback!

  *
  *

- * @param sc context for the upload to stop
+ * @param pc context for the publication to stop

  */
  */

-void 
-GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *sc);
+void
+GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc);

 
 
 /**
 
 
 /**


@@ -1917,10 +2095,10 @@ GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *sc);
  * @param uri URI under which the block is now available, NULL on error
  * @param emsg error message, NULL on success
  */
  * @param uri URI under which the block is now available, NULL on error
  * @param emsg error message, NULL on success
  */

-typedef void (*GNUNET_FS_PublishContinuation)(void *cls,
-                                             const struct GNUNET_FS_Uri *uri,
-                                             const char *emsg);
-                                     
+typedef void (*GNUNET_FS_PublishContinuation) (void *cls,
+                                               const struct GNUNET_FS_Uri * uri,
+                                               const char *emsg);
+

 
 /**
  * Publish a KBlock on GNUnet.
 
 /**
  * Publish a KBlock on GNUnet.


@@ -1929,23 +2107,19 @@ typedef void (*GNUNET_FS_PublishContinuation)(void *cls,
  * @param ksk_uri keywords to use
  * @param meta metadata to use
  * @param uri URI to refer to in the KBlock
  * @param ksk_uri keywords to use
  * @param meta metadata to use
  * @param uri URI to refer to in the KBlock

- * @param expirationTime when the KBlock expires
- * @param anonymity anonymity level for the KBlock
- * @param priority priority for the KBlock
+ * @param bo block options
+ * @param options publication options

  * @param cont continuation
  * @param cont_cls closure for cont
  */
 void
 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
  * @param cont continuation
  * @param cont_cls closure for cont
  */
 void
 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,

-                      struct GNUNET_FS_Uri *ksk_uri,
-                      struct GNUNET_CONTAINER_MetaData *meta,
-                      struct GNUNET_FS_Uri *uri,
-                      struct GNUNET_TIME_Absolute expirationTime,
-                      uint32_t anonymity,
-                      uint32_t priority,
-                      enum GNUNET_FS_PublishOptions options,
-                      GNUNET_FS_PublishContinuation cont,
-                      void *cont_cls);
+                       const struct GNUNET_FS_Uri *ksk_uri,
+                       const struct GNUNET_CONTAINER_MetaData *meta,
+                       const struct GNUNET_FS_Uri *uri,
+                       const struct GNUNET_FS_BlockOptions *bo,
+                       enum GNUNET_FS_PublishOptions options,
+                       GNUNET_FS_PublishContinuation cont, void *cont_cls);

 
 
 /**
 
 
 /**


@@ -1957,25 +2131,20 @@ GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
  * @param update update identifier to use
  * @param meta metadata to use
  * @param uri URI to refer to in the SBlock
  * @param update update identifier to use
  * @param meta metadata to use
  * @param uri URI to refer to in the SBlock

- * @param expirationTime when the SBlock expires
- * @param anonymity anonymity level for the SBlock
- * @param priority priority for the SBlock
+ * @param bo block options
+ * @param options publication options

  * @param cont continuation
  * @param cont_cls closure for cont
  */
 void
 GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
  * @param cont continuation
  * @param cont_cls closure for cont
  */
 void
 GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,

-                      struct GNUNET_FS_Namespace *namespace,
-                      const char *identifier,
-                      const char *update,
-                      struct GNUNET_CONTAINER_MetaData *meta,
-                      struct GNUNET_FS_Uri *uri,
-                      struct GNUNET_TIME_Absolute expirationTime,
-                      uint32_t anonymity,
-                      uint32_t priority,
-                      enum GNUNET_FS_PublishOptions options,
-                      GNUNET_FS_PublishContinuation cont,
-                      void *cont_cls);
+                       struct GNUNET_FS_Namespace *namespace,
+                       const char *identifier, const char *update,
+                       const struct GNUNET_CONTAINER_MetaData *meta,
+                       const struct GNUNET_FS_Uri *uri,
+                       const struct GNUNET_FS_BlockOptions *bo,
+                       enum GNUNET_FS_PublishOptions options,
+                       GNUNET_FS_PublishContinuation cont, void *cont_cls);

 
 
 /**
 
 
 /**


@@ -1986,9 +2155,8 @@ GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
  * @param file_id hash of the contents of the indexed file
  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
  */
  * @param file_id hash of the contents of the indexed file
  * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
  */

-typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls,
-                                              const char *filename,
-                                              const GNUNET_HashCode *file_id);
+typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename,
+                                               const GNUNET_HashCode * file_id);

 
 
 /**
 
 
 /**


@@ -2002,12 +2170,11 @@ typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls,
  *             error) or  "PREREQ_DONE" (on success)
  * @param cont_cls closure for cont
  */
  *             error) or  "PREREQ_DONE" (on success)
  * @param cont_cls closure for cont
  */

-void 
+void

 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,

-                            GNUNET_FS_IndexedFileProcessor iterator,
-                            void *iterator_cls,
-                            GNUNET_SCHEDULER_Task cont,
-                            void *cont_cls);
+                             GNUNET_FS_IndexedFileProcessor iterator,
+                             void *iterator_cls, GNUNET_SCHEDULER_Task cont,
+                             void *cont_cls);

 
 
 /**
 
 
 /**


@@ -2015,11 +2182,12 @@ GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
  *
  * @param h handle to the file sharing subsystem
  * @param filename file to unindex
  *
  * @param h handle to the file sharing subsystem
  * @param filename file to unindex

+ * @param cctx initial value for the client context

  * @return NULL on error, otherwise handle 
  */
 struct GNUNET_FS_UnindexContext *
  * @return NULL on error, otherwise handle 
  */
 struct GNUNET_FS_UnindexContext *

-GNUNET_FS_unindex (struct GNUNET_FS_Handle *h,
-                  const char *filename);
+GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, const char *filename,
+                         void *cctx);

 
 
 /**
 
 
 /**


@@ -2035,27 +2203,23 @@ GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
  * Publish an advertismement for a namespace.  
  *
  * @param h handle to the file sharing subsystem
  * Publish an advertismement for a namespace.  
  *
  * @param h handle to the file sharing subsystem

+ * @param ksk_uri keywords to use for advertisment

  * @param namespace handle for the namespace that should be advertised
  * @param meta meta-data for the namespace advertisement
  * @param namespace handle for the namespace that should be advertised
  * @param meta meta-data for the namespace advertisement

- * @param anonymity for the namespace advertismement
- * @param priority for the namespace advertisement
- * @param expiration for the namespace advertisement
- * @param advertisementURI the keyword (!) URI to advertise the
- *        namespace under (we will create a GNUNET_EC_KNBlock)
- * @param rootEntry name of the root entry in the namespace (for
- *        the namespace advertisement)
- *
- * @return uri of the advertisement
+ * @param bo block options
+ * @param rootEntry name of the root of the namespace
+ * @param cont continuation
+ * @param cont_cls closure for cont

  */
  */

-struct GNUNET_FS_Uri *
+void

 GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
 GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,

-                              struct GNUNET_FS_Namespace *namespace,
-                              const struct GNUNET_CONTAINER_MetaData *meta,
-                              uint32_t anonymity,
-                              uint32_t priority,
-                              struct GNUNET_TIME_Absolute expiration,
-                              const struct GNUNET_FS_Uri *advertisementURI,
-                              const char *rootEntry);
+                               struct GNUNET_FS_Uri *ksk_uri,
+                               struct GNUNET_FS_Namespace *namespace,
+                               const struct GNUNET_CONTAINER_MetaData *meta,
+                               const struct GNUNET_FS_BlockOptions *bo,
+                               const char *rootEntry,
+                               GNUNET_FS_PublishContinuation cont,
+                               void *cont_cls);

 
 
 /**
 
 
 /**


@@ -2067,8 +2231,7 @@ GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
  * @return handle to the namespace, NULL on error
  */
 struct GNUNET_FS_Namespace *
  * @return handle to the namespace, NULL on error
  */
 struct GNUNET_FS_Namespace *

-GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h,
-                           const char *name);
+GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, const char *name);

 
 
 /**
 
 
 /**


@@ -2082,9 +2245,8 @@ GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h,
  *
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
  *
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */

-int 
-GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace,
-                           int freeze);
+int
+GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, int freeze);

 
 
 /**
 
 
 /**


@@ -2096,9 +2258,8 @@ GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace,
  * @param name human-readable identifier of the namespace
  * @param id hash identifier for the namespace
  */
  * @param name human-readable identifier of the namespace
  * @param id hash identifier for the namespace
  */

-typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls,
-                                                 const char *name,
-                                                 const GNUNET_HashCode *id);
+typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, const char *name,
+                                                  const GNUNET_HashCode * id);

 
 
 /**
 
 
 /**


@@ -2110,10 +2271,9 @@ typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls,
  * @param cb function to call on each known namespace
  * @param cb_cls closure for cb
  */
  * @param cb function to call on each known namespace
  * @param cb_cls closure for cb
  */

-void 
+void

 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
 GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,

-                         GNUNET_FS_NamespaceInfoProcessor cb,
-                         void *cb_cls);
+                          GNUNET_FS_NamespaceInfoProcessor cb, void *cb_cls);

 
 
 /**
 
 
 /**


@@ -2125,26 +2285,57 @@ GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h,
  * @param last_meta metadata associated with last_uri
  * @param next_id identifier that should be used for updates
  */
  * @param last_meta metadata associated with last_uri
  * @param next_id identifier that should be used for updates
  */

-typedef void 
-(*GNUNET_FS_IdentifierProcessor)(void *cls,
-                                const char *last_id, 
-                                const struct GNUNET_FS_Uri *last_uri,
-                                const struct GNUNET_CONTAINER_MetaData *last_meta,
-                                const char *next_id);
+typedef void (*GNUNET_FS_IdentifierProcessor) (void *cls, const char *last_id,
+                                               const struct GNUNET_FS_Uri *
+                                               last_uri,
+                                               const struct
+                                               GNUNET_CONTAINER_MetaData *
+                                               last_meta, const char *next_id);

 
 
 /**
 
 
 /**

- * List all of the identifiers in the namespace for 
- * which we could produce an update.
+ * List all of the identifiers in the namespace for which we could
+ * produce an update.  Namespace updates form a graph where each node
+ * has a name.  Each node can have any number of URI/meta-data entries
+ * which can each be linked to other nodes.  Cycles are possible.
+ * 
+ * Calling this function with "next_id" NULL will cause the library to
+ * call "ip" with a root for each strongly connected component of the
+ * graph (a root being a node from which all other nodes in the Scc
+ * are reachable).
+ * 
+ * Calling this function with "next_id" being the name of a node will
+ * cause the library to call "ip" with all children of the node.  Note
+ * that cycles within an SCC are possible (including self-loops).

  *
  * @param namespace namespace to inspect for updateable content
  *
  * @param namespace namespace to inspect for updateable content

+ * @param next_id ID to look for; use NULL to look for SCC roots

  * @param ip function to call on each updateable identifier
  * @param ip_cls closure for ip
  */
 void
 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
  * @param ip function to call on each updateable identifier
  * @param ip_cls closure for ip
  */
 void
 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,

-                                    GNUNET_FS_IdentifierProcessor ip, 
-                                    void *ip_cls);
+                                     const char *next_id,
+                                     GNUNET_FS_IdentifierProcessor ip,
+                                     void *ip_cls);
+
+
+/**
+ * Options for searching.  Compatible options
+ * can be OR'ed together.
+ */
+enum GNUNET_FS_SearchOptions
+{
+    /**
+     * No options (use defaults for everything).
+     */
+  GNUNET_FS_SEARCH_OPTION_NONE = 0,
+
+    /**
+     * Only search the local host, do not search remote systems (no P2P)
+     */
+  GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1
+};

 
 
 /**
 
 
 /**


@@ -2154,12 +2345,14 @@ GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
  * @param uri specifies the search parameters; can be
  *        a KSK URI or an SKS URI.
  * @param anonymity desired level of anonymity
  * @param uri specifies the search parameters; can be
  *        a KSK URI or an SKS URI.
  * @param anonymity desired level of anonymity

+ * @param options options for the search
+ * @param cctx initial value for the client context

  * @return context that can be used to control the search
  */
 struct GNUNET_FS_SearchContext *
 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
  * @return context that can be used to control the search
  */
 struct GNUNET_FS_SearchContext *
 GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,

-                       const struct GNUNET_FS_Uri *uri,
-                       uint32_t anonymity);
+                        const struct GNUNET_FS_Uri *uri, uint32_t anonymity,
+                        enum GNUNET_FS_SearchOptions options, void *cctx);

 
 
 /**
 
 
 /**


@@ -2167,7 +2360,7 @@ GNUNET_FS_search_start (struct GNUNET_FS_Handle *h,
  *
  * @param sc context for the search that should be paused
  */
  *
  * @param sc context for the search that should be paused
  */

-void 
+void

 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
 
 
 GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
 
 


@@ -2176,7 +2369,7 @@ GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc);
  *
  * @param sc context for the search that should be resumed
  */
  *
  * @param sc context for the search that should be resumed
  */

-void 
+void

 GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
 
 
 GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
 
 


@@ -2185,7 +2378,7 @@ GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc);
  *
  * @param sc context for the search that should be stopped
  */
  *
  * @param sc context for the search that should be stopped
  */

-void 
+void

 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
 
 
 GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
 
 


@@ -2195,26 +2388,39 @@ GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc);
  * Options for downloading.  Compatible options
  * can be OR'ed together.
  */
  * Options for downloading.  Compatible options
  * can be OR'ed together.
  */

-enum GNUNET_FS_DownloadOptions 
-  {
+enum GNUNET_FS_DownloadOptions
+{

     /**
      * No options (use defaults for everything).
      */
     /**
      * No options (use defaults for everything).
      */

-    GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
-    
+  GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
+
+    /**
+     * Only download from the local host, do not access remote systems (no P2P)
+     */
+  GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1,
+

     /**
      * Do a recursive download (that is, automatically trigger the
      * download of files in directories).
      */
     /**
      * Do a recursive download (that is, automatically trigger the
      * download of files in directories).
      */

-    GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 1,
+  GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2,

 
     /**
      * Do not append temporary data to
      * the target file (for the IBlocks).
      */
 
     /**
      * Do not append temporary data to
      * the target file (for the IBlocks).
      */

-    GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 2
+  GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4,

 
 

-  };
+    /**
+     * Internal option used to flag this download as a 'probe' for a
+     * search result.  Impacts the priority with which the download is
+     * run and causes signalling callbacks to be done differently.
+     * Also, probe downloads are not serialized on suspension.  Normal
+     * clients should not use this!
+     */
+  GNUNET_FS_DOWNLOAD_IS_PROBE = (1 << 31)
+};

 
 
 
 
 
 


@@ -2235,95 +2441,81 @@ enum GNUNET_FS_DownloadOptions
  * @param meta known metadata for the file (can be NULL)
  * @param filename where to store the file, maybe NULL (then no file is
  *        created on disk and data must be grabbed from the callbacks)
  * @param meta known metadata for the file (can be NULL)
  * @param filename where to store the file, maybe NULL (then no file is
  *        created on disk and data must be grabbed from the callbacks)

+ * @param tempname where to store temporary file data, not used if filename is non-NULL;
+ *        can be NULL (in which case we will pick a name if needed); the temporary file
+ *        may already exist, in which case we will try to use the data that is there and
+ *        if it is not what is desired, will overwrite it

  * @param offset at what offset should we start the download (typically 0)
  * @param length how many bytes should be downloaded starting at offset
  * @param anonymity anonymity level to use for the download
  * @param options various download options
  * @param offset at what offset should we start the download (typically 0)
  * @param length how many bytes should be downloaded starting at offset
  * @param anonymity anonymity level to use for the download
  * @param options various download options

+ * @param cctx initial value for the client context for this download

  * @param parent parent download to associate this download with (use NULL
  *        for top-level downloads; useful for manually-triggered recursive downloads)
  * @return context that can be used to control this download
  */
 struct GNUNET_FS_DownloadContext *
  * @param parent parent download to associate this download with (use NULL
  *        for top-level downloads; useful for manually-triggered recursive downloads)
  * @return context that can be used to control this download
  */
 struct GNUNET_FS_DownloadContext *

-GNUNET_FS_file_download_start (struct GNUNET_FS_Handle *h,
-                              const struct GNUNET_FS_Uri *uri,
-                              const struct GNUNET_CONTAINER_MetaData *meta,
-                              const char *filename,
-                              uint64_t offset,
-                              uint64_t length,
-                              uint32_t anonymity,
-                              enum GNUNET_FS_DownloadOptions options,
-                              struct GNUNET_FS_DownloadContext *parent);
-
-
-/**
- * Stop a download (aborts if download is incomplete).
- *
- * @param dc handle for the download
- * @param do_delete delete files of incomplete downloads
- */
-void
-GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *dc,
-                             int do_delete);
+GNUNET_FS_download_start (struct GNUNET_FS_Handle *h,
+                          const struct GNUNET_FS_Uri *uri,
+                          const struct GNUNET_CONTAINER_MetaData *meta,
+                          const char *filename, const char *tempname,
+                          uint64_t offset, uint64_t length, uint32_t anonymity,
+                          enum GNUNET_FS_DownloadOptions options, void *cctx,
+                          struct GNUNET_FS_DownloadContext *parent);

 
 
 /**
 
 
 /**

- * Initialize collection.
+ * Download parts of a file based on a search result.  The download
+ * will be associated with the search result (and the association
+ * will be preserved when serializing/deserializing the state).
+ * If the search is stopped, the download will not be aborted but
+ * be 'promoted' to a stand-alone download.

  *
  *

- * @param h handle to the file sharing subsystem
- * @param namespace namespace to use for the collection
- * @return GNUNET_OK on success, GNUNET_SYSERR if another
- *         namespace is already set for our collection
- */
-int 
-GNUNET_FS_collection_start (struct GNUNET_FS_Handle *h,
-                           struct GNUNET_FS_Namespace *namespace);
-
-
-/**
- * Stop collection.
- *
- * @param h handle to the file sharing subsystem
- * @return GNUNET_OK on success, GNUNET_SYSERR if no collection is active
- */
-int 
-GNUNET_FS_collection_stop (struct GNUNET_FS_Handle *h);
-
-
-/**
- * Are we using a collection?
+ * As with the other download function, this will store
+ * the blocks at the respective offset in the given file.  Also, the
+ * download is still using the blocking of the underlying FS
+ * encoding.  As a result, the download may *write* outside of the
+ * given boundaries (if offset and length do not match the 32k FS
+ * block boundaries). <p>

  *
  *

- * @param h handle to the file sharing subsystem
- * @return NULL if there is no collection,
- */
-struct GNUNET_FS_Namespace *
-GNUNET_FS_collection_get(struct GNUNET_FS_Handle *h);
-
-
-/**
- * Publish an update of the current collection information to the
- * network now.  The function has no effect if the collection has not
- * changed since the last publication.  If we are currently not
- * collecting, this function does nothing.
+ * The given range can be used to focus a download towards a
+ * particular portion of the file (optimization), not to strictly
+ * limit the download to exactly those bytes.

  *
  * @param h handle to the file sharing subsystem
  *
  * @param h handle to the file sharing subsystem

+ * @param sr the search result to use for the download (determines uri and
+ *        meta data and associations)
+ * @param filename where to store the file, maybe NULL (then no file is
+ *        created on disk and data must be grabbed from the callbacks)
+ * @param tempname where to store temporary file data, not used if filename is non-NULL;
+ *        can be NULL (in which case we will pick a name if needed); the temporary file
+ *        may already exist, in which case we will try to use the data that is there and
+ *        if it is not what is desired, will overwrite it
+ * @param offset at what offset should we start the download (typically 0)
+ * @param length how many bytes should be downloaded starting at offset
+ * @param anonymity anonymity level to use for the download
+ * @param options various download options
+ * @param cctx initial value for the client context for this download
+ * @return context that can be used to control this download

  */
  */

-void GNUNET_FS_collection_publish (struct GNUNET_FS_Handle *h);
+struct GNUNET_FS_DownloadContext *
+GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h,
+                                      struct GNUNET_FS_SearchResult *sr,
+                                      const char *filename,
+                                      const char *tempname, uint64_t offset,
+                                      uint64_t length, uint32_t anonymity,
+                                      enum GNUNET_FS_DownloadOptions options,
+                                      void *cctx);

 
 
 /**
 
 
 /**

- * If we are currently building a collection, publish the given file
- * information in that collection.  If we are currently not
- * collecting, this function does nothing.
+ * Stop a download (aborts if download is incomplete).

  *
  *

- * @param h handle to the file sharing subsystem
- * @param uri uri to add to the collection
- * @param meta metadata for the uri
+ * @param dc handle for the download
+ * @param do_delete delete files of incomplete downloads

  */
  */

-void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h,
-                              const struct GNUNET_FS_Uri *uri,
-                              const struct GNUNET_CONTAINER_MetaData *meta);
-
-
+void
+GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete);

 
 
 
 
 
 


@@ -2341,8 +2533,9 @@ void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h,
  * @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')
  */
  * @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_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData *md);
+int
+GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData
+                                        *md);

 
 
 /**
 
 
 /**


@@ -2355,6 +2548,17 @@ void
 GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
 
 
 GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
 
 

+/**
+ * Suggest a filename based on given metadata.
+ * 
+ * @param md given meta data
+ * @return NULL if meta data is useless for suggesting a filename
+ */
+char *
+GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData
+                                      *md);
+
+

 /**
  * Function used to process entries in a directory.
  *
 /**
  * Function used to process entries in a directory.
  *


@@ -2370,12 +2574,14 @@ GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
  *            embedded with the directory itself).
  * @param data data available for the file (length bytes)
  */
  *            embedded with the directory itself).
  * @param data data available for the file (length bytes)
  */

-typedef void (*GNUNET_FS_DirectoryEntryProcessor)(void *cls,
-                                                 const char *filename,
-                                                 const struct GNUNET_FS_Uri *uri,
-                                                 const struct GNUNET_CONTAINER_MetaData *meta,
-                                                 size_t length,
-                                                 const void *data);
+typedef void (*GNUNET_FS_DirectoryEntryProcessor) (void *cls,
+                                                   const char *filename,
+                                                   const struct GNUNET_FS_Uri *
+                                                   uri,
+                                                   const struct
+                                                   GNUNET_CONTAINER_MetaData *
+                                                   meta, size_t length,
+                                                   const void *data);

 
 
 /**
 
 
 /**


@@ -2393,13 +2599,15 @@ typedef void (*GNUNET_FS_DirectoryEntryProcessor)(void *cls,
  * @param offset offset of data in the directory
  * @param dep function to call on each entry
  * @param dep_cls closure for dep
  * @param offset offset of data in the directory
  * @param dep function to call on each entry
  * @param dep_cls closure for dep

+ * @return GNUNET_OK if this could be a block in a directory,
+ *         GNUNET_NO if this could be part of a directory (but not 100% OK)
+ *         GNUNET_SYSERR if 'data' does not represent a directory

  */
  */

-void 
-GNUNET_FS_directory_list_contents (size_t size,
-                                  const void *data,
-                                  uint64_t offset,
-                                  GNUNET_FS_DirectoryEntryProcessor dep, 
-                                  void *dep_cls);
+int
+GNUNET_FS_directory_list_contents (size_t size, const void *data,
+                                   uint64_t offset,
+                                   GNUNET_FS_DirectoryEntryProcessor dep,
+                                   void *dep_cls);

 
 
 /**
 
 
 /**


@@ -2413,7 +2621,8 @@ struct GNUNET_FS_DirectoryBuilder;
  * @param mdir metadata for the directory
  */
 struct GNUNET_FS_DirectoryBuilder *
  * @param mdir metadata for the directory
  */
 struct GNUNET_FS_DirectoryBuilder *

-GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData *mdir);
+GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData
+                                    *mdir);

 
 
 /**
 
 
 /**


@@ -2428,10 +2637,10 @@ GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData *mdir
  */
 void
 GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
  */
 void
 GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,

-                                const struct GNUNET_FS_Uri *uri,
-                                const struct GNUNET_CONTAINER_MetaData *md,
-                                const void *data);
-                
+                                 const struct GNUNET_FS_Uri *uri,
+                                 const struct GNUNET_CONTAINER_MetaData *md,
+                                 const void *data);
+

 
 /**
  * Finish building the directory.  Frees the
 
 /**
  * Finish building the directory.  Frees the


@@ -2445,8 +2654,7 @@ GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
  */
 int
 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
  */
 int
 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,

-                                   size_t *rsize,
-                                   void **rdata);
+                                    size_t * rsize, void **rdata);

 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */