X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_fs_service.h;h=4b1b1b1993e5fec0190119eb534d2cdd3fff6cd6;hb=d583ad46d4babd962f362deac20fa5aa6cdce7c7;hp=6ce4b6d11ef1ef0d8800332c54d26102ba0ece68;hpb=013778533273494f054ec1aa6084fe72d9d1e1c7;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h index 6ce4b6d11..4b1b1b199 100644 --- a/src/include/gnunet_fs_service.h +++ b/src/include/gnunet_fs_service.h @@ -4,7 +4,7 @@ GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your + by the Free Software Foundation; either version 3, or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but @@ -19,12 +19,8 @@ */ /** * @file include/gnunet_fs_service.h - * @brief API for file-sharing via GNUnet + * @brief API for file-sharing via GNUnet * @author Christian Grothoff - * - * TODO: - * - extend API with support for publish simulation (-s) - * and URI-argument binding to keyword/namespace (-u) */ #ifndef GNUNET_FS_LIB_H #define GNUNET_FS_LIB_H @@ -57,7 +53,7 @@ extern "C" * 6.1.x: with simplified namespace support * 9.0.0: CPS-style integrated API */ -#define GNUNET_FS_VERSION 0x00090000 +#define GNUNET_FS_VERSION 0x00090001 /* ******************** URI API *********************** */ @@ -83,9 +79,8 @@ struct GNUNET_FS_Uri; * @param is_mandatory is the keyword mandatory (in a search) * @return GNUNET_OK to continue to iterate, GNUNET_SYSERR to abort */ -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 @@ -94,9 +89,8 @@ typedef int (*GNUNET_FS_KeywordIterator) (void *cls, * @param uri uri to convert to a unique key * @param key wherer to store the unique key */ -void -GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, - GNUNET_HashCode * key); +void +GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, GNUNET_HashCode * key); /** * Convert a URI to a UTF-8 String. @@ -111,13 +105,38 @@ 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. * @@ -126,15 +145,14 @@ GNUNET_FS_uri_ksk_to_string_fancy (const struct GNUNET_FS_Uri *uri); * @return NULL on error */ struct GNUNET_FS_Uri * -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); @@ -144,7 +162,7 @@ GNUNET_FS_uri_destroy (struct GNUNET_FS_Uri *uri); * @param uri ksk uri to get the number of keywords from * @return 0 if this is not a keyword URI */ -unsigned int +unsigned int GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri); @@ -157,10 +175,10 @@ GNUNET_FS_uri_ksk_get_keyword_count (const struct GNUNET_FS_Uri *uri); * @return -1 if this is not a keyword URI, otherwise number of * keywords iterated over until iterator aborted */ -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); /** @@ -172,7 +190,7 @@ GNUNET_FS_uri_ksk_get_keywords (const struct GNUNET_FS_Uri *uri, */ int GNUNET_FS_uri_loc_get_peer_identity (const struct GNUNET_FS_Uri *uri, - struct GNUNET_PeerIdentity * peer); + struct GNUNET_PeerIdentity *peer); /** @@ -205,26 +223,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 @@ -232,7 +236,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); /** @@ -263,8 +267,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); /** @@ -285,8 +288,7 @@ GNUNET_FS_uri_ksk_create (const char *keywords, * if keywords is not legal (i.e. empty). */ struct GNUNET_FS_Uri * -GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, - const char **argv); +GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, const char **argv); /** @@ -296,9 +298,9 @@ GNUNET_FS_uri_ksk_create_from_args (unsigned int argc, * @param u2 the other URI * @return GNUNET_YES if the URIs are equal */ -int +int GNUNET_FS_uri_test_equal (const struct GNUNET_FS_Uri *u1, - const struct GNUNET_FS_Uri *u2); + const struct GNUNET_FS_Uri *u2); /** @@ -311,6 +313,36 @@ 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. + * + * @param ns namespace + * @param id identifier + * @param emsg where to store an error message + * @return an FS URI for the given namespace and identifier + */ +struct GNUNET_FS_Uri * +GNUNET_FS_uri_sks_create (struct GNUNET_FS_Namespace *ns, const char *id, + char **emsg); + + +/** + * Create an SKS URI from a namespace ID and an identifier. + * + * @param nsid namespace ID + * @param id identifier + * @return an FS URI for the given namespace and identifier + */ +struct GNUNET_FS_Uri * +GNUNET_FS_uri_sks_create_from_nsid (GNUNET_HashCode * nsid, const char *id); + + /** * Get the ID of a namespace from the given * namespace URI. @@ -319,9 +351,9 @@ GNUNET_FS_uri_test_sks (const struct GNUNET_FS_Uri *uri); * @param nsid where to store the ID of the namespace * @return GNUNET_OK on success */ -int +int GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri, - GNUNET_HashCode * nsid); + GNUNET_HashCode * nsid); /** @@ -344,7 +376,7 @@ GNUNET_FS_uri_sks_get_content_id (const struct GNUNET_FS_Uri *uri); */ char * GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg, - const struct GNUNET_FS_Uri *uri); + const struct GNUNET_FS_Uri *uri); /** @@ -353,7 +385,7 @@ GNUNET_FS_uri_sks_to_string_fancy (struct GNUNET_CONFIGURATION_Handle *cfg, * @param uri the uri * @return GNUNET_YES if this is a KSK uri */ -int +int GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri); @@ -363,7 +395,7 @@ GNUNET_FS_uri_test_ksk (const struct GNUNET_FS_Uri *uri); * @param uri the uri to check * @return GNUNET_YES if this is a CHK uri */ -int +int GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri); @@ -374,7 +406,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); @@ -384,7 +416,7 @@ GNUNET_FS_uri_chk_get_file_size (const struct GNUNET_FS_Uri *uri); * @param uri the uri to check * @return GNUNET_YES if this is a LOC uri */ -int +int GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri); @@ -397,7 +429,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 *********************** */ @@ -415,10 +448,9 @@ GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData * @return GNUNET_OK on success */ int -GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext* ctx, - void *scls, - const char *option, - const char *value); +GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext + *ctx, void *scls, const char *option, + const char *value); /** @@ -434,10 +466,9 @@ GNUNET_FS_getopt_set_keywords (struct GNUNET_GETOPT_CommandLineProcessorContext* * @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); @@ -445,13 +476,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. */ @@ -460,206 +491,219 @@ 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 = 14, + + /** + * Notification that this download is no longer actively + * being pursued (back in the queue). + */ + GNUNET_FS_STATUS_DOWNLOAD_INACTIVE = 15, + + /** + * Notification that this download is no longer part of a + * recursive download or search but now a 'stand-alone' + * download (and may thus need to be moved in the GUI + * into a different category). + */ + GNUNET_FS_STATUS_DOWNLOAD_LOST_PARENT = 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, - - /** - * Event generated for each search result - * when the respective search is suspended. - */ - GNUNET_FS_STATUS_SEARCH_SUSPEND_RESULT, + 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 = 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 }; -/** - * Handle to one of our namespaces. - */ -struct GNUNET_FS_Namespace; - - /** * Handle for controlling an upload. */ @@ -678,6 +722,14 @@ struct GNUNET_FS_UnindexContext; struct GNUNET_FS_SearchContext; +/** + * Result from a search. Opaque handle to refer to the search + * (typically used when starting a download associated with the search + * result). + */ +struct GNUNET_FS_SearchResult; + + /** * Context for controlling a download. */ @@ -697,22 +749,24 @@ 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. */ - struct GNUNET_FS_PublishContext *sc; + struct GNUNET_FS_PublishContext *pc; /** * Information about the file that is being publishd. @@ -735,11 +789,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; @@ -748,7 +802,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; /** @@ -770,92 +824,96 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { + union + { - /** + /** * These values are only valid for * 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. */ - struct { - - /** + 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. */ - 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. */ - 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. @@ -874,7 +932,15 @@ struct GNUNET_FS_ProgressInfo * (if this is a file in a directory or a subdirectory). */ void *pctx; - + + /** + * Client context pointer for the associated search operation + * (specifically, context pointer for the specific search + * result, not the overall search); only set if this + * download was started from a search result. + */ + void *sctx; + /** * URI used for this download. */ @@ -884,7 +950,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 @@ -896,12 +962,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; /** @@ -914,85 +980,101 @@ struct GNUNET_FS_ProgressInfo */ uint32_t anonymity; + /** + * Is the download currently active. + */ + int is_active; + /** * Additional values for specific events. */ - union { - - /** + union + { + + /** * These values are only valid for * GNUNET_FS_STATUS_DOWNLOAD_PROGRESS events. */ - struct { - - /** - * Data block we just obtained. + struct + { + + /** + * Data block we just obtained, can be NULL (even if + * data_len > 0) if we found the entire block 'intact' on + * disk. In this case, it is also possible for 'data_len' + * to be larger than an individual (32k) block. */ - const void *data; - - /** + const void *data; + + /** * At what offset in the file is "data"? */ - 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; + /** + * How much trust did we offer for downloading this block? + */ + unsigned int trust_offered; - /** + } progress; + + /** * These values are only valid for * 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. */ - 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. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; - } error; + } error; } specifics; @@ -1001,7 +1083,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_SEARCH_*" events. */ - struct { + struct + { /** * Context for controlling the search, NULL for @@ -1022,8 +1105,10 @@ struct GNUNET_FS_ProgressInfo /** * Client parent-context pointer; NULL for top-level searches, - * non-NULL for automatically triggered searches for updates in - * namespaces. + * refers to the client context of the associated search result + * for automatically triggered searches for updates in + * namespaces. In this case, 'presult' refers to that search + * result. */ void *pctx; @@ -1048,227 +1133,252 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { - - /** + union + { + + /** * These values are only valid for * 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; + + /** + * Applicability rank (the larger, the better the result + * fits the search criteria). + */ + uint32_t applicability_rank; + + } result; - } result; - - /** + /** * These values are only valid for * 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; - /** + /** * 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 availabiliy_certainty; + uint32_t availability_certainty; - /** + /** * Updated applicability rank (the larger, * the better the result fits the search * criteria). */ - uint32_t applicabiliy_rank; - - } resume_result; - - /** + uint32_t applicability_rank; + + } resume_result; + + /** * These values are only valid for * GNUNET_FS_STATUS_SEARCH_UPDATE events. */ - 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; - - /** + } update; + + /** * These values are only valid for * GNUNET_FS_STATUS_SEARCH_RESULT_SUSPEND events. * These events are automatically triggered for - * each search result before the + * 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. * These events are automatically triggered for - * each search result before the + * 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. */ - 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. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; + + } error; - } error; - - /** + /** * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events. */ - struct { - - /** + struct + { + + /** * Handle to the namespace (NULL if it is not a local * namespace). */ - struct GNUNET_FS_Namespace *ns; - - /** + struct GNUNET_FS_Namespace *ns; + + /** * Short, human-readable name of the namespace. */ - 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; - - /** + const struct GNUNET_CONTAINER_MetaData *meta; + + /** * Hash-identifier for the namespace. */ - GNUNET_HashCode id; - - } namespace; + GNUNET_HashCode id; + + } namespace; } specifics; @@ -1277,7 +1387,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events. */ - struct { + struct + { /** * Context for controlling the unindexing. @@ -1305,7 +1416,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; /** @@ -1322,64 +1433,66 @@ struct GNUNET_FS_ProgressInfo /** * Additional values for specific events. */ - union { + union + { - /** + /** * These values are only valid for * 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. */ - 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. */ - struct { + struct + { - /** + /** * Error message. */ - const char *message; + const char *message; - } error; + } error; } specifics; @@ -1389,16 +1502,16 @@ struct GNUNET_FS_ProgressInfo /** * Specific status code (determines the event type). - */ + */ enum GNUNET_FS_Status status; }; /** - * 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 @@ -1410,49 +1523,133 @@ struct GNUNET_FS_ProgressInfo * will be passed to future callbacks in the respective * field in the GNUNET_FS_ProgressInfo struct. */ -typedef void* (*GNUNET_FS_ProgressCallback) - (void *cls, - const struct GNUNET_FS_ProgressInfo *info); +typedef void *(*GNUNET_FS_ProgressCallback) (void *cls, + const struct GNUNET_FS_ProgressInfo + * info); /** * General (global) option flags for file-sharing. */ enum GNUNET_FS_Flags - { +{ /** * No special flags set. */ - GNUNET_FS_FLAGS_NONE = 0, + GNUNET_FS_FLAGS_NONE = 0, /** * Is persistence of operations desired? * (will create SUSPEND/RESUME events). */ - GNUNET_FS_FLAGS_PERSISTENCE = 1 + GNUNET_FS_FLAGS_PERSISTENCE = 1, - }; + /** + * Should we automatically trigger probes for search results + * to determine availability? + * (will create GNUNET_FS_STATUS_SEARCH_UPDATE events). + */ + GNUNET_FS_FLAGS_DO_PROBES = 2 +}; /** - * Options specified in the VARARGs - * portion of GNUNET_FS_start. + * Options specified in the VARARGs portion of GNUNET_FS_start. */ enum GNUNET_FS_OPTIONS - { - +{ + /** * Last option in the VARARG list. */ - GNUNET_FS_OPTIONS_END = 0, + GNUNET_FS_OPTIONS_END = 0, /** * Select the desired amount of parallelism (this option should be * followed by an "unsigned int" giving the desired maximum number * of parallel downloads). */ - GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1 + GNUNET_FS_OPTIONS_DOWNLOAD_PARALLELISM = 1, + + /** + * Maximum number of requests that should be pending at a given + * point in time (invidivual downloads may go above this, but + * if we are above this threshold, we should not activate any + * additional downloads. + */ + GNUNET_FS_OPTIONS_REQUEST_PARALLELISM = 2 +}; + + +/** + * Settings for publishing a block (which may of course also + * apply to an entire directory or file). + */ +struct GNUNET_FS_BlockOptions +{ + + /** + * At what time should the block expire? Data blocks (DBLOCKS and + * IBLOCKS) may still be used even if they are expired (however, + * they'd be removed quickly from the datastore if we are short on + * space), all other types of blocks will no longer be returned + * after they expire. + */ + struct GNUNET_TIME_Absolute expiration_time; + + /** + * At which anonymity level should the block be shared? + * (0: no anonymity, 1: normal GAP, >1: with cover traffic). + */ + uint32_t anonymity_level; + + /** + * How important is it for us to store the block? If we run + * out of space, the highest-priority, non-expired blocks will + * be kept. + */ + uint32_t content_priority; + + /** + * How often should we try to migrate the block to other peers? + * Only used if "CONTENT_PUSHING" is set to YES, in which case we + * first push each block to other peers according to their + * replication levels. Once each block has been pushed that many + * times to other peers, blocks are chosen for migration at random. + * Naturally, there is no guarantee that the other peers will keep + * these blocks for any period of time (since they won't have any + * priority or might be too busy to even store the block in the + * first place). + */ + uint32_t replication_level; - }; +}; + + +/** + * Return the current year (i.e. '2011'). + */ +unsigned int +GNUNET_FS_get_current_year (void); + + +/** + * Convert a year to an expiration time of January 1st of that year. + * + * @param year a year (after 1970, please ;-)). + * @return absolute time for January 1st of that year. + */ +struct GNUNET_TIME_Absolute +GNUNET_FS_year_to_time (unsigned int year); + + +/** + * 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); /** @@ -1464,9 +1661,8 @@ 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 flags specific attributes for fs-operations @@ -1474,13 +1670,9 @@ struct GNUNET_FS_Handle; * @return NULL on error */ struct GNUNET_FS_Handle * -GNUNET_FS_start (struct GNUNET_SCHEDULER_Handle *sched, - const struct GNUNET_CONFIGURATION_Handle *cfg, - const char *client_name, - GNUNET_FS_ProgressCallback upcb, - void *upcb_cls, - enum GNUNET_FS_Flags flags, - ...); +GNUNET_FS_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *client_name, GNUNET_FS_ProgressCallback upcb, + void *upcb_cls, enum GNUNET_FS_Flags flags, ...); /** @@ -1489,9 +1681,24 @@ 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); + */ +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); /** @@ -1502,33 +1709,24 @@ GNUNET_FS_stop (struct GNUNET_FS_Handle *h); * @param length length of the file or directory * @param meta metadata for the file or directory (can be modified) * @param uri pointer to the keywords that will be used for this entry (can be modified) - * @param anonymity pointer to selected anonymity level (can be modified) - * @param priority pointer to selected priority (can be modified) - * @param expirationTime pointer to selected expiration time (can be modified) + * @param bo block options (can be modified) + * @param do_index should we index (can be modified) * @param client_info pointer to client context set upon creation (can be modified) * @return GNUNET_OK to continue, GNUNET_NO to remove * this entry from the directory, GNUNET_SYSERR * to abort the iteration */ -typedef int (*GNUNET_FS_FileInformationProcessor)(void *cls, - struct GNUNET_FS_FileInformation *fi, - uint64_t length, - struct GNUNET_CONTAINER_MetaData *meta, - struct GNUNET_FS_Uri **uri, - uint32_t *anonymity, - uint32_t *priority, - struct GNUNET_TIME_Absolute *expirationTime, - void **client_info); - - -/** - * Recover file information structure from disk. - * - * @param fn filename for the structure on disk - * @return NULL on error - */ -struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_recover (const char *fn); +typedef int (*GNUNET_FS_FileInformationProcessor) (void *cls, + struct + GNUNET_FS_FileInformation * + fi, uint64_t length, + struct + GNUNET_CONTAINER_MetaData * + meta, + struct GNUNET_FS_Uri ** uri, + struct GNUNET_FS_BlockOptions + * bo, int *do_index, + void **client_info); /** @@ -1545,48 +1743,39 @@ const char * GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s); -/** - * Synchronize this file-information struct with its mirror - * on disk. Note that all internal FS-operations that change - * file information data should already call "sync" internally, - * so this function is likely not useful for clients. - * - * @param fi the struct to sync - */ -void -GNUNET_FS_file_information_sync (struct GNUNET_FS_FileInformation *f); - /** * Create an entry for a file in a publish-structure. * + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param filename name of the file or directory to publish * @param keywords under which keywords should this file be available * directly; can be NULL * @param meta metadata for the file * @param do_index GNUNET_YES for index, GNUNET_NO for insertion, * GNUNET_SYSERR for simulation - * @param anonymity what is the desired anonymity level for sharing? - * @param priority what is the priority for OUR node to - * keep this file available? Use 0 for maximum anonymity and - * minimum reliability... - * @param expirationTime when should this content expire? + * @param bo block options * @return publish structure entry for the file */ struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_create_from_file (void *client_info, - const char *filename, - const struct GNUNET_FS_Uri *keywords, - const struct GNUNET_CONTAINER_MetaData *meta, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); +GNUNET_FS_file_information_create_from_file (struct GNUNET_FS_Handle *h, + void *client_info, + const char *filename, + const struct GNUNET_FS_Uri + *keywords, + const struct + GNUNET_CONTAINER_MetaData *meta, + int do_index, + const struct GNUNET_FS_BlockOptions + *bo); /** * Create an entry for a file in a publish-structure. * + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param length length of the file * @param data data for the file (should not be used afterwards by * the caller; callee will "free") @@ -1595,23 +1784,20 @@ GNUNET_FS_file_information_create_from_file (void *client_info, * @param meta metadata for the file * @param do_index GNUNET_YES for index, GNUNET_NO for insertion, * GNUNET_SYSERR for simulation - * @param anonymity what is the desired anonymity level for sharing? - * @param priority what is the priority for OUR node to - * keep this file available? Use 0 for maximum anonymity and - * minimum reliability... - * @param expirationTime when should this content expire? + * @param bo block options * @return publish structure entry for the file */ struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_create_from_data (void *client_info, - uint64_t length, - void *data, - const struct GNUNET_FS_Uri *keywords, - const struct GNUNET_CONTAINER_MetaData *meta, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); +GNUNET_FS_file_information_create_from_data (struct GNUNET_FS_Handle *h, + void *client_info, uint64_t length, + void *data, + const struct GNUNET_FS_Uri + *keywords, + const struct + GNUNET_CONTAINER_MetaData *meta, + int do_index, + const struct GNUNET_FS_BlockOptions + *bo); /** @@ -1621,7 +1807,7 @@ GNUNET_FS_file_information_create_from_data (void *client_info, * @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 + * @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 @@ -1630,42 +1816,39 @@ GNUNET_FS_file_information_create_from_data (void *client_info, * @param emsg location for the reader to store an error message * @return number of bytes written, usually "max", 0 on error */ -typedef size_t (*GNUNET_FS_DataReader)(void *cls, - uint64_t offset, - size_t max, - void *buf, - char **emsg); +typedef size_t (*GNUNET_FS_DataReader) (void *cls, uint64_t offset, size_t max, + void *buf, char **emsg); /** * Create an entry for a file in a publish-structure. * + * @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 function that can be used to obtain the data for the file * @param reader_cls closure for "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 bo block options * @return publish structure entry for the file */ struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_create_from_reader (void *client_info, - uint64_t length, - GNUNET_FS_DataReader reader, - void *reader_cls, - const struct GNUNET_FS_Uri *keywords, - const struct GNUNET_CONTAINER_MetaData *meta, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); +GNUNET_FS_file_information_create_from_reader (struct GNUNET_FS_Handle *h, + void *client_info, + uint64_t length, + GNUNET_FS_DataReader reader, + void *reader_cls, + const struct GNUNET_FS_Uri + *keywords, + const struct + GNUNET_CONTAINER_MetaData *meta, + int do_index, + const struct + GNUNET_FS_BlockOptions *bo); /** @@ -1673,39 +1856,34 @@ GNUNET_FS_file_information_create_from_reader (void *client_info, * for each entry in the directory. * * @param cls closure - * @param filename name of the file (including path); must end + * @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); +typedef void (*GNUNET_FS_FileProcessor) (void *cls, const char *filename, + struct GNUNET_FS_FileInformation * fi); /** * Type of a function that will be used to scan a directory. - * + * * @param cls closure + * @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 bo block options * @param proc function to call on each entry * @param proc_cls closure for proc * @param emsg where to store an error message (on errors) * @return GNUNET_OK on success */ -typedef int (*GNUNET_FS_DirectoryScanner)(void *cls, - const char *dirname, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime, - GNUNET_FS_FileProcessor proc, - void *proc_cls, - char **emsg); +typedef int (*GNUNET_FS_DirectoryScanner) (void *cls, + struct GNUNET_FS_Handle * h, + const char *dirname, int do_index, + const struct GNUNET_FS_BlockOptions * + bo, GNUNET_FS_FileProcessor proc, + void *proc_cls, char **emsg); @@ -1716,31 +1894,28 @@ typedef int (*GNUNET_FS_DirectoryScanner)(void *cls, * 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. + * extraction. Keywords will be derived from the metadata and + * associated with directories as appropriate. This is strictly a + * convenience function (however, if all tools use it, there will + * be less of a chance of distinguishing users by the specific + * user-interface they were using). * * @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 bo block options * @param proc function called on each entry * @param proc_cls closure for proc * @param emsg where to store an error message (on errors) * @return GNUNET_OK on success */ int -GNUNET_FS_directory_scanner_default (void *cls, - const char *dirname, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime, - GNUNET_FS_FileProcessor proc, - void *proc_cls, - char **emsg); +GNUNET_FS_directory_scanner_default (void *cls, struct GNUNET_FS_Handle *h, + const char *dirname, int do_index, + const struct GNUNET_FS_BlockOptions *bo, + GNUNET_FS_FileProcessor proc, + void *proc_cls, char **emsg); /** @@ -1753,28 +1928,26 @@ GNUNET_FS_directory_scanner_default (void *cls, * passed (GNUNET_FS_directory_scanner_default). This is strictly a * convenience function. * + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param filename name of the top-level file or directory * @param scanner function used to get a list of files in a directory * @param scanner_cls closure for scanner * @param do_index should files in the hierarchy be indexed? - * @param anonymity what is the desired anonymity level for sharing? - * @param priority what is the priority for OUR node to - * keep this file available? Use 0 for maximum anonymity and - * minimum reliability... - * @param expirationTime when should this content expire? + * @param bo block options * @param emsg where to store an error message * @return publish structure entry for the directory, NULL on error */ struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_create_from_directory (void *client_info, - const char *filename, - GNUNET_FS_DirectoryScanner scanner, - void *scanner_cls, - int do_index, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime, - char **emsg); +GNUNET_FS_file_information_create_from_directory (struct GNUNET_FS_Handle *h, + void *client_info, + const char *filename, + GNUNET_FS_DirectoryScanner + scanner, void *scanner_cls, + int do_index, + const struct + GNUNET_FS_BlockOptions *bo, + char **emsg); /** @@ -1783,23 +1956,35 @@ GNUNET_FS_file_information_create_from_directory (void *client_info, * use of "GNUNET_FS_file_information_create_from_directory" * is not appropriate. * - * @param meta metadata for the directory + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param keywords under which keywords should this directory be available * directly; can be NULL - * @param anonymity what is the desired anonymity level for sharing? - * @param priority what is the priority for OUR node to - * keep this file available? Use 0 for maximum anonymity and - * minimum reliability... - * @param expirationTime when should this content expire? + * @param meta metadata for the directory + * @param bo block options * @return publish structure entry for the directory , NULL on error */ struct GNUNET_FS_FileInformation * -GNUNET_FS_file_information_create_empty_directory (void *client_info, - const struct GNUNET_CONTAINER_MetaData *meta, - const struct GNUNET_FS_Uri *keywords, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expirationTime); +GNUNET_FS_file_information_create_empty_directory (struct GNUNET_FS_Handle *h, + void *client_info, + const struct GNUNET_FS_Uri + *keywords, + const struct + GNUNET_CONTAINER_MetaData + *meta, + const struct + GNUNET_FS_BlockOptions *bo); + + +/** + * Test if a given entry represents a directory. + * + * @param ent check if this FI represents a directory + * @return GNUNET_YES if so, GNUNET_NO if not + */ +int +GNUNET_FS_file_information_is_directory (const struct GNUNET_FS_FileInformation + *ent); /** @@ -1809,13 +1994,13 @@ GNUNET_FS_file_information_create_empty_directory (void *client_info, * * @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 + * 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 */ int GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir, - struct GNUNET_FS_FileInformation *ent); + struct GNUNET_FS_FileInformation *ent); /** @@ -1834,8 +2019,8 @@ GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir, */ void GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir, - GNUNET_FS_FileInformationProcessor proc, - void *proc_cls); + GNUNET_FS_FileInformationProcessor proc, + void *proc_cls); /** @@ -1850,27 +2035,27 @@ GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir, */ 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 - { +enum GNUNET_FS_PublishOptions +{ /** * No options (use defaults for everything). */ - GNUNET_FS_PUBLISH_OPTION_NONE = 0, - + GNUNET_FS_PUBLISH_OPTION_NONE = 0, + /** * Simulate publishing. With this option, no data will be stored * in the datastore. Useful for computing URIs from files. */ - GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1 - }; + GNUNET_FS_PUBLISH_OPTION_SIMULATE_ONLY = 1 +}; /** * Publish a file or directory. @@ -1880,30 +2065,29 @@ enum GNUNET_FS_PublishOptions * @param namespace 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, - const char *nid, - const char *nuid, - enum GNUNET_FS_PublishOptions options); + struct GNUNET_FS_FileInformation *fi, + struct GNUNET_FS_Namespace *namespace, const char *nid, + const char *nuid, + enum GNUNET_FS_PublishOptions options); /** - * Stop an upload. Will abort incomplete uploads (but - * not remove blocks that have already been publishd) or - * simply clean up the state for completed uploads. + * Stop a publication. Will abort incomplete publications (but + * not remove blocks that have already been published) or + * simply clean up the state for completed publications. * Must NOT be called from within the event callback! * - * @param sc context for the upload to stop + * @param pc context for the publication to stop */ -void -GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *sc); +void +GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc); /** @@ -1914,10 +2098,10 @@ GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *sc); * @param uri URI under which the block is now available, NULL on error * @param emsg error message, NULL on success */ -typedef void (*GNUNET_FS_PublishContinuation)(void *cls, - const struct GNUNET_FS_Uri *uri, - const char *emsg); - +typedef void (*GNUNET_FS_PublishContinuation) (void *cls, + const struct GNUNET_FS_Uri * uri, + const char *emsg); + /** * Publish a KBlock on GNUnet. @@ -1926,23 +2110,19 @@ typedef void (*GNUNET_FS_PublishContinuation)(void *cls, * @param ksk_uri keywords to use * @param meta metadata to use * @param uri URI to refer to in the KBlock - * @param expirationTime when the KBlock expires - * @param anonymity anonymity level for the KBlock - * @param priority priority for the KBlock + * @param bo block options + * @param options publication options * @param cont continuation * @param cont_cls closure for cont */ void GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_Uri *ksk_uri, - struct GNUNET_CONTAINER_MetaData *meta, - struct GNUNET_FS_Uri *uri, - struct GNUNET_TIME_Absolute expirationTime, - uint32_t anonymity, - uint32_t priority, - enum GNUNET_FS_PublishOptions options, - GNUNET_FS_PublishContinuation cont, - void *cont_cls); + const struct GNUNET_FS_Uri *ksk_uri, + const struct GNUNET_CONTAINER_MetaData *meta, + const struct GNUNET_FS_Uri *uri, + const struct GNUNET_FS_BlockOptions *bo, + enum GNUNET_FS_PublishOptions options, + GNUNET_FS_PublishContinuation cont, void *cont_cls); /** @@ -1954,25 +2134,20 @@ GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h, * @param update update identifier to use * @param meta metadata to use * @param uri URI to refer to in the SBlock - * @param expirationTime when the SBlock expires - * @param anonymity anonymity level for the SBlock - * @param priority priority for the SBlock + * @param bo block options + * @param options publication options * @param cont continuation * @param cont_cls closure for cont */ void GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_Namespace *namespace, - const char *identifier, - const char *update, - struct GNUNET_CONTAINER_MetaData *meta, - struct GNUNET_FS_Uri *uri, - struct GNUNET_TIME_Absolute expirationTime, - uint32_t anonymity, - uint32_t priority, - enum GNUNET_FS_PublishOptions options, - GNUNET_FS_PublishContinuation cont, - void *cont_cls); + struct GNUNET_FS_Namespace *namespace, + const char *identifier, const char *update, + const struct GNUNET_CONTAINER_MetaData *meta, + const struct GNUNET_FS_Uri *uri, + const struct GNUNET_FS_BlockOptions *bo, + enum GNUNET_FS_PublishOptions options, + GNUNET_FS_PublishContinuation cont, void *cont_cls); /** @@ -1983,9 +2158,8 @@ GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h, * @param file_id hash of the contents of the indexed file * @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort */ -typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, - const char *filename, - const GNUNET_HashCode *file_id); +typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename, + const GNUNET_HashCode * file_id); /** @@ -1999,12 +2173,11 @@ typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, * error) or "PREREQ_DONE" (on success) * @param cont_cls closure for cont */ -void +void GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, - GNUNET_FS_IndexedFileProcessor iterator, - void *iterator_cls, - GNUNET_SCHEDULER_Task cont, - void *cont_cls); + GNUNET_FS_IndexedFileProcessor iterator, + void *iterator_cls, GNUNET_SCHEDULER_Task cont, + void *cont_cls); /** @@ -2013,12 +2186,11 @@ GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, * @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 + * @return NULL on error, otherwise handle */ struct GNUNET_FS_UnindexContext * -GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, - const char *filename, - void *cctx); +GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, const char *filename, + void *cctx); /** @@ -2031,30 +2203,26 @@ GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc); /** - * Publish an advertismement for a namespace. + * 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 advertisementURI the keyword (!) URI to advertise the - * namespace under (we will create a GNUNET_EC_KNBlock) - * @param rootEntry name of the root entry in the namespace (for - * the namespace advertisement) - * - * @return uri of the advertisement + * @param bo block options + * @param rootEntry name of the root of the namespace + * @param cont continuation + * @param cont_cls closure for cont */ -struct GNUNET_FS_Uri * +void GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h, - struct GNUNET_FS_Namespace *namespace, - const struct GNUNET_CONTAINER_MetaData *meta, - uint32_t anonymity, - uint32_t priority, - struct GNUNET_TIME_Absolute expiration, - const struct GNUNET_FS_Uri *advertisementURI, - const char *rootEntry); + struct GNUNET_FS_Uri *ksk_uri, + struct GNUNET_FS_Namespace *namespace, + const struct GNUNET_CONTAINER_MetaData *meta, + const struct GNUNET_FS_BlockOptions *bo, + const char *rootEntry, + GNUNET_FS_PublishContinuation cont, + void *cont_cls); /** @@ -2066,8 +2234,7 @@ GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h, * @return handle to the namespace, NULL on error */ struct GNUNET_FS_Namespace * -GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, - const char *name); +GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, const char *name); /** @@ -2081,9 +2248,8 @@ GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, * * @return GNUNET_OK on success, GNUNET_SYSERR on error */ -int -GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, - int freeze); +int +GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, int freeze); /** @@ -2095,9 +2261,8 @@ GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, * @param name human-readable identifier of the namespace * @param id hash identifier for the namespace */ -typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, - const char *name, - const GNUNET_HashCode *id); +typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, const char *name, + const GNUNET_HashCode * id); /** @@ -2109,41 +2274,71 @@ typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, * @param cb function to call on each known namespace * @param cb_cls closure for cb */ -void +void GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h, - GNUNET_FS_NamespaceInfoProcessor cb, - void *cb_cls); + GNUNET_FS_NamespaceInfoProcessor cb, void *cb_cls); /** * Function called on updateable identifiers. * * @param cls closure - * @param last_id last identifier + * @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 next_id identifier that should be used for updates */ -typedef void -(*GNUNET_FS_IdentifierProcessor)(void *cls, - const char *last_id, - const struct GNUNET_FS_Uri *last_uri, - const struct GNUNET_CONTAINER_MetaData *last_meta, - const char *next_id); +typedef void (*GNUNET_FS_IdentifierProcessor) (void *cls, const char *last_id, + const struct GNUNET_FS_Uri * + last_uri, + const struct + GNUNET_CONTAINER_MetaData * + last_meta, const char *next_id); /** - * List all of the identifiers in the namespace for - * which we could produce an update. + * List all of the identifiers in the namespace for which we could + * produce an update. Namespace updates form a graph where each node + * has a name. Each node can have any number of URI/meta-data entries + * which can each be linked to other nodes. Cycles are possible. + * + * Calling this function with "next_id" NULL will cause the library to + * call "ip" with a root for each strongly connected component of the + * graph (a root being a node from which all other nodes in the Scc + * are reachable). + * + * Calling this function with "next_id" being the name of a node will + * cause the library to call "ip" with all children of the node. Note + * that cycles within an SCC are possible (including self-loops). * * @param namespace namespace to inspect for updateable content + * @param next_id ID to look for; use NULL to look for SCC roots * @param ip function to call on each updateable identifier * @param ip_cls closure for ip */ void GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace, - GNUNET_FS_IdentifierProcessor ip, - void *ip_cls); + const char *next_id, + GNUNET_FS_IdentifierProcessor ip, + void *ip_cls); + + +/** + * Options for searching. Compatible options + * can be OR'ed together. + */ +enum GNUNET_FS_SearchOptions +{ + /** + * No options (use defaults for everything). + */ + GNUNET_FS_SEARCH_OPTION_NONE = 0, + + /** + * Only search the local host, do not search remote systems (no P2P) + */ + GNUNET_FS_SEARCH_OPTION_LOOPBACK_ONLY = 1 +}; /** @@ -2153,21 +2348,22 @@ GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace, * @param uri specifies the search parameters; can be * a KSK URI or an SKS URI. * @param anonymity desired level of anonymity + * @param options options for the search + * @param cctx initial value for the client context * @return context that can be used to control the search */ -// FIXME: add a "void *" context for the client to arguments!? struct GNUNET_FS_SearchContext * GNUNET_FS_search_start (struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - uint32_t anonymity); + const struct GNUNET_FS_Uri *uri, uint32_t anonymity, + enum GNUNET_FS_SearchOptions options, void *cctx); /** - * 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); @@ -2176,7 +2372,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); @@ -2185,7 +2381,7 @@ 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); @@ -2195,26 +2391,39 @@ GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc); * Options for downloading. Compatible options * can be OR'ed together. */ -enum GNUNET_FS_DownloadOptions - { +enum GNUNET_FS_DownloadOptions +{ /** * No options (use defaults for everything). */ - GNUNET_FS_DOWNLOAD_OPTION_NONE = 0, - + GNUNET_FS_DOWNLOAD_OPTION_NONE = 0, + + /** + * Only download from the local host, do not access remote systems (no P2P) + */ + GNUNET_FS_DOWNLOAD_OPTION_LOOPBACK_ONLY = 1, + /** * Do a recursive download (that is, automatically trigger the * download of files in directories). */ - GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 1, + GNUNET_FS_DOWNLOAD_OPTION_RECURSIVE = 2, /** * Do not append temporary data to * the target file (for the IBlocks). */ - GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 2 + GNUNET_FS_DOWNLOAD_NO_TEMPORARIES = 4, - }; + /** + * Internal option used to flag this download as a 'probe' for a + * search result. Impacts the priority with which the download is + * run and causes signalling callbacks to be done differently. + * Also, probe downloads are not serialized on suspension. Normal + * clients should not use this! + */ + GNUNET_FS_DOWNLOAD_IS_PROBE = (1 << 31) +}; @@ -2235,6 +2444,10 @@ enum GNUNET_FS_DownloadOptions * @param meta known metadata for the file (can be NULL) * @param filename where to store the file, maybe NULL (then no file is * created on disk and data must be grabbed from the callbacks) + * @param tempname where to store temporary file data, not used if filename is non-NULL; + * can be NULL (in which case we will pick a name if needed); the temporary file + * may already exist, in which case we will try to use the data that is there and + * if it is not what is desired, will overwrite it * @param offset at what offset should we start the download (typically 0) * @param length how many bytes should be downloaded starting at offset * @param anonymity anonymity level to use for the download @@ -2246,86 +2459,66 @@ 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, - uint64_t offset, - uint64_t length, - uint32_t anonymity, - enum GNUNET_FS_DownloadOptions options, - void *cctx, - struct GNUNET_FS_DownloadContext *parent); - - -/** - * Stop a download (aborts if download is incomplete). - * - * @param dc handle for the download - * @param do_delete delete files of incomplete downloads - */ -void -GNUNET_FS_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); + 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); /** - * Stop collection. + * Download parts of a file based on a search result. The download + * will be associated with the search result (and the association + * will be preserved when serializing/deserializing the state). + * If the search is stopped, the download will not be aborted but + * be 'promoted' to a stand-alone download. * - * @param h handle to the file sharing subsystem - * @return GNUNET_OK on success, GNUNET_SYSERR if no collection is active - */ -int -GNUNET_FS_collection_stop (struct GNUNET_FS_Handle *h); - - -/** - * Are we using a collection? + * As with the other download function, this will store + * the blocks at the respective offset in the given file. Also, the + * download is still using the blocking of the underlying FS + * encoding. As a result, the download may *write* outside of the + * given boundaries (if offset and length do not match the 32k FS + * block boundaries).

