X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_fs_service.h;h=f50166d326279aaf29ad458d4f1d583f00275a02;hb=27c12911f4f2aba2d90099270d70de846e83854f;hp=5dcee17cdc151b94f73c171fa30f09103c8ce931;hpb=303ab4dafbc680b1b362f95df5b12dae831b1593;p=oweals%2Fgnunet.git

diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index 5dcee17cd..f50166d32 100644
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -85,187 +85,13 @@ struct GNUNET_FS_Uri;
  * @param cls closure
  * @param keyword the keyword
  * @param is_mandatory is the keyword mandatory (in a search)
- * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort
+ * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to abort
  */
 typedef int (*GNUNET_FS_KeywordIterator) (void *cls, const char *keyword,
                                           int is_mandatory);
 
 
 
-/**
- * Iterator over all known pseudonyms.
- *
- * @param cls closure
- * @param pseudonym public key of pseudonym
- * @param name name of the pseudonym (might be NULL)
- * @param unique_name unique name of the pseudonym (might be NULL)
- * @param md meta data known about the pseudonym
- * @param rating the local rating of the pseudonym
- * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
- */
-typedef int (*GNUNET_FS_PseudonymIterator) (void *cls,
-					    const struct GNUNET_CRYPTO_EccPublicKey *pseudonym,
-					    const char *name,
-					    const char *unique_name,
-					    const struct GNUNET_CONTAINER_MetaData *md, 
-					    int32_t rating);
-
-
-/**
- * Change the rank of a pseudonym.
- *
- * @param cfg overall configuration
- * @param pseudonym identity of the pseudonym
- * @param delta by how much should the rating be changed?
- * @return new rating of the pseudonym
- */
-int
-GNUNET_FS_pseudonym_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
-			  const struct GNUNET_CRYPTO_EccPublicKey *pseudonym, 
-			  int32_t delta);
-
-
-/**
- * Add a pseudonym to the set of known pseudonyms.
- * For all pseudonym advertisements that we discover
- * FS should automatically call this function.
- *
- * @param cfg overall configuration
- * @param pseudonym the pseudonym identifier
- * @param meta metadata for the pseudonym
- * @return GNUNET_OK on success, GNUNET_SYSERR on failure
- */
-int
-GNUNET_FS_pseudonym_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
-			 const struct GNUNET_CRYPTO_EccPublicKey *pseudonym,
-			 const struct GNUNET_CONTAINER_MetaData *meta);
-
-
-/**
- * List all known pseudonyms.
- *
- * @param cfg overall configuration
- * @param iterator function to call for each pseudonym
- * @param iterator_cls closure for iterator
- * @return number of pseudonyms found
- */
-int
-GNUNET_FS_pseudonym_list_all (const struct GNUNET_CONFIGURATION_Handle *cfg,
-			      GNUNET_FS_PseudonymIterator iterator, 
-			      void *iterator_cls);
-
-
-/**
- * Handle for a discovery callback registration.
- */
-struct GNUNET_FS_Pseudonym_DiscoveryHandle;
-
-
-/**
- * Register callback to be invoked whenever we discover
- * a new pseudonym.
- *
- * @param cfg our configuration
- * @param iterator function to invoke on discovery
- * @param iterator_cls closure for iterator
- * @return registration handle
- */
-struct GNUNET_FS_Pseudonym_DiscoveryHandle *
-GNUNET_FS_pseudonym_discovery_callback_register (const struct GNUNET_CONFIGURATION_Handle *cfg,
-						 GNUNET_FS_PseudonymIterator iterator, 
-						 void *iterator_cls);
-
-
-/**
- * Unregister pseudonym discovery callback.
- *
- * @param dh registration to unregister
- */
-void
-GNUNET_FS_pseudonym_discovery_callback_unregister (struct GNUNET_FS_Pseudonym_DiscoveryHandle *dh);
-
-
-/**
- * Return unique variant of the pseudonym name.  Use after
- * GNUNET_FS_pseudonym_id_to_name() to make sure that name is unique.
- *
- * @param cfg configuration
- * @param pseudonym cryptographic ID of the pseudonym
- * @param name name to uniquify
- * @param suffix if not NULL, filled with the suffix value
- * @return NULL on failure (should never happen), name on success.
- *         Free the name with GNUNET_free().
- */
-char *
-GNUNET_FS_pseudonym_name_uniquify (const struct GNUNET_CONFIGURATION_Handle *cfg,
-				   const struct GNUNET_CRYPTO_EccPublicKey *pseudonym, 
-				   const char *name, 
-				   unsigned int *suffix);
-
-
-/**
- * Get pseudonym name, metadata and rank. This is a wrapper around
- * internal read_info() call, and ensures that returned data is not
- * invalid (not NULL).  Writing back information returned by this
- * function will give a name "no-name" to pseudonyms that have no
- * name. This side-effect is unavoidable, but hardly harmful.
- *
- * @param cfg configuration
- * @param pseudonym cryptographic ID of the pseudonym
- * @param ret_meta a location to store metadata pointer. NULL, if metadata
- *        is not needed. Destroy with GNUNET_CONTAINER_meta_data_destroy().
- * @param ret_rank a location to store rank. NULL, if rank not needed.
- * @param ret_name a location to store human-readable name. Name is not unique.
- *        NULL, if name is not needed. Free with GNUNET_free().
- * @param name_is_a_dup is set to GNUNET_YES, if ret_name was filled with
- *        a duplicate of a "no-name" placeholder
- * @return GNUNET_OK on success. GNUENT_SYSERR if the data was
- *         unobtainable (in that case ret_* are filled with placeholders - 
- *         empty metadata container, rank -1 and a "no-name" name).
- */
-int
-GNUNET_FS_pseudonym_get_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
-			      const struct GNUNET_CRYPTO_EccPublicKey *pseudonym, 
-			      struct GNUNET_CONTAINER_MetaData **ret_meta,
-			      int32_t *ret_rank, 
-			      char **ret_name, 
-			      int *name_is_a_dup);
-
-
-/**
- * Get the pseudonym ID belonging to the given pseudonym name.
- *
- * @param cfg configuration to use
- * @param ns_uname unique (!) human-readable name for the pseudonym
- * @param pseudonym set to pseudonym ID based on 'ns_uname'
- * @return GNUNET_OK on success, GNUNET_SYSERR on failure
- */
-int
-GNUNET_FS_pseudonym_name_to_id (const struct GNUNET_CONFIGURATION_Handle *cfg,
-				const char *ns_uname,
-				struct GNUNET_CRYPTO_EccPublicKey *pseudonym);
-
-
-/**
- * Set the pseudonym metadata, rank and name.
- *
- * @param cfg overall configuration
- * @param pseudonym id of the pseudonym
- * @param name name to set. Must be the non-unique version of it.
- *        May be NULL, in which case it erases pseudonym's name!
- * @param md metadata to set
- *        May be NULL, in which case it erases pseudonym's metadata!
- * @param rank rank to assign
- * @return GNUNET_OK on success, GNUNET_SYSERR on failure
- */
-int
-GNUNET_FS_pseudonym_set_info (const struct GNUNET_CONFIGURATION_Handle *cfg,
-			      const struct GNUNET_CRYPTO_EccPublicKey *pseudonym, 
-			      const char *name,
-			      const struct GNUNET_CONTAINER_MetaData *md, 
-			      int32_t rank);
-
-
 /**
  * Get a unique key from a URI.  This is for putting URIs
  * into HashMaps.  The key may change between FS implementations.
@@ -308,7 +134,7 @@ GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri);
  * @param is_mandatory is this keyword mandatory?
  */
 void
-GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri, 
+GNUNET_FS_uri_ksk_add_keyword (struct GNUNET_FS_Uri *uri,
 			       const char *keyword,
                                int is_mandatory);
 
@@ -360,7 +186,7 @@ GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri);
  *
  * @param uri ksk uri to get the keywords from
  * @param iterator function to call on each keyword
- * @param iterator_cls closure for iterator
+ * @param iterator_cls closure for @a iterator
  * @return -1 if this is not a keyword URI, otherwise number of
  *   keywords iterated over until iterator aborted
  */
@@ -375,7 +201,7 @@ GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri,
  *
  * @param uri the location URI to inspect
  * @param peer where to store the identify of the peer (presumably) offering the content
- * @return GNUNET_SYSERR if this is not a location URI, otherwise GNUNET_OK
+ * @return #GNUNET_SYSERR if this is not a location URI, otherwise #GNUNET_OK
  */
 int
 GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri,
@@ -477,7 +303,8 @@ GNUNET_FS_uri_ksk_create (const char *keywords, char **emsg);
  *  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);
 
 
 /**
@@ -485,7 +312,7 @@ GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, const char **argv);
  *
  * @param u1 one of the URIs
  * @param u2 the other URI
- * @return GNUNET_YES if the URIs are equal
+ * @return #GNUNET_YES if the URIs are equal
  */
 int
 GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
