X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_fs_service.h;h=f50166d326279aaf29ad458d4f1d583f00275a02;hb=27c12911f4f2aba2d90099270d70de846e83854f;hp=a0425c9a1b3a92f9296a1008df7feae6e19e7e58;hpb=38b29592cf2e8b816cab68579e07e2477153f739;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h index a0425c9a1..f50166d32 100644 --- a/src/include/gnunet_fs_service.h +++ b/src/include/gnunet_fs_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2004, 2005, 2006, 2007, 2008, 2009 Christian Grothoff (and other contributing authors) + (C) 2004--2013 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -19,7 +19,7 @@ */ /** * @file include/gnunet_fs_service.h - * @brief API for file-sharing via GNUnet + * @brief API for file-sharing via GNUnet * @author Christian Grothoff */ #ifndef GNUNET_FS_LIB_H @@ -52,8 +52,10 @@ extern "C" * 6.0.0: with support for OR in KSKs * 6.1.x: with simplified namespace support * 9.0.0: CPS-style integrated API + * 9.1.1: asynchronous directory scanning + * 9.2.0: unified K-Block and S-block format (#2564) */ -#define GNUNET_FS_VERSION 0x00090000 +#define GNUNET_FS_VERSION 0x00090200 /* ******************** URI API *********************** */ @@ -65,6 +67,12 @@ extern "C" #define GNUNET_FS_URI_LOC_INFIX "loc/" +/** + * How often do we signal applications that a probe for a particular + * search result is running? (used to visualize probes). + */ +#define GNUNET_FS_PROBE_UPDATE_FREQUENCY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MILLISECONDS, 250) + /** * A Universal Resource Identifier (URI), opaque. */ @@ -77,11 +85,12 @@ 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); +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 @@ -90,9 +99,10 @@ typedef int (*GNUNET_FS_KeywordIterator) (void *cls, * @param uri uri to convert to a unique key * @param key wherer to store the unique key */ -void +void GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, - GNUNET_HashCode * key); + struct GNUNET_HashCode *key); + /** * Convert a URI to a UTF-8 String. @@ -103,17 +113,44 @@ GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, char * GNUNET_FS_uri_to_string (const struct GNUNET_FS_Uri *uri); + /** * Convert keyword URI to a human readable format * (i.e. the search query that was used in the first place) * - * @param uri ksk uri to convert to a string + * @param uri ksk uri to convert to a string * @return string with the keywords */ char * 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. * @@ -122,15 +159,15 @@ GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *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 */ -void +void GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri); @@ -140,7 +177,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 */ -unsigned int +unsigned int GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri); @@ -149,14 +186,14 @@ 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 */ -int +int 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); /** @@ -164,11 +201,11 @@ 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, - struct GNUNET_PeerIdentity * peer); + struct GNUNET_PeerIdentity *peer); /** @@ -201,26 +238,12 @@ 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_CONFIGURATION_Handle *cfg, - struct GNUNET_TIME_Absolute expiration_time); - - -/** - * Canonicalize keyword URI. Performs operations such - * as decapitalization and removal of certain characters. - * (useful for search). - * - * @param uri the URI to canonicalize - * @return canonicalized version of the URI, NULL on error - */ -struct GNUNET_FS_Uri * -GNUNET_FS_uri_ksk_canonicalize (const struct GNUNET_FS_Uri *uri); + const struct GNUNET_CONFIGURATION_Handle *cfg, + struct GNUNET_TIME_Absolute expiration_time); /** * Merge the sets of keywords from two KSK URIs. - * (useful for merging the canonicalized keywords with - * the original keywords for sharing). * * @param u1 first uri * @param u2 second uri @@ -228,7 +251,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, - const struct GNUNET_FS_Uri *u2); + const struct GNUNET_FS_Uri *u2); /** @@ -259,8 +282,7 @@ GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *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); /** @@ -290,54 +312,46 @@ GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, * * @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 +int GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1, - const struct GNUNET_FS_Uri *u2); + const struct GNUNET_FS_Uri *u2); /** * 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); /** - * Handle to one of our namespaces. - */ -struct GNUNET_FS_Namespace; - - -/** - * Create an SKS URI from a namespace and an identifier. + * Create an SKS URI from a namespace ID and an identifier. * - * @param ns namespace + * @param ns pseudonym to use * @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); +GNUNET_FS_uri_sks_create (const struct GNUNET_CRYPTO_EcdsaPublicKey *ns, + const char *id); /** - * Get the ID of a namespace from the given + * Get the public key of a namespace from the given * namespace URI. * * @param uri the uri to get the namespace ID from - * @param nsid where to store the ID of the namespace - * @return GNUNET_OK on success + * @param pseudonym where to store the public key of the namespace + * @return #GNUNET_OK on success */ -int +int GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri, - GNUNET_HashCode * nsid); + struct GNUNET_CRYPTO_EcdsaPublicKey *pseudonym); /** @@ -350,26 +364,13 @@ 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 +int GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri); @@ -377,9 +378,9 @@ 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 +int GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri); @@ -390,7 +391,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 */ -uint64_t +uint64_t GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri); @@ -398,9 +399,9 @@ 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 +int GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri); @@ -413,7 +414,8 @@ GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *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 *********************** */ @@ -428,13 +430,12 @@ 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* 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); /** @@ -444,16 +445,15 @@ 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* 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); @@ -461,13 +461,13 @@ GNUNET_FS_getopt_set_metadata (struct GNUNET_GETOPT_CommandLineProcessorContext* /** - * Possible status codes used in the callback for the + * Possible status codes used in the callback for the * various file-sharing operations. On each file (or search), * the callback is guaranteed to be called once with "START" * and once with STOPPED; calls with PROGRESS, ERROR or COMPLETED * are optional and depend on the circumstances; parent operations * will be STARTED before child-operations and STOPPED after - * their respective child-operations. START and STOP signals + * their respective child-operations. START and STOP signals * are typically generated either due to explicit client requests * or because of suspend/resume operations. */ @@ -476,93 +476,93 @@ enum GNUNET_FS_Status /** * Notification that we have started to publish a file structure. */ - GNUNET_FS_STATUS_PUBLISH_START, + GNUNET_FS_STATUS_PUBLISH_START = 0, /** * Notification that we have resumed sharing a file structure. */ - GNUNET_FS_STATUS_PUBLISH_RESUME, + GNUNET_FS_STATUS_PUBLISH_RESUME = 1, /** * Notification that we have suspended sharing a file structure. */ - GNUNET_FS_STATUS_PUBLISH_SUSPEND, + GNUNET_FS_STATUS_PUBLISH_SUSPEND = 2, /** * Notification that we are making progress sharing a file structure. */ - GNUNET_FS_STATUS_PUBLISH_PROGRESS, + GNUNET_FS_STATUS_PUBLISH_PROGRESS = 3, /** * Notification that an error was encountered sharing a file structure. * The application will continue to receive resume/suspend events for * this structure until "GNUNET_FS_publish_stop" is called. */ - GNUNET_FS_STATUS_PUBLISH_ERROR, + GNUNET_FS_STATUS_PUBLISH_ERROR = 4, /** * Notification that we completed sharing a file structure. * The application will continue to receive resume/suspend events for * this structure until "GNUNET_FS_publish_stop" is called. */ - GNUNET_FS_STATUS_PUBLISH_COMPLETED, + GNUNET_FS_STATUS_PUBLISH_COMPLETED = 5, /** * Notification that we have stopped * the process of uploading a file structure; no * futher events will be generated for this action. */ - GNUNET_FS_STATUS_PUBLISH_STOPPED, + GNUNET_FS_STATUS_PUBLISH_STOPPED = 6, /** * Notification that we have started this download. */ - GNUNET_FS_STATUS_DOWNLOAD_START, + GNUNET_FS_STATUS_DOWNLOAD_START = 7, /** * Notification that this download is being resumed. */ - GNUNET_FS_STATUS_DOWNLOAD_RESUME, + GNUNET_FS_STATUS_DOWNLOAD_RESUME = 8, /** * Notification that this download was suspended. */ - GNUNET_FS_STATUS_DOWNLOAD_SUSPEND, + GNUNET_FS_STATUS_DOWNLOAD_SUSPEND = 9, /** * Notification about progress with this download. */ - GNUNET_FS_STATUS_DOWNLOAD_PROGRESS, + GNUNET_FS_STATUS_DOWNLOAD_PROGRESS = 10, /** * Notification that this download encountered an error. */ - GNUNET_FS_STATUS_DOWNLOAD_ERROR, + GNUNET_FS_STATUS_DOWNLOAD_ERROR = 11, /** * Notification that this download completed. Note that for * directories, completion does not imply completion of all files in * the directory. */ - GNUNET_FS_STATUS_DOWNLOAD_COMPLETED, + GNUNET_FS_STATUS_DOWNLOAD_COMPLETED = 12, /** * Notification that this download was stopped * (final event with respect to this action). */ - GNUNET_FS_STATUS_DOWNLOAD_STOPPED, + GNUNET_FS_STATUS_DOWNLOAD_STOPPED = 13, /** * Notification that this download is now actively being * pursued (as opposed to waiting in the queue). */ - GNUNET_FS_STATUS_DOWNLOAD_ACTIVE, + GNUNET_FS_STATUS_DOWNLOAD_ACTIVE = 14, /** * Notification that this download is no longer actively * being pursued (back in the queue). */ - GNUNET_FS_STATUS_DOWNLOAD_INACTIVE, + GNUNET_FS_STATUS_DOWNLOAD_INACTIVE = 15, /** * Notification that this download is no longer part of a @@ -570,122 +570,127 @@ enum GNUNET_FS_Status * download (and may thus need to be moved in the GUI * into a different category). */ - GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT, + GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT = 16, /** - * First event generated when a client requests + * First event generated when a client requests * a search to begin or when a namespace result * automatically triggers the search for updates. */ - GNUNET_FS_STATUS_SEARCH_START, + GNUNET_FS_STATUS_SEARCH_START = 17, /** * Last event when a search is being resumed; * note that "GNUNET_FS_SEARCH_START" will not * be generated in this case. */ - GNUNET_FS_STATUS_SEARCH_RESUME, + GNUNET_FS_STATUS_SEARCH_RESUME = 18, /** * Event generated for each search result * when the respective search is resumed. */ - GNUNET_FS_STATUS_SEARCH_RESUME_RESULT, + GNUNET_FS_STATUS_SEARCH_RESUME_RESULT = 19, /** * Last event when a search is being suspended; * note that "GNUNET_FS_SEARCH_STOPPED" will not * be generated in this case. */ - GNUNET_FS_STATUS_SEARCH_SUSPEND, - + GNUNET_FS_STATUS_SEARCH_SUSPEND = 20, + /** * This search has yielded a result. */ - GNUNET_FS_STATUS_SEARCH_RESULT, + GNUNET_FS_STATUS_SEARCH_RESULT = 21, /** * We have discovered a new namespace. */ - GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE, + GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE = 22, /** * We have additional data about the quality * or availability of a search result. */ - GNUNET_FS_STATUS_SEARCH_UPDATE, + GNUNET_FS_STATUS_SEARCH_UPDATE = 23, /** * Signals a problem with this search. */ - GNUNET_FS_STATUS_SEARCH_ERROR, + GNUNET_FS_STATUS_SEARCH_ERROR = 24, /** * Signals that this search was paused. */ - GNUNET_FS_STATUS_SEARCH_PAUSED, + GNUNET_FS_STATUS_SEARCH_PAUSED = 25, /** * Signals that this search was continued (unpaused). */ - GNUNET_FS_STATUS_SEARCH_CONTINUED, + GNUNET_FS_STATUS_SEARCH_CONTINUED = 26, /** * Event generated for each search result * when the respective search is stopped. */ - GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED, + GNUNET_FS_STATUS_SEARCH_RESULT_STOPPED = 27, /** * Event generated for each search result * when the respective search is suspended. */ - GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND, + GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND = 28, /** * Last message from a search; this signals * that there will be no further events associated * with this search. */ - GNUNET_FS_STATUS_SEARCH_STOPPED, + GNUNET_FS_STATUS_SEARCH_STOPPED = 29, /** * Notification that we started to unindex a file. - */ - GNUNET_FS_STATUS_UNINDEX_START, + */ + GNUNET_FS_STATUS_UNINDEX_START = 30, /** * Notification that we resumed unindexing of a file. */ - GNUNET_FS_STATUS_UNINDEX_RESUME, + GNUNET_FS_STATUS_UNINDEX_RESUME = 31, /** * Notification that we suspended unindexing a file. */ - GNUNET_FS_STATUS_UNINDEX_SUSPEND, + GNUNET_FS_STATUS_UNINDEX_SUSPEND = 32, /** * Notification that we made progress unindexing a file. */ - GNUNET_FS_STATUS_UNINDEX_PROGRESS, + GNUNET_FS_STATUS_UNINDEX_PROGRESS = 33, /** * Notification that we encountered an error unindexing * a file. */ - GNUNET_FS_STATUS_UNINDEX_ERROR, + GNUNET_FS_STATUS_UNINDEX_ERROR = 34, /** * Notification that the unindexing of this file * was completed. */ - GNUNET_FS_STATUS_UNINDEX_COMPLETED, + GNUNET_FS_STATUS_UNINDEX_COMPLETED = 35, /** * Notification that the unindexing of this file * was stopped (final event for this action). */ - GNUNET_FS_STATUS_UNINDEX_STOPPED + GNUNET_FS_STATUS_UNINDEX_STOPPED = 36, + + /** + * Notification that we are making progress sharing a directory. + */ + GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY = 37 }; @@ -735,17 +740,19 @@ struct GNUNET_FS_FileInformation; * information about what is going on. */ struct GNUNET_FS_ProgressInfo -{ +{ /** * Values that depend on the event type. */ - union { - + union + { + /** * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events. */ - struct { + struct + { /** * Context for controlling the upload. @@ -773,11 +780,11 @@ struct GNUNET_FS_ProgressInfo * 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, - * not of the other files contained within the + * not of the other files contained within the * directory. */ uint64_t size; @@ -786,7 +793,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). - */ + */ struct GNUNET_TIME_Relative eta; /** @@ -808,92 +815,123 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { + union + { - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_PUBLISH_PROGRESS events. + * #GNUNET_FS_STATUS_PUBLISH_PROGRESS events. */ - struct { - - /** + struct + { + + /** * Data block we just published. */ - const void *data; - - /** + const void *data; + + /** * At what offset in the file is "data"? */ - uint64_t offset; - - /** + uint64_t offset; + + /** * Length of the data block. */ - uint64_t data_len; + uint64_t data_len; - /** - * 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). + /** + * Depth of the given block in the tree; + * 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. + * #GNUNET_FS_STATUS_PUBLISH_PROGRESS_DIRECTORY events. */ - struct { - - /** + 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 + { + + /** * 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) */ - 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. + * #GNUNET_FS_STATUS_PUBLISH_COMPLETED events. */ - struct { - - /** + struct + { + + /** * 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. + * #GNUNET_FS_STATUS_PUBLISH_ERROR events. */ - struct { - - /** + struct + { + + /** * Error message, never NULL. */ - const char *message; + const char *message; - } error; + } error; } specifics; } publish; - + /** * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events. */ - struct { + struct + { /** * Context for controlling the download. @@ -916,11 +954,11 @@ struct GNUNET_FS_ProgressInfo /** * Client context pointer for the associated search operation * (specifically, context pointer for the specific search - * result, not the overall search); only set if this + * result, not the overall search); only set if this * download was started from a search result. */ void *sctx; - + /** * URI used for this download. */ @@ -930,7 +968,7 @@ struct GNUNET_FS_ProgressInfo * 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 @@ -942,12 +980,12 @@ struct GNUNET_FS_ProgressInfo * 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 duration; /** @@ -968,82 +1006,110 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { - - /** + union + { + + /** * These values are only valid for - * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events. + * #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"? */ - uint64_t offset; - - /** + uint64_t offset; + + /** * Length of the data block. */ - uint64_t data_len; + uint64_t data_len; - /** - * 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). + /** + * How much time passed between us asking for this block and + * actually getting it? #GNUNET_TIME_UNIT_FOREVER_REL if unknown. + */ + struct GNUNET_TIME_Relative block_download_duration; + + /** + * Depth of the given block in the tree; + * 0 would be the lowest level (DBLOCKS). + */ + unsigned int depth; + + /** + * How much respect did we offer for downloading this block? (estimate, + * because we might have the same request pending for multiple clients, + * and of course because a transmission may have failed at a lower + * layer). */ - unsigned int depth; + uint32_t respect_offered; - } progress; + /** + * How often did we transmit the request? (estimate, + * because we might have the same request pending for multiple clients, + * and of course because a transmission may have failed at a lower + * layer). + */ + uint32_t num_transmissions; + + } progress; - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_DOWNLOAD_START events. + * #GNUNET_FS_STATUS_DOWNLOAD_START events. */ - struct { + struct + { - /** + /** * 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. + * #GNUNET_FS_STATUS_DOWNLOAD_RESUME events. */ - struct { + struct + { - /** + /** * 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. */ - const char *message; + const char *message; - } resume; + } resume; - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_DOWNLOAD_ERROR events. + * #GNUNET_FS_STATUS_DOWNLOAD_ERROR events. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; - } error; + } error; } specifics; @@ -1052,7 +1118,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_SEARCH_*" events. */ - struct { + struct + { /** * Context for controlling the search, NULL for @@ -1101,243 +1168,251 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { - - /** + union + { + + /** * These values are only valid for - * GNUNET_FS_STATUS_SEARCH_RESULT events. + * #GNUNET_FS_STATUS_SEARCH_RESULT events. */ - struct { - - /** + struct + { + + /** * Metadata for the search result. */ - const struct GNUNET_CONTAINER_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - /** + /** * 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; + struct GNUNET_FS_SearchResult *result; - /** + /** * Applicability rank (the larger, the better the result * fits the search criteria). */ - uint32_t applicability_rank; + uint32_t applicability_rank; + + } result; - } result; - - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events. + * #GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events. */ - struct { - - /** + struct + { + + /** * Metadata for the search result. */ - const struct GNUNET_CONTAINER_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - /** + /** * 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; + struct GNUNET_FS_SearchResult *result; - /** + /** * 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? */ - uint32_t availability_certainty; + uint32_t availability_certainty; - /** + /** * Updated applicability rank (the larger, * the better the result fits the search * criteria). */ - uint32_t applicability_rank; - - } resume_result; - - /** + uint32_t applicability_rank; + + } resume_result; + + /** * These values are only valid for - * GNUNET_FS_STATUS_SEARCH_UPDATE events. + * #GNUNET_FS_STATUS_SEARCH_UPDATE events. */ - struct { + struct + { - /** + /** * Private context set for for this result * during the "RESULT" event. */ - void *cctx; - - /** + void *cctx; + + /** * Metadata for the search result. */ - const struct GNUNET_CONTAINER_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - /** + /** * URI for the search result. */ - const struct GNUNET_FS_Uri *uri; + const struct GNUNET_FS_Uri *uri; - /** + /** * 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? */ - uint32_t availability_certainty; + uint32_t availability_certainty; - /** + /** * Updated applicability rank (the larger, * the better the result fits the search * criteria). */ - uint32_t applicability_rank; + uint32_t applicability_rank; - } update; - - /** + /** + * How long has the current probe been active? + */ + struct GNUNET_TIME_Relative current_probe_time; + + } update; + + /** * 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 + * each search result before the + * #GNUNET_FS_STATUS_SEARCH_SUSPEND event. This * 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. */ - void *cctx; - - /** + void *cctx; + + /** * Metadata for the search result. */ - const struct GNUNET_CONTAINER_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - /** + /** * 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. + * #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 + * each search result before the + * #GNUNET_FS_STATUS_SEARCH_STOPPED event. This * 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. */ - void *cctx; - - /** + void *cctx; + + /** * Metadata for the search result. */ - const struct GNUNET_CONTAINER_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - /** + /** * 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. + * #GNUNET_FS_STATUS_SEARCH_RESUME events. */ - struct { + struct + { - /** + /** * Error message, NULL if we have not encountered any error yet. */ - const char *message; + const char *message; - /** + /** * 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. + * #GNUNET_FS_STATUS_SEARCH_ERROR events. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; - } error; - - /** - * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events. + } error; + + /** + * Values for #GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE events. */ - struct { - - /** - * Handle to the namespace (NULL if it is not a local - * namespace). - */ - struct GNUNET_FS_Namespace *ns; - - /** + struct + { + + /** * Short, human-readable name of the namespace. */ - const char *name; - - /** + const char *name; + + /** * Root identifier for the namespace, can be NULL. */ - const char *root; - - /** + const char *root; + + /** * Metadata for the namespace. */ - const struct GNUNET_CONTAINER_MetaData *meta; - - /** - * Hash-identifier for the namespace. + const struct GNUNET_CONTAINER_MetaData *meta; + + /** + * Public key of the namespace. */ - GNUNET_HashCode id; - - } namespace; + struct GNUNET_CRYPTO_EcdsaPublicKey pseudonym; + + } ns; } specifics; @@ -1346,7 +1421,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events. */ - struct { + struct + { /** * Context for controlling the unindexing. @@ -1374,7 +1450,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). - */ + */ struct GNUNET_TIME_Relative eta; /** @@ -1391,64 +1467,66 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { + union + { - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_UNINDEX_PROGRESS events. + * #GNUNET_FS_STATUS_UNINDEX_PROGRESS events. */ - struct { - - /** + struct + { + + /** * Data block we just unindexed. */ - const void *data; - - /** + const void *data; + + /** * At what offset in the file is "data"? */ - uint64_t offset; - - /** + uint64_t offset; + + /** * Length of the data block. */ - uint64_t data_len; + uint64_t data_len; - /** - * 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). + /** + * Depth of the given block in the tree; + * 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. + * #GNUNET_FS_STATUS_UNINDEX_RESUME events. */ - struct { + struct + { - /** + /** * 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. + * #GNUNET_FS_STATUS_UNINDEX_ERROR events. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; - } error; + } error; } specifics; @@ -1458,16 +1536,20 @@ struct GNUNET_FS_ProgressInfo /** * Specific status code (determines the event type). - */ + */ enum GNUNET_FS_Status status; + /** + * File-sharing handle that generated the event. + */ + struct GNUNET_FS_Handle *fsh; }; /** - * Notification of FS to a client about the progress of an + * Notification of FS to a client about the progress of an * operation. Callbacks of this type will be used for uploads, - * downloads and searches. Some of the arguments depend a bit + * downloads and searches. Some of the arguments depend a bit * in their meaning on the context in which the callback is used. * * @param cls closure @@ -1477,65 +1559,108 @@ 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); +typedef void *(*GNUNET_FS_ProgressCallback) (void *cls, + const struct GNUNET_FS_ProgressInfo *info); /** * General (global) option flags for file-sharing. */ enum GNUNET_FS_Flags - { - /** - * No special flags set. - */ - GNUNET_FS_FLAGS_NONE = 0, +{ + /** + * No special flags set. + */ + GNUNET_FS_FLAGS_NONE = 0, - /** - * Is persistence of operations desired? - * (will create SUSPEND/RESUME events). - */ - GNUNET_FS_FLAGS_PERSISTENCE = 1, + /** + * 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). - */ - GNUNET_FS_FLAGS_DO_PROBES = 2 + /** + * 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. */ enum GNUNET_FS_OPTIONS - { - - /** - * Last option in the VARARG list. - */ - 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). - */ - GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1, + /** + * Last option in the VARARG list. + */ + GNUNET_FS_OPTIONS_END = 0, - /** - * 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 + /** + * 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, + + /** + * 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; + +}; /** @@ -1547,23 +1672,18 @@ struct GNUNET_FS_Handle; /** * 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 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 * -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, ...); /** @@ -1572,55 +1692,37 @@ GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched, * called after this function returns. * * @param h handle that was returned from GNUNET_FS_start - */ -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); +void +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 * @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 bo block options (can be modified) * @param do_index should we index (can be modified) - * @param expirationTime pointer to selected expiration time (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, - struct GNUNET_FS_FileInformation *fi, - uint64_t length, - struct GNUNET_CONTAINER_MetaData *meta, - struct GNUNET_FS_Uri **uri, - uint32_t *anonymity, - uint32_t *priority, - int *do_index, - struct GNUNET_TIME_Absolute *expirationTime, - void **client_info); +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); /** @@ -1629,14 +1731,35 @@ 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 * GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s); +/** + * Obtain the filename from the file information structure. + * + * @param s structure to get the filename for + * @return "filename" field of the structure (can be NULL) + */ +const char * +GNUNET_FS_file_information_get_filename (struct GNUNET_FS_FileInformation *s); + + +/** + * Set the filename in the file information structure. + * If filename was already set, frees it before setting the new one. + * Makes a copy of the argument. + * + * @param s structure to get the filename for + * @param filename filename to set + */ +void +GNUNET_FS_file_information_set_filename (struct GNUNET_FS_FileInformation *s, + const char *filename); + /** * Create an entry for a file in a publish-structure. @@ -1647,25 +1770,22 @@ GNUNET_FS_file_information_get_id (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 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 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 */ struct GNUNET_FS_FileInformation * 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, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); + 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); /** @@ -1679,26 +1799,22 @@ 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 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 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 */ struct GNUNET_FS_FileInformation * 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, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); + 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); /** @@ -1707,21 +1823,22 @@ GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h, * @param cls closure * @param offset offset to read from; it is possible * that the caller might need to go backwards - * a bit at times - * @param max maximum number of bytes that should be + * a bit at times; set to UINT64_MAX to tell + * the reader that we won't be reading for a while + * (used to close the file descriptor but NOT fully + * clean up the reader's state); in this case, + * a value of '0' for max should be ignored + * @param max maximum number of bytes that should be * copied to buf; readers are not allowed * to provide less data unless there is an error; * a value of "0" will be used at the end to allow * 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); +typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max, + void *buf, char **emsg); /** @@ -1730,289 +1847,169 @@ typedef size_t (*GNUNET_FS_DataReader)(void *cls, * @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 reader function that can be used to obtain the data for the file + * @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 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 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 */ struct GNUNET_FS_FileInformation * 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, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); - - -/** - * Function that a "GNUNET_FS_DirectoryScanner" should call - * for each entry in the directory. - * - * @param cls closure - * @param filename name of the file (including path); must end - * in a "/" (even on W32) if this is a directory - * @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); + 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); /** - * 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 anonymity desired anonymity level - * @param priority priority for publishing - * @param expirationTime expiration for publication - * @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, - struct GNUNET_FS_Handle *h, - 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); - - - -/** - * Simple, useful default implementation of a directory scanner - * (GNUNET_FS_DirectoryScanner). This implementation expects to get a - * UNIX filename, will publish all files in the directory except hidden - * files (those starting with a "."). Metadata will be extracted - * using GNU libextractor; the specific list of plugins should be - * specified in "cls", passing NULL will disable (!) metadata - * extraction. Keywords will be derived from the metadata and be - * subject to default canonicalization. This is strictly a - * 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 anonymity desired anonymity level - * @param priority priority for publishing - * @param expirationTime expiration for publication - * @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, - struct GNUNET_FS_Handle *h, - 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); - - -/** - * Create a publish-structure from an existing file hierarchy, inferring - * and organizing keywords and metadata as much as possible. This - * function primarily performs the recursive build and re-organizes - * keywords and metadata; for automatically getting metadata - * extraction, scanning of directories and creation of the respective - * GNUNET_FS_FileInformation entries the default scanner should be - * passed (GNUNET_FS_directory_scanner_default). This is strictly a - * convenience function. + * Create an entry for an empty directory 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 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 emsg where to store an error message - * @return publish structure entry for the directory, NULL on error + * @param keywords under which keywords should this directory be available + * directly; can be NULL + * @param meta metadata for the directory + * @param bo block options + * @param filename name of the directory; can be NULL + * @return publish structure entry for the directory , NULL on error */ struct GNUNET_FS_FileInformation * -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, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime, - char **emsg); - - -/** - * 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 - * @param keywords under which keywords should this directory be available - * directly; can be NULL - * @param meta metadata for the directory - * @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? - * @return publish structure entry for the directory , NULL on error - */ -struct GNUNET_FS_FileInformation * -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, - 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, + const char *filename); /** * 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 (struct GNUNET_FS_FileInformation *ent); +GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation + *ent); /** * 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 + * added to any other directory at this point and + * 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, - struct GNUNET_FS_FileInformation *ent); + struct GNUNET_FS_FileInformation *ent); /** * 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, - GNUNET_FS_FileInformationProcessor proc, - void *proc_cls); + GNUNET_FS_FileInformationProcessor proc, + void *proc_cls); /** * 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, - GNUNET_FS_FileInformationProcessor cleaner, - void *cleaner_cls); + GNUNET_FS_FileInformationProcessor cleaner, + void *cleaner_cls); /** * Options for publishing. Compatible options * can be OR'ed together. */ -enum GNUNET_FS_PublishOptions - { - /** - * 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. - */ - GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1 - }; +enum GNUNET_FS_PublishOptions +{ + /** + * 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. + */ + GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1 +}; + /** * Publish a file or directory. * * @param h handle to the file sharing subsystem * @param fi information about the file or directory structure to publish - * @param namespace namespace to publish the file in, NULL for no namespace + * @param ns namespace to publish the file in, NULL for no namespace * @param nid identifier to use for the publishd content in the namespace * (can be NULL, must be NULL if namespace is NULL) - * @param nuid update-identifier that will be used for future updates + * @param nuid update-identifier that will be used for future updates * (can be NULL, must be NULL if namespace or nid is NULL) - * @param options options for the publication + * @param options options for the publication * @return context that can be used to control the publish operation */ struct GNUNET_FS_PublishContext * GNUNET_FS_publish_start (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_FileInformation *fi, - struct GNUNET_FS_Namespace *namespace, + struct GNUNET_FS_FileInformation *fi, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns, const char *nid, - const char *nuid, - enum GNUNET_FS_PublishOptions options); + const char *nuid, + enum GNUNET_FS_PublishOptions options); /** - * Stop a publication. Will abort incomplete publications (but + * 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 pc context for the publication to stop */ -void +void GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc); @@ -2024,10 +2021,16 @@ GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc); * @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); + + +/** + * Handle to cancel publish KSK operation. + */ +struct GNUNET_FS_PublishKskContext; + /** * Publish a KBlock on GNUnet. @@ -2036,243 +2039,198 @@ 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 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 + * @param cont_cls closure for @a cont + * @return NULL on error (@a cont will still be called) */ -void +struct GNUNET_FS_PublishKskContext * GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *ksk_uri, - const struct GNUNET_CONTAINER_MetaData *meta, - const 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); /** - * Publish an SBlock on GNUnet. + * Abort the KSK publishing operation. * - * @param h handle to the file sharing subsystem - * @param namespace namespace to publish in - * @param identifier identifier to use - * @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 cont continuation - * @param cont_cls closure for cont + * @param pkc context of the operation to abort. */ void -GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_Namespace *namespace, - const char *identifier, - const char *update, - const struct GNUNET_CONTAINER_MetaData *meta, - const 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); +GNUNET_FS_publish_ksk_cancel (struct GNUNET_FS_PublishKskContext *pkc); /** - * Type of a function called by "GNUNET_FS_get_indexed_files". - * - * @param cls closure - * @param filename the name of the file - * @param file_id hash of the contents of the indexed file - * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort + * Handle to cancel publish SKS operation. */ -typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, - const char *filename, - const GNUNET_HashCode *file_id); +struct GNUNET_FS_PublishSksContext; /** - * Iterate over all indexed files. + * Publish an SBlock on GNUnet. * * @param h handle to the file sharing subsystem - * @param iterator function to call on each indexed file - * @param iterator_cls closure for iterator - * @param cont continuation to call when done; - * reason should be "TIMEOUT" (on - * error) or "PREREQ_DONE" (on success) - * @param cont_cls closure for cont + * @param ns namespace to publish in + * @param identifier identifier to use + * @param update update identifier to use + * @param meta metadata to use + * @param uri URI to refer to in the SBlock + * @param bo block options + * @param options publication options + * @param cont continuation + * @param cont_cls closure for @a cont + * @return NULL on error (@a cont will still be called) */ -void -GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, - GNUNET_FS_IndexedFileProcessor iterator, - void *iterator_cls, - GNUNET_SCHEDULER_Task cont, - void *cont_cls); +struct GNUNET_FS_PublishSksContext * +GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h, + 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, + enum GNUNET_FS_PublishOptions options, + GNUNET_FS_PublishContinuation cont, void *cont_cls); /** - * Unindex a file. + * Abort the SKS publishing operation. * - * @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 + * @param psc context of the operation to abort. */ -struct GNUNET_FS_UnindexContext * -GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, - const char *filename, - void *cctx); +void +GNUNET_FS_publish_sks_cancel (struct GNUNET_FS_PublishSksContext *psc); /** - * Clean up after completion of an unindex operation. + * Type of a function called by #GNUNET_FS_get_indexed_files. * - * @param uc handle + * @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 */ -void -GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc); +typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename, + const struct GNUNET_HashCode * file_id); /** - * 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 anonymity for the namespace advertismement - * @param priority for the namespace advertisement - * @param expiration for the namespace advertisement - * @param rootEntry name of the root of the namespace - * @param cont continuation - * @param cont_cls closure for cont + * Handle to cancel 'GNUNET_FS_get_indexed_files'. */ -void -GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_Uri *ksk_uri, - struct GNUNET_FS_Namespace *namespace, - const struct GNUNET_CONTAINER_MetaData *meta, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expiration, - const char *rootEntry, - GNUNET_FS_PublishContinuation cont, - void *cont_cls); +struct GNUNET_FS_GetIndexedContext; /** - * Create a namespace with the given name; if one already - * exists, return a handle to the existing namespace. + * Iterate over all indexed files. * * @param h handle to the file sharing subsystem - * @param name name to use for the namespace - * @return handle to the namespace, NULL on error + * @param iterator function to call on each indexed file + * @param iterator_cls closure for @a iterator + * @return NULL on error (@a iterator is not called) */ -struct GNUNET_FS_Namespace * -GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, - const char *name); +struct GNUNET_FS_GetIndexedContext * +GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, + GNUNET_FS_IndexedFileProcessor iterator, + void *iterator_cls); /** - * Delete a namespace handle. Can be used for a clean shutdown (free - * memory) or also to freeze the namespace to prevent further - * insertions by anyone. + * Cancel iteration over all indexed files. * - * @param namespace handle to the namespace that should be deleted / freed - * @param freeze prevents future insertions; creating a namespace - * with the same name again will create a fresh namespace instead - * - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @param gic operation to cancel */ -int -GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, - int freeze); +void +GNUNET_FS_get_indexed_files_cancel (struct GNUNET_FS_GetIndexedContext *gic); /** - * Callback with information about local (!) namespaces. - * Contains the names of the local namespace and the global - * ID. + * Unindex a file. * - * @param cls closure - * @param name human-readable identifier of the namespace - * @param id hash identifier for the namespace + * @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 */ -typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, - const char *name, - const GNUNET_HashCode *id); +struct GNUNET_FS_UnindexContext * +GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, + const char *filename, + void *cctx); /** - * Build a list of all available local (!) namespaces The returned - * names are only the nicknames since we only iterate over the local - * namespaces. + * Clean up after completion of an unindex operation. * - * @param h handle to the file sharing subsystem - * @param cb function to call on each known namespace - * @param cb_cls closure for cb + * @param uc handle */ -void -GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h, - GNUNET_FS_NamespaceInfoProcessor cb, - void *cb_cls); +void +GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc); /** * Function called on updateable identifiers. * * @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_id last identifier + * @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); /** - * 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 @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). * - * @param namespace namespace to inspect for updateable content + * 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 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_Namespace *namespace, - GNUNET_FS_IdentifierProcessor ip, - void *ip_cls); +GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *ns, + 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 - { +enum GNUNET_FS_SearchOptions +{ /** * No options (use defaults for everything). */ - GNUNET_FS_SEARCH_OPTION_NONE = 0, + 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 - - }; + GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1 +}; /** @@ -2288,18 +2246,16 @@ enum GNUNET_FS_SearchOptions */ struct GNUNET_FS_SearchContext * GNUNET_FS_search_start (struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - uint32_t anonymity, - enum GNUNET_FS_SearchOptions options, - void *cctx); + const struct GNUNET_FS_Uri *uri, uint32_t anonymity, + enum GNUNET_FS_SearchOptions options, void *cctx); /** - * Pause search. + * Pause search. * * @param sc context for the search that should be paused */ -void +void GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc); @@ -2308,7 +2264,7 @@ GNUNET_FS_search_pause (struct GNUNET_FS_SearchContext *sc); * * @param sc context for the search that should be resumed */ -void +void GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc); @@ -2317,50 +2273,76 @@ GNUNET_FS_search_continue (struct GNUNET_FS_SearchContext *sc); * * @param sc context for the search that should be stopped */ -void +void GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc); +/** + * Start download probes for the given search result. + * + * @param h file-sharing handle to use for the operation + * @param uri URI to probe + * @param meta meta data associated with the URI + * @param client_info client info pointer to use for associated events + * @param anonymity anonymity level to use for the probes + * @return the search result handle to access the probe activity + */ +struct GNUNET_FS_SearchResult * +GNUNET_FS_probe (struct GNUNET_FS_Handle *h, + const struct GNUNET_FS_Uri *uri, + const struct GNUNET_CONTAINER_MetaData *meta, + void *client_info, + uint32_t anonymity); + + +/** + * Stop probe activity. Must ONLY be used on values + * returned from #GNUNET_FS_probe. + * + * @param sr search result to stop probing for (freed) + * @return the value of the 'client_info' pointer + */ +void * +GNUNET_FS_probe_stop (struct GNUNET_FS_SearchResult *sr); /** * Options for downloading. Compatible options * can be OR'ed together. */ -enum GNUNET_FS_DownloadOptions - { - /** - * No options (use defaults for everything). - */ - GNUNET_FS_DOWNLOAD_OPTION_NONE = 0, +enum GNUNET_FS_DownloadOptions +{ + /** + * 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) - */ - GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1, - - /** - * Do a recursive download (that is, automatically trigger the - * download of files in directories). - */ - GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2, + /** + * Only download from the local host, do not access remote systems (no P2P) + */ + GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1, - /** - * Do not append temporary data to - * the target file (for the IBlocks). - */ - GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4, + /** + * Do a recursive download (that is, automatically trigger the + * download of files in directories). + */ + GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2, - /** - * 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) + /** + * 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! + */ + GNUNET_FS_DOWNLOAD_IS_PROBE = (1 << 31) +}; @@ -2370,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).