* - * @param h handle to the file sharing subsystem - * @return NULL if there is no collection, - */ -struct GNUNET_FS_Namespace * -GNUNET_FS_collection_get(struct GNUNET_FS_Handle *h); - - -/** - * Publish an update of the current collection information to the - * network now. The function has no effect if the collection has not - * changed since the last publication. If we are currently not - * collecting, this function does nothing. + * The given range can be used to focus a download towards a + * particular portion of the file (optimization), not to strictly + * limit the download to exactly those bytes. * * @param h handle to the file sharing subsystem + * @param sr the search result to use for the download (determines uri and + * meta data and associations) + * @param filename where to store the file, maybe NULL (then no file is + * created on disk and data must be grabbed from the callbacks) + * @param tempname where to store temporary file data, not used if filename is non-NULL; + * can be NULL (in which case we will pick a name if needed); the temporary file + * may already exist, in which case we will try to use the data that is there and + * if it is not what is desired, will overwrite it + * @param offset at what offset should we start the download (typically 0) + * @param length how many bytes should be downloaded starting at offset + * @param anonymity anonymity level to use for the download + * @param options various download options + * @param cctx initial value for the client context for this download + * @return context that can be used to control this download */ -void GNUNET_FS_collection_publish (struct GNUNET_FS_Handle *h); +struct GNUNET_FS_DownloadContext * +GNUNET_FS_download_start_from_search (struct GNUNET_FS_Handle *h, + struct GNUNET_FS_SearchResult *sr, + const char *filename, + const char *tempname, uint64_t offset, + uint64_t length, uint32_t anonymity, + enum GNUNET_FS_DownloadOptions options, + void *cctx); /** - * If we are currently building a collection, publish the given file - * information in that collection. If we are currently not - * collecting, this function does nothing. + * Stop a download (aborts if download is incomplete). * - * @param h handle to the file sharing subsystem - * @param uri uri to add to the collection - * @param meta metadata for the uri + * @param dc handle for the download + * @param do_delete delete files of incomplete downloads */ -void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - const struct GNUNET_CONTAINER_MetaData *meta); - - +void +GNUNET_FS_download_stop (struct GNUNET_FS_DownloadContext *dc, int do_delete); @@ -2343,20 +2536,32 @@ void GNUNET_FS_collection_add (const struct GNUNET_FS_Handle *h, * @return GNUNET_YES if it is, GNUNET_NO if it is not, GNUNET_SYSERR if * we have no mime-type information (treat as 'GNUNET_NO') */ -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 GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md); +/** + * Suggest a filename based on given metadata. + * + * @param md given meta data + * @return NULL if meta data is useless for suggesting a filename + */ +char * +GNUNET_FS_meta_data_suggest_filename (const struct GNUNET_CONTAINER_MetaData + *md); + + /** * Function used to process entries in a directory. * @@ -2372,12 +2577,14 @@ GNUNET_FS_meta_data_make_directory (struct GNUNET_CONTAINER_MetaData *md); * embedded with the directory itself). * @param data data available for the file (length bytes) */ -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); /** @@ -2395,13 +2602,15 @@ typedef void (*GNUNET_FS_DirectoryEntryProcessor)(void *cls, * @param offset offset of data in the directory * @param dep function to call on each entry * @param dep_cls closure for dep + * @return GNUNET_OK if this could be a block in a directory, + * GNUNET_NO if this could be part of a directory (but not 100% OK) + * GNUNET_SYSERR if 'data' does not represent a directory */ -void -GNUNET_FS_directory_list_contents (size_t size, - const void *data, - uint64_t offset, - GNUNET_FS_DirectoryEntryProcessor dep, - void *dep_cls); +int +GNUNET_FS_directory_list_contents (size_t size, const void *data, + uint64_t offset, + GNUNET_FS_DirectoryEntryProcessor dep, + void *dep_cls); /** @@ -2411,16 +2620,17 @@ 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 @@ -2430,10 +2640,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 @@ -2447,8 +2657,7 @@ GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld, */ int GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld, - size_t *rsize, - void **rdata); + size_t * rsize, void **rdata); #if 0 /* keep Emacsens' auto-indent happy */