@@ -496,7 +323,7 @@ GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1,
  * Is this a namespace URI?
  *
  * @param uri the uri to check
- * @return GNUNET_YES if this is an SKS uri
+ * @return #GNUNET_YES if this is an SKS uri
  */
 int
 GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
@@ -510,7 +337,7 @@ GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri);
  * @return an FS URI for the given namespace and identifier
  */
 struct GNUNET_FS_Uri *
-GNUNET_FS_uri_sks_create (const struct GNUNET_CRYPTO_EccPublicKey *ns, 
+GNUNET_FS_uri_sks_create (const struct GNUNET_CRYPTO_EcdsaPublicKey *ns,
 			  const char *id);
 
 
@@ -520,11 +347,11 @@ GNUNET_FS_uri_sks_create (const struct GNUNET_CRYPTO_EccPublicKey *ns,
  *
  * @param uri the uri to get the namespace ID from
  * @param pseudonym where to store the public key of the namespace
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
-                                 struct GNUNET_CRYPTO_EccPublicKey *pseudonym);
+                                 struct GNUNET_CRYPTO_EcdsaPublicKey *pseudonym);
 
 
 /**
@@ -537,24 +364,11 @@ char *
 GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri);
 
 
-/**
- * Convert namespace URI to a human readable format
- * (using the namespace description, if available).
- *
- * @param cfg configuration to use
- * @param uri SKS uri to convert
- * @return NULL on error (not an SKS URI)
- */
-char *
-GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg,
-                                   const struct GNUNET_FS_Uri *uri);
-
-
 /**
  * Is this a keyword URI?
  *
  * @param uri the uri
- * @return GNUNET_YES if this is a KSK uri
+ * @return #GNUNET_YES if this is a KSK uri
  */
 int
 GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
@@ -564,7 +378,7 @@ GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri);
  * Is this a file (or directory) URI?
  *
  * @param uri the uri to check
- * @return GNUNET_YES if this is a CHK uri
+ * @return #GNUNET_YES if this is a CHK uri
  */
 int
 GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri);
@@ -585,7 +399,7 @@ GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri);
  * Is this a location URI?
  *
  * @param uri the uri to check
- * @return GNUNET_YES if this is a LOC uri
+ * @return #GNUNET_YES if this is a LOC uri
  */
 int
 GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
@@ -616,7 +430,7 @@ GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData
  * @param scls must be of type "struct GNUNET_FS_Uri **"
  * @param option name of the option (typically 'k')
  * @param value command line argument given
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -631,10 +445,10 @@ GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext
  * the metadata must be passed as the "scls" argument.
  *
  * @param ctx command line processor context
- * @param scls must be of type "struct GNUNET_CONTAINER_MetaData **"
+ * @param scls must be of type `struct GNUNET_CONTAINER_MetaData **`
  * @param option name of the option (typically 'k')
  * @param value command line argument given
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext
@@ -871,7 +685,13 @@ enum GNUNET_FS_Status
    * Notification that the unindexing of this file
    * was stopped (final event for this action).
    */
-  GNUNET_FS_STATUS_UNINDEX_STOPPED = 36
+  GNUNET_FS_STATUS_UNINDEX_STOPPED = 36,
+
+  /**
+   * Notification that we are making progress sharing a directory.
+   */
+  GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY = 37
+
 };
 
 