+ * block boundaries). * * The given range can be used to focus a download towards a * particular portion of the file (optimization), not to strictly @@ -2396,16 +2378,12 @@ enum GNUNET_FS_DownloadOptions */ struct GNUNET_FS_DownloadContext * 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); + 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); /** @@ -2420,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).

+ * block boundaries). * * The given range can be used to focus a download towards a * particular portion of the file (optimization), not to strictly @@ -2444,14 +2422,12 @@ GNUNET_FS_download_start (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); + 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); /** @@ -2461,68 +2437,7 @@ GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h, * @param do_delete delete files of incomplete downloads */ void -GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, - int do_delete); - - -/** - * Initialize collection. - * - * @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? - * - * @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. - * - * @param h handle to the file sharing subsystem - */ -void GNUNET_FS_collection_publish (struct GNUNET_FS_Handle *h); - - -/** - * 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. - * - * @param h handle to the file sharing subsystem - * @param uri uri to add to the collection - * @param meta metadata for the uri - */ -void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - const struct GNUNET_CONTAINER_MetaData *meta); - - +GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete); @@ -2537,17 +2452,18 @@ void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h, * 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 *md); +int +GNUNET_FS_meta_data_test_for_directory (const struct GNUNET_CONTAINER_MetaData + *md); /** * Set the MIMETYPE information for the given * metadata to "application/gnunet-directory". - * + * * @param md metadata to add mimetype to */ void @@ -2556,7 +2472,7 @@ 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 */ @@ -2579,12 +2495,14 @@ GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData *md * 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); /** @@ -2601,17 +2519,16 @@ 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, - 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); /** @@ -2619,18 +2536,20 @@ GNUNET_FS_directory_list_contents (size_t size, */ struct GNUNET_FS_DirectoryBuilder; + /** * Create a directory builder. - * + * * @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); /** * Add an entry to a directory. - * + * * @param bld directory to extend * @param uri uri of the entry (must not be a KSK) * @param md metadata of the entry @@ -2640,10 +2559,10 @@ GNUNET_FS_directory_builder_create (const struct GNUNET_CONTAINER_MetaData *mdir */ 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 @@ -2653,12 +2572,197 @@ 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, - size_t *rsize, - void **rdata); + size_t * rsize, void **rdata); + + +/* ******************** DirScanner API *********************** */ + +/** + * Progress reasons of the directory scanner. + */ +enum GNUNET_FS_DirScannerProgressUpdateReason +{ + + /** + * We've started processing a file or directory. + */ + GNUNET_FS_DIRSCANNER_FILE_START = 0, + + /** + * We're having trouble accessing a file (soft-error); it will + * be ignored. + */ + GNUNET_FS_DIRSCANNER_FILE_IGNORED, + + /** + * We've found all files (in the pre-pass). + */ + GNUNET_FS_DIRSCANNER_ALL_COUNTED, + + /** + * We've finished extracting meta data from a file. + */ + GNUNET_FS_DIRSCANNER_EXTRACT_FINISHED, + + /** + * Last call to the progress function: we have finished scanning + * the directory. + */ + GNUNET_FS_DIRSCANNER_FINISHED, + + /** + * There was an internal error. Application should abort the scan. + */ + GNUNET_FS_DIRSCANNER_INTERNAL_ERROR + +}; + + +/** + * Function called over time as the directory scanner makes + * progress on the job at hand. + * + * @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 reason kind of progress we are making + */ +typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls, + const char *filename, + int is_directory, + enum GNUNET_FS_DirScannerProgressUpdateReason reason); + + +/** + * A node of a directory tree (produced by dirscanner) + */ +struct GNUNET_FS_ShareTreeItem +{ + /** + * This is a doubly-linked list + */ + struct GNUNET_FS_ShareTreeItem *prev; + + /** + * This is a doubly-linked list + */ + struct GNUNET_FS_ShareTreeItem *next; + + /** + * This is a doubly-linked tree + * NULL for top-level entries. + */ + struct GNUNET_FS_ShareTreeItem *parent; + + /** + * This is a doubly-linked tree + * NULL for files and empty directories + */ + struct GNUNET_FS_ShareTreeItem *children_head; + + /** + * This is a doubly-linked tree + * NULL for files and empty directories + */ + struct GNUNET_FS_ShareTreeItem *children_tail; + + /** + * Metadata for this file or directory + */ + struct GNUNET_CONTAINER_MetaData *meta; + + /** + * Keywords for this file or directory (derived from metadata). + */ + struct GNUNET_FS_Uri *ksk_uri; + + /** + * Name of the file/directory + */ + char *filename; + + /** + * Base name of the file/directory. + */ + char *short_filename; + + /** + * #GNUNET_YES if this is a directory + */ + int is_directory; + +}; + + +/** + * Opaqe handle to an asynchronous directory scanning activity. + */ +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 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 @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, + const char *ex, + GNUNET_FS_DirScannerProgressCallback cb, + void *cb_cls); + + +/** + * Abort the scan. Must not be called from within the progress_callback + * function. + * + * @param ds directory scanner structure + */ +void +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 @a ds is + * freed as part of this call. + * + * @param ds directory scanner structure + * @return the results of the scan (a directory tree) + */ +struct GNUNET_FS_ShareTreeItem * +GNUNET_FS_directory_scan_get_result (struct GNUNET_FS_DirScanner *ds); + + +/** + * Process a share item tree, moving frequent keywords up and + * copying frequent metadata up. + * + * @param toplevel toplevel directory in the tree, returned by the scanner + */ +void +GNUNET_FS_share_tree_trim (struct GNUNET_FS_ShareTreeItem *toplevel); + + +/** + * Release memory of a share item tree. + * + * @param toplevel toplevel of the tree to be freed + */ +void +GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel); #if 0 /* keep Emacsens' auto-indent happy */