@@ -1000,7 +820,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
+	 * #GNUNET_FS_STATUS_PUBLISH_PROGRESS events.
 	 */
         struct
         {
@@ -1030,7 +850,34 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_PUBLISH_RESUME events.
+	 * #GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY events.
+	 */
+        struct
+        {
+
+          /**
+	   * How far are we along in the overall directory?
+	   */
+          uint64_t completed;
+
+          /**
+	   * How big do we estimate the entire directory to be?
+	   */
+          uint64_t total;
+
+          /**
+           * At what time do we expect to finish the upload of the
+           * CONTENTS of the directory. (The direcory itself will take
+           * extra time, indicated with the "eta" member at the
+           * "publish"-level of this struct.)
+           */
+          struct GNUNET_TIME_Relative eta;
+
+        } progress_directory;
+
+        /**
+	 * These values are only valid for
+	 * #GNUNET_FS_STATUS_PUBLISH_RESUME events.
 	 */
         struct
         {
@@ -1049,7 +896,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
+	 * #GNUNET_FS_STATUS_PUBLISH_COMPLETED events.
 	 */
         struct
         {
@@ -1063,7 +910,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_PUBLISH_ERROR events.
+	 * #GNUNET_FS_STATUS_PUBLISH_ERROR events.
 	 */
         struct
         {
@@ -1164,7 +1011,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
+	 * #GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events.
 	 */
         struct
         {
@@ -1189,7 +1036,7 @@ struct GNUNET_FS_ProgressInfo
 
           /**
 	   * How much time passed between us asking for this block and
-           * actually getting it? GNUNET_TIME_UNIT_FOREVER_REL if unknown.
+           * actually getting it? #GNUNET_TIME_UNIT_FOREVER_REL if unknown.
 	   */
           struct GNUNET_TIME_Relative block_download_duration;
 
@@ -1219,7 +1066,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_DOWNLOAD_START events.
+	 * #GNUNET_FS_STATUS_DOWNLOAD_START events.
 	 */
         struct
         {
@@ -1233,7 +1080,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
+	 * #GNUNET_FS_STATUS_DOWNLOAD_RESUME events.
 	 */
         struct
         {
@@ -1252,7 +1099,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
+	 * #GNUNET_FS_STATUS_DOWNLOAD_ERROR events.
 	 */
         struct
         {
@@ -1326,7 +1173,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_RESULT events.
+	 * #GNUNET_FS_STATUS_SEARCH_RESULT events.
 	 */
         struct
         {
@@ -1356,7 +1203,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
+	 * #GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events.
 	 */
         struct
         {
@@ -1399,7 +1246,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_UPDATE events.
+	 * #GNUNET_FS_STATUS_SEARCH_UPDATE events.
 	 */
         struct
         {
@@ -1448,10 +1295,10 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
+	 * #GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events.
 	 * These events are automatically triggered for
 	 * each search result before the
-	 * GNUNET_FS_STATUS_SEARCH_SUSPEND event.  This
+	 * #GNUNET_FS_STATUS_SEARCH_SUSPEND event.  This
 	 * happens primarily to give the client a chance
 	 * to clean up the "cctx" (if needed).
 	 */
@@ -1478,10 +1325,10 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
+	 * #GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED events.
 	 * These events are automatically triggered for
 	 * each search result before the
-	 * GNUNET_FS_STATUS_SEARCH_STOPPED event.  This
+	 * #GNUNET_FS_STATUS_SEARCH_STOPPED event.  This
 	 * happens primarily to give the client a chance
 	 * to clean up the "cctx" (if needed).
 	 */
@@ -1508,7 +1355,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_RESUME events.
+	 * #GNUNET_FS_STATUS_SEARCH_RESUME events.
 	 */
         struct
         {
@@ -1527,7 +1374,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_SEARCH_ERROR events.
+	 * #GNUNET_FS_STATUS_SEARCH_ERROR events.
 	 */
         struct
         {
@@ -1540,7 +1387,7 @@ struct GNUNET_FS_ProgressInfo
         } error;
 
         /**
-	 * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events.
+	 * Values for #GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE events.
 	 */
         struct
         {
@@ -1563,7 +1410,7 @@ struct GNUNET_FS_ProgressInfo
           /**
 	   * Public key of the namespace.
 	   */
-          struct GNUNET_CRYPTO_EccPublicKey pseudonym;
+          struct GNUNET_CRYPTO_EcdsaPublicKey pseudonym;
 
         } ns;
 
@@ -1625,7 +1472,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
+	 * #GNUNET_FS_STATUS_UNINDEX_PROGRESS events.
 	 */
         struct
         {
@@ -1655,7 +1502,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_UNINDEX_RESUME events.
+	 * #GNUNET_FS_STATUS_UNINDEX_RESUME events.
 	 */
         struct
         {
@@ -1669,7 +1516,7 @@ struct GNUNET_FS_ProgressInfo
 
         /**
 	 * These values are only valid for
-	 * GNUNET_FS_STATUS_UNINDEX_ERROR events.
+	 * #GNUNET_FS_STATUS_UNINDEX_ERROR events.
 	 */
         struct
         {
@@ -1712,7 +1559,7 @@ struct GNUNET_FS_ProgressInfo
  *         for this operation; should be set to NULL for
  *         SUSPEND and STOPPED events).  The value returned
  *         will be passed to future callbacks in the respective
- *         field in the GNUNET_FS_ProgressInfo struct.
+ *         field in the `struct GNUNET_FS_ProgressInfo`.
  */
 typedef void *(*GNUNET_FS_ProgressCallback) (void *cls,
                                              const struct GNUNET_FS_ProgressInfo *info);
@@ -1723,22 +1570,22 @@ typedef void *(*GNUNET_FS_ProgressCallback) (void *cls,
  */
 enum GNUNET_FS_Flags
 {
-    /**
-     * No special flags set.
-     */
+  /**
+   * No special flags set.
+   */
   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,
 
-    /**
-     * Should we automatically trigger probes for search results
-     * to determine availability?
-     * (will create GNUNET_FS_STATUS_SEARCH_UPDATE events).
-     */
+  /**
+   * 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
 };
 
@@ -1816,33 +1663,6 @@ struct GNUNET_FS_BlockOptions
 };
 
 
-/**
- * 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);
-
-
-/**
- * Convert an expiration time to the respective year (rounds)
- *
- * @param at absolute time 
- * @return year a year (after 1970), 0 on error
- */
-unsigned int 
-GNUNET_FS_time_to_year (struct GNUNET_TIME_Absolute at);
-
-
 /**
  * Handle to the file-sharing service.
  */
@@ -1855,9 +1675,9 @@ struct GNUNET_FS_Handle;
  * @param cfg configuration to use
  * @param client_name unique identifier for this client
  * @param upcb function to call to notify about FS actions
- * @param upcb_cls closure for upcb
+ * @param upcb_cls closure for @a upcb
  * @param flags specific attributes for fs-operations
- * @param ... list of optional options, terminated with GNUNET_FS_OPTIONS_END
+ * @param ... list of optional options, terminated with #GNUNET_FS_OPTIONS_END
  * @return NULL on error
  */
 struct GNUNET_FS_Handle *
@@ -1878,7 +1698,7 @@ GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
 
 
 /**
- * Function called on entries in a GNUNET_FS_FileInformation publish-structure.
+ * Function called on entries in a `struct GNUNET_FS_FileInformation` iteration.
  *
  * @param cls closure
  * @param fi the entry in the publish-structure
@@ -1888,8 +1708,8 @@ GNUNET_FS_stop (struct GNUNET_FS_Handle *h);
  * @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
+ * @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,
@@ -1911,8 +1731,7 @@ typedef int (*GNUNET_FS_FileInformationProcessor) (void *cls,
  * file information structures.
  *
  * @param s structure to get the filename for
- * @return NULL on error, otherwise filename that
- *         can be passed to "GNUNET_FS_file_information_recover"
+ * @return NULL on error, otherwise filename that can be used
  *         to read this fi-struct from disk.
  */
 const char *
@@ -1951,8 +1770,8 @@ GNUNET_FS_file_information_set_filename (struct GNUNET_FS_FileInformation *s,
  * @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 do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
+ *                #GNUNET_SYSERR for simulation
  * @param bo block options
  * @return publish structure entry for the file
  */
@@ -1980,8 +1799,8 @@ GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h,
  * @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 do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
+ *                #GNUNET_SYSERR for simulation
  * @param bo block options
  * @return publish structure entry for the file
  */
@@ -2016,7 +1835,7 @@ GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h,
  *            the reader to clean up its internal state
  * @param buf where the reader should write the data
  * @param emsg location for the reader to store an error message
- * @return number of bytes written, usually "max", 0 on error
+ * @return number of bytes written, usually @a max, 0 on error
  */
 typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max,
                                         void *buf, char **emsg);
@@ -2029,12 +1848,12 @@ typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max,
  * @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 reader_cls closure for @a reader
  * @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 do_index #GNUNET_YES for index, #GNUNET_NO for insertion,
+ *                #GNUNET_SYSERR for simulation
  * @param bo block options
  * @return publish structure entry for the file
  */
@@ -2055,9 +1874,6 @@ GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h,
 
 /**
  * Create an entry for an empty directory in a publish-structure.
- * This function should be used by applications for which the
- * use of "GNUNET_FS_file_information_create_from_directory"
- * is not appropriate.
  *
  * @param h handle to the file sharing subsystem
  * @param client_info initial client-info value for this entry
@@ -2085,7 +1901,7 @@ GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h,
  * 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
+ * @return #GNUNET_YES if so, #GNUNET_NO if not
  */
 int
 GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation
@@ -2095,13 +1911,13 @@ GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation
 /**
  * Add an entry to a directory in a publish-structure.  Clients
  * should never modify publish structures that were passed to
- * "GNUNET_FS_publish_start" already.
+ * #GNUNET_FS_publish_start already.
  *
  * @param dir the directory
  * @param ent the entry to add; the entry must not have been
  *            added to any other directory at this point and
- *            must not include "dir" in its structure
- * @return GNUNET_OK on success, GNUNET_SYSERR on error
+ *            must not include @a dir in its structure
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
  */
 int
 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
@@ -2111,16 +1927,16 @@ GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
 /**
  * Inspect a file or directory in a publish-structure.  Clients
  * should never modify publish structures that were passed to
- * "GNUNET_FS_publish_start" already.  When called on a directory,
- * this function will FIRST call "proc" with information about
+ * #GNUNET_FS_publish_start already.  When called on a directory,
+ * this function will FIRST call @a proc with information about
  * the directory itself and then for each of the files in the
  * directory (but not for files in subdirectories).  When called
- * on a file, "proc" will be called exactly once (with information
+ * on a file, @a proc will be called exactly once (with information
  * about the specific file).
  *
  * @param dir the directory
  * @param proc function to call on each entry
- * @param proc_cls closure for proc
+ * @param proc_cls closure for @a proc
  */
 void
 GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
@@ -2130,13 +1946,13 @@ GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir,
 
 /**
  * Destroy publish-structure.  Clients should never destroy publish
- * structures that were passed to "GNUNET_FS_publish_start" already.
+ * structures that were passed to #GNUNET_FS_publish_start already.
  *
  * @param fi structure to destroy
  * @param cleaner function to call on each entry in the structure
  *        (useful to clean up client_info); can be NULL; return
  *        values are ignored
- * @param cleaner_cls closure for cleaner
+ * @param cleaner_cls closure for @a cleaner
  */
 void
 GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
@@ -2150,15 +1966,15 @@ GNUNET_FS_file_information_destroy (struct GNUNET_FS_FileInformation *fi,
  */
 enum GNUNET_FS_PublishOptions
 {
-    /**
-     * No options (use defaults for everything).
-     */
+  /**
+   * No options (use defaults for everything).
+   */
   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
 };
 
@@ -2179,7 +1995,7 @@ enum GNUNET_FS_PublishOptions
 struct GNUNET_FS_PublishContext *
 GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h,
                          struct GNUNET_FS_FileInformation *fi,
-                         const struct GNUNET_CRYPTO_EccPrivateKey *ns,
+                         const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
 			 const char *nid,
                          const char *nuid,
                          enum GNUNET_FS_PublishOptions options);
@@ -2226,8 +2042,8 @@ struct GNUNET_FS_PublishKskContext;
  * @param bo block options
  * @param options publication options
  * @param cont continuation
- * @param cont_cls closure for cont
- * @return NULL on error ('cont' will still be called)
+ * @param cont_cls closure for @a cont
+ * @return NULL on error (@a cont will still be called)
  */
 struct GNUNET_FS_PublishKskContext *
 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
@@ -2266,13 +2082,14 @@ struct GNUNET_FS_PublishSksContext;
  * @param bo block options
  * @param options publication options
  * @param cont continuation
- * @param cont_cls closure for cont
- * @return NULL on error ('cont' will still be called)
+ * @param cont_cls closure for @a cont
+ * @return NULL on error (@a cont will still be called)
  */
 struct GNUNET_FS_PublishSksContext *
 GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
-                       const struct GNUNET_CRYPTO_EccPrivateKey *ns,
-                       const char *identifier, const char *update,
+                       const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
+                       const char *identifier,
+		       const char *update,
                        const struct GNUNET_CONTAINER_MetaData *meta,
                        const struct GNUNET_FS_Uri *uri,
                        const struct GNUNET_FS_BlockOptions *bo,
@@ -2290,12 +2107,12 @@ GNUNET_FS_publish_sks_cancel (struct GNUNET_FS_PublishSksContext *psc);
 
 
 /**
- * Type of a function called by "GNUNET_FS_get_indexed_files".
+ * Type of a function called by #GNUNET_FS_get_indexed_files.
  *
  * @param cls closure
  * @param filename the name of the file, NULL for end of list
  * @param file_id hash of the contents of the indexed file
- * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
+ * @return #GNUNET_OK to continue iteration, #GNUNET_SYSERR to abort
  */
 typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename,
                                                const struct GNUNET_HashCode * file_id);
@@ -2312,8 +2129,8 @@ struct GNUNET_FS_GetIndexedContext;
  *
  * @param h handle to the file sharing subsystem
  * @param iterator function to call on each indexed file
- * @param iterator_cls closure for iterator
- * @return NULL on error ('iter' is not called)
+ * @param iterator_cls closure for @a iterator
+ * @return NULL on error (@a iterator is not called)
  */
 struct GNUNET_FS_GetIndexedContext *
 GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
@@ -2339,7 +2156,8 @@ GNUNET_FS_get_indexed_files_cancel (struct GNUNET_FS_GetIndexedContext *gic);
  * @return NULL on error, otherwise handle
  */
 struct GNUNET_FS_UnindexContext *
-GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, const char *filename,
+GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h,
+			 const char *filename,
                          void *cctx);
 
 
@@ -2357,16 +2175,15 @@ GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
  *
  * @param cls closure
  * @param last_id last identifier
- * @param last_uri uri used for the content published under the last_id
- * @param last_meta metadata associated with last_uri
+ * @param last_uri uri used for the content published under the @a last_id
+ * @param last_meta metadata associated with @a 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);
 
 
 /**
@@ -2375,24 +2192,24 @@ typedef void (*GNUNET_FS_IdentifierProcessor) (void *cls, const char *last_id,
  * 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
+ * Calling this function with @a next_id NULL will cause the library to
+ * call @a 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
+ * Calling this function with @a next_id being the name of a node will
+ * cause the library to call @a ip with all children of the node.  Note
  * that cycles within an SCC are possible (including self-loops).
  *
-* @param h fs handle to use
+ * @param h fs handle to use
  * @param ns 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
+ * @param ip_cls closure for @a ip
  */
 void
 GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Handle *h,
-				     const struct GNUNET_CRYPTO_EccPrivateKey *ns,
+				     const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns,
                                      const char *next_id,
                                      GNUNET_FS_IdentifierProcessor ip,
                                      void *ip_cls);
@@ -2480,7 +2297,7 @@ GNUNET_FS_probe (struct GNUNET_FS_Handle *h,
 
 /**
  * Stop probe activity.  Must ONLY be used on values
- * returned from 'GNUNET_FS_probe'.
+ * returned from #GNUNET_FS_probe.
  *
  * @param sr search result to stop probing for (freed)
  * @return the value of the 'client_info' pointer
@@ -2495,35 +2312,35 @@ GNUNET_FS_probe_stop (struct GNUNET_FS_SearchResult *sr);
  */
 enum GNUNET_FS_DownloadOptions
 {
-    /**
-     * No options (use defaults for everything).
-     */
+  /**
+   * No options (use defaults for everything).
+   */
   GNUNET_FS_DOWNLOAD_OPTION_NONE = 0,
 
-    /**
-     * Only download from the local host, do not access remote systems (no P2P)
-     */
+  /**
+   * 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 = 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 = 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!
-     */
+  /**
+   * 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)
 };
 
@@ -2535,7 +2352,7 @@ enum GNUNET_FS_DownloadOptions
  * 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>
+ * block boundaries).
  *
  * The given range can be used to focus a download towards a
  * particular portion of the file (optimization), not to strictly
@@ -2581,7 +2398,7 @@ GNUNET_FS_download_start (struct GNUNET_FS_Handle *h,
  * 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>
+ * block boundaries).
  *
  * The given range can be used to focus a download towards a
  * particular portion of the file (optimization), not to strictly
@@ -2635,8 +2452,8 @@ GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete);
  * Does the meta-data claim that this is a directory?
  * Checks if the mime-type is that of a GNUnet directory.
  *
- * @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
@@ -2660,8 +2477,7 @@ GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md);
  * @return NULL if meta data is useless for suggesting a filename
  */
 char *
-GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData
-                                      *md);
+GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData *md);
 
 
 /**
@@ -2703,10 +2519,10 @@ typedef void (*GNUNET_FS_DirectoryEntryProcessor) (void *cls,
  * @param data pointer to the beginning of the directory
  * @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
+ * @param dep_cls closure for @a 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
  */
 int
 GNUNET_FS_directory_list_contents (size_t size, const void *data,
@@ -2720,6 +2536,7 @@ GNUNET_FS_directory_list_contents (size_t size, const void *data,
  */
 struct GNUNET_FS_DirectoryBuilder;
 
+
 /**
  * Create a directory builder.
  *
@@ -2755,7 +2572,7 @@ GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
  * @param bld directory to finish
  * @param rsize set to the number of bytes needed
  * @param rdata set to the encoded directory
- * @return GNUNET_OK on success
+ * @return #GNUNET_OK on success
  */
 int
 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
@@ -2811,14 +2628,14 @@ enum GNUNET_FS_DirScannerProgressUpdateReason
  *
  * @param cls closure
  * @param filename which file we are making progress on
- * @param is_directory GNUNET_YES if this is a directory,
- *                     GNUNET_NO if this is a file
- *                     GNUNET_SYSERR if it is neither (or unknown)
+ * @param is_directory #GNUNET_YES if this is a directory,
+ *                     #GNUNET_NO if this is a file
+ *                     #GNUNET_SYSERR if it is neither (or unknown)
  * @param reason kind of progress we are making
  */
-typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls, 
+typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
 						      const char *filename,
-						      int is_directory, 
+						      int is_directory,
 						      enum GNUNET_FS_DirScannerProgressUpdateReason reason);
 
 
@@ -2876,7 +2693,7 @@ struct GNUNET_FS_ShareTreeItem
   char *short_filename;
 
   /**
-   * GNUNET_YES if this is a directory
+   * #GNUNET_YES if this is a directory
    */
   int is_directory;
 
@@ -2893,22 +2710,22 @@ struct GNUNET_FS_DirScanner;
  * Start a directory scanner.
  *
  * @param filename name of the directory to scan
- * @param disable_extractor GNUNET_YES to not to run libextractor on files (only build a tree)
+ * @param disable_extractor #GNUNET_YES to not to run libextractor on files (only build a tree)
  * @param ex if not NULL, must be a list of extra plugins for extractor
  * @param cb the callback to call when there are scanning progress messages
- * @param cb_cls closure for 'cb'
+ * @param cb_cls closure for @a cb
  * @return directory scanner object to be used for controlling the scanner
  */
 struct GNUNET_FS_DirScanner *
 GNUNET_FS_directory_scan_start (const char *filename,
-				int disable_extractor, 
+				int disable_extractor,
 				const char *ex,
-				GNUNET_FS_DirScannerProgressCallback cb, 
+				GNUNET_FS_DirScannerProgressCallback cb,
 				void *cb_cls);
 
 
 /**
- * Abort the scan.    Must not be called from within the progress_callback
+ * Abort the scan. Must not be called from within the progress_callback
  * function.
  *
  * @param ds directory scanner structure
@@ -2919,7 +2736,7 @@ GNUNET_FS_directory_scan_abort (struct GNUNET_FS_DirScanner *ds);
 
 /**
  * Obtain the result of the scan after the scan has signalled
- * completion.  Must not be called prior to completion.  The 'ds' is
+ * completion.  Must not be called prior to completion.  The @a ds is
  * freed as part of this call.
  *
  * @param ds directory scanner structure