X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_fs_service.h;h=4b1b1b1993e5fec0190119eb534d2cdd3fff6cd6;hb=d583ad46d4babd962f362deac20fa5aa6cdce7c7;hp=0f61bc764ca37e11b653483d72f6caf2a6d64e8e;hpb=0700c60ef320c8ccbd417833441697c64d6c525c;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h index 0f61bc764..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,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 @@ -53,16 +53,16 @@ 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 *********************** */ -#define GNUNET_FS_URI_PREFIX "gnunet://fs/" -#define GNUNET_FS_SEARCH_INFIX "ksk/" -#define GNUNET_FS_SUBSPACE_INFIX "sks/" -#define GNUNET_FS_FILE_INFIX "chk/" -#define GNUNET_FS_LOCATION_INFIX "loc/" +#define GNUNET_FS_URI_PREFIX "gnunet://fs/" +#define GNUNET_FS_URI_KSK_INFIX "ksk/" +#define GNUNET_FS_URI_SKS_INFIX "sks/" +#define GNUNET_FS_URI_CHK_INFIX "chk/" +#define GNUNET_FS_URI_LOC_INFIX "loc/" /** @@ -79,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 @@ -90,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. @@ -107,12 +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. * @@ -121,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); @@ -139,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); @@ -152,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); /** @@ -167,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); /** @@ -181,35 +204,31 @@ GNUNET_FS_uri_loc_get_uri (const struct GNUNET_FS_Uri *uri); /** - * Construct a location URI (this peer will be used for the location). + * Obtain the expiration of the LOC URI. * - * @param baseURI content offered by the sender - * @param cfg configuration information (used to find our hostkey) - * @param expiration_time how long will the content be offered? - * @return the location URI, NULL on error + * @param uri location URI to get the expiration from + * @return expiration time of the 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); +struct GNUNET_TIME_Absolute +GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri); /** - * Canonicalize keyword URI. Performs operations such - * as decapitalization and removal of certain characters. - * (useful for search). + * Construct a location URI (this peer will be used for the location). * - * @param uri the URI to canonicalize - * @return canonicalized version of the URI, NULL on error + * @param baseUri content offered by the sender + * @param cfg configuration information (used to find our hostkey) + * @param expiration_time how long will the content be offered? + * @return the location URI, NULL on error */ struct GNUNET_FS_Uri * -GNUNET_FS_uri_ksk_canonicalize (const struct GNUNET_FS_Uri *uri); +GNUNET_FS_uri_loc_create (const struct GNUNET_FS_Uri *baseUri, + 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 @@ -217,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); /** @@ -243,11 +262,12 @@ GNUNET_FS_uri_dup (const struct GNUNET_FS_Uri *uri); * "OR"ed keywords 'foo' and 'bar', not into '"foo bar"'. * * @param keywords the keyword string + * @param emsg where to store an error message * @return an FS URI for the given keywords, NULL * if keywords is not legal (i.e. empty). */ struct GNUNET_FS_Uri * -GNUNET_FS_uri_ksk_create (const char *keywords); +GNUNET_FS_uri_ksk_create (const char *keywords, char **emsg); /** @@ -268,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); /** @@ -279,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); /** @@ -294,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. @@ -302,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); /** @@ -327,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); /** @@ -336,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); @@ -346,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); @@ -354,10 +403,10 @@ GNUNET_FS_uri_test_chk (const struct GNUNET_FS_Uri *uri); * What is the size of the file that this URI * refers to? * - * @param uri the CHK URI to inspect + * @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); @@ -367,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); @@ -375,10 +424,13 @@ GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri); * Construct a keyword-URI from meta-data (take all entries * in the meta-data and construct one large keyword URI * that lists all keywords that can be found in the meta-data). - * @deprecated + * + * @param md metadata to use + * @return NULL on error, otherwise a KSK URI */ struct GNUNET_FS_Uri * -GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_MetaData *md); +GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData + *md); /* ******************** command-line option parsing API *********************** */ @@ -396,10 +448,9 @@ GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_MetaData *md); * @return GNUNET_OK on success */ int -GNUNET_FS_getopt_configure_set_keywords (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); /** @@ -409,16 +460,15 @@ GNUNET_FS_getopt_configure_set_keywords (GNUNET_GETOPT_CommandLineProcessorConte * the metadata must be passed as the "scls" argument. * * @param ctx command line processor context - * @param scls must be of type "struct GNUNET_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 */ int -GNUNET_FS_getopt_configure_set_metadata (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); @@ -426,239 +476,238 @@ GNUNET_FS_getopt_configure_set_metadata (GNUNET_GETOPT_CommandLineProcessorConte /** - * 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. */ enum GNUNET_FS_Status { /** - * Notification that we have started to share a file structure. + * Notification that we have started to publish a file structure. */ - GNUNET_FS_STATUS_SHARE_START, + GNUNET_FS_STATUS_PUBLISH_START = 0, /** * Notification that we have resumed sharing a file structure. */ - GNUNET_FS_STATUS_SHARE_RESUME, + GNUNET_FS_STATUS_PUBLISH_RESUME = 1, /** * Notification that we have suspended sharing a file structure. */ - GNUNET_FS_STATUS_SHARE_SUSPEND, + GNUNET_FS_STATUS_PUBLISH_SUSPEND = 2, /** * Notification that we are making progress sharing a file structure. */ - GNUNET_FS_STATUS_SHARE_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_share_stop" is called. + * this structure until "GNUNET_FS_publish_stop" is called. */ - GNUNET_FS_STATUS_SHARE_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_share_stop" is called. + * this structure until "GNUNET_FS_publish_stop" is called. */ - GNUNET_FS_STATUS_SHARE_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_SHARE_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, /** - * First event generated when a client requests + * 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 * 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 stopped (final event for this action). + * was completed. */ - GNUNET_FS_STATUS_UNINDEX_STOPPED + 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 = 36 }; -/** - * 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 - * in their meaning on the context in which the callback is used. - * - * @param cls closure - * @param info details about the event, specifying the event type - * and various bits about the event - * @return client-context (for the next progress call - * 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. - */ -typedef int (*GNUNET_FS_ProgressCallback) - (void *cls, - const struct GNUNET_FS_ProgressInfo *info); - - -/** - * Handle to one of our namespaces. - */ -struct GNUNET_FS_Namespace; - - /** * Handle for controlling an upload. */ -struct GNUNET_FS_ShareContext; +struct GNUNET_FS_PublishContext; /** @@ -673,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. */ @@ -680,7 +737,7 @@ struct GNUNET_FS_DownloadContext; /** - * Handle for detail information about a file that is being shared. + * Handle for detail information about a file that is being publishd. * Specifies metadata, keywords, how to get the contents of the file * (i.e. data-buffer in memory, filename on disk) and other options. */ @@ -692,32 +749,33 @@ 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_SHARE_*" events. + * Values for all "GNUNET_FS_STATUS_PUBLISH_*" events. */ - struct { + struct + { /** * Context for controlling the upload. */ - struct GNUNET_FS_ShareContext *sc; + struct GNUNET_FS_PublishContext *pc; /** - * Information about the file that is being shared. + * Information about the file that is being publishd. */ const struct GNUNET_FS_FileInformation *fi; /** - * Client context pointer (set the last time - * by the client for this operation; initially - * NULL on START/RESUME events). + * Client context pointer (set the last time by the client for + * this operation; initially NULL on START/RESUME events). */ void *cctx; @@ -726,11 +784,16 @@ struct GNUNET_FS_ProgressInfo * (if this is a file in a directory or a subdirectory). */ void *pctx; - + + /** + * 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; @@ -739,8 +802,8 @@ 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_Absolute eta; + */ + struct GNUNET_TIME_Relative eta; /** * How long has this upload been actively running @@ -756,71 +819,101 @@ struct GNUNET_FS_ProgressInfo /** * What anonymity level is used for this upload? */ - unsigned int anonymity; + uint32_t anonymity; /** * Additional values for specific events. */ - union { + union + { - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_SHARE_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 lowest level (DBLOCKs). + */ + unsigned int depth; - } progress; + } progress; - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_SHARE_RESUME events. + * 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; - } resume; + } resume; - /** + /** * These values are only valid for - * GNUNET_FS_STATUS_SHARE_ERROR events. + * GNUNET_FS_STATUS_PUBLISH_COMPLETED events. */ - struct { - - /** + struct + { + + /** + * URI of the file. + */ + const struct GNUNET_FS_Uri *chk_uri; + + } completed; + + /** + * These values are only valid for + * GNUNET_FS_STATUS_PUBLISH_ERROR events. + */ + struct + { + + /** * Error message, never NULL. */ - const char *message; + const char *message; - } error; + } error; } specifics; - } share; + } publish; + - /** * Values for all "GNUNET_FS_STATUS_DOWNLOAD_*" events. */ - struct { + struct + { /** * Context for controlling the download. @@ -839,17 +932,29 @@ 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. */ const struct GNUNET_FS_Uri *uri; - + /** - * 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 - * directory. + * Name of the file that we are downloading. + */ + const char *filename; + + /** + * How large is the download overall? This + * is NOT necessarily the size from the + * URI since we may be doing a partial download. */ uint64_t size; @@ -857,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_Absolute eta; + */ + struct GNUNET_TIME_Relative eta; /** * How long has this download been active? - */ + */ struct GNUNET_TIME_Relative duration; /** @@ -873,84 +978,103 @@ struct GNUNET_FS_ProgressInfo /** * What anonymity level is used for this download? */ - unsigned int anonymity; + 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; - /** - * Amount of trust we offered to get the block. + /** + * Depth of the given block in the tree; + * 0 would be the lowest level (DBLOCKS). */ - unsigned int trust_offered; + 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_MetaData *meta; + const struct GNUNET_CONTAINER_MetaData *meta; - } start; + } start; - /** + /** * These values are only valid for * GNUNET_FS_STATUS_DOWNLOAD_RESUME events. */ - struct { + struct + { - /** + /** * Known metadata for the download. */ - const struct GNUNET_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; @@ -959,7 +1083,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_SEARCH_*" events. */ - struct { + struct + { /** * Context for controlling the search, NULL for @@ -980,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; @@ -1001,238 +1128,257 @@ struct GNUNET_FS_ProgressInfo /** * What anonymity level is used for this search? */ - unsigned int anonymity; - - /** - * How much trust have we been offering for this search - * so far? - */ - unsigned int trust_offered; + uint32_t anonymity; /** * 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_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; - - /** + /** + * 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; + + /** * These values are only valid for * GNUNET_FS_STATUS_SEARCH_RESUME_RESULT events. */ - struct { - - /** + struct + { + + /** * Metadata for the search result. */ - const struct GNUNET_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) */ - int availability_rank; - - /** + int32_t availability_rank; + + /** * On how many total queries is the given * availability_rank based? */ - unsigned int availabiliy_certainty; + uint32_t availability_certainty; - /** + /** * Updated applicability rank (the larger, * the better the result fits the search * criteria). */ - unsigned int 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_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) */ - int availability_rank; - - /** + int32_t availability_rank; + + /** * On how many total queries is the given * availability_rank based? */ - unsigned int availabiliy_certainty; + uint32_t availability_certainty; - /** + /** * Updated applicability rank (the larger, * the better the result fits the search * criteria). */ - unsigned int applicabiliy_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_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_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_RESULT_NAMESPACE" events. + /** + * Values for all "GNUNET_FS_STATUS_SEARCH_RESULT_NAMESPACE" events. */ - struct { - - /** + struct + { + + /** * Handle to the namespace (NULL if it is not a local * namespace). */ - 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. */ - struct GNUNET_HashCode id; - - } namespace; + GNUNET_HashCode id; + + } namespace; } specifics; @@ -1241,7 +1387,8 @@ struct GNUNET_FS_ProgressInfo /** * Values for all "GNUNET_FS_STATUS_UNINDEX_*" events. */ - struct { + struct + { /** * Context for controlling the unindexing. @@ -1269,8 +1416,8 @@ 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_Absolute eta; + */ + struct GNUNET_TIME_Relative eta; /** * How long has this upload been actively running @@ -1286,56 +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; - } progress; + /** + * Depth of the given block in the tree; + * 0 would be the lowest level (DBLOCKS). + */ + unsigned int depth; + + } 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; @@ -1345,12 +1502,156 @@ 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 + * operation. Callbacks of this type will be used for uploads, + * 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 + * @param info details about the event, specifying the event type + * and various bits about the event + * @return client-context (for the next progress call + * 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. + */ +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, + + /** + * 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 +}; + +/** + * 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, + + /** + * 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); + + /** * Handle to the file-sharing service. */ @@ -1360,18 +1661,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 flags specific attributes for fs-operations + * @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, - struct GNUNET_CONFIGURATION_Handle *cfg, - const char *client_name, - GNUNET_FS_ProgressCallback upcb, - void *upcb_cls); +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, ...); /** @@ -1380,87 +1681,123 @@ 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); /** - * Function called on entries in a GNUNET_FS_FileInformation share-structure. + * Function called on entries in a GNUNET_FS_FileInformation publish-structure. * * @param cls closure - * @param fi the entry in the share-structure + * @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 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, - unsigned int *anonymity, - unsigned int *priority, - 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); + + +/** + * Obtain the name under which this file information + * structure is stored on disk. Only works for top-level + * 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" + * to read this fi-struct from disk. + */ +const char * +GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s); + /** - * Create an entry for a file in a share-structure. + * Create an entry for a file in a publish-structure. * - * @param filename name of the file or directory to share + * @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? - * @return share structure entry for the file + * @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_CONTAINER_MetaData *meta, - int do_index, - unsigned int anonymity, - unsigned int 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 share-structure. + * Create an entry for a file in a publish-structure. * + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param length length of the file * @param data data for the file (should not be used afterwards by - * the caller; caller will "free") + * the caller; callee will "free") + * @param keywords under which keywords should this file be available + * directly; can be NULL * @param meta metadata for the file * @param do_index GNUNET_YES for index, GNUNET_NO for insertion, * GNUNET_SYSERR for simulation - * @param 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 share structure entry for the file + * @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_CONTAINER_MetaData *meta, - int do_index, - unsigned int anonymity, - unsigned int 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); /** @@ -1470,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 @@ -1479,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 share-structure. + * Create an entry for a file in a publish-structure. * + * @param h handle to the file sharing subsystem + * @param client_info initial client-info value for this entry * @param length length of the file - * @param reader function that can be used to obtain the data for the file + * @param reader 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? - * @return share structure entry for the file + * @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, - unsigned int anonymity, - unsigned int 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); /** @@ -1522,61 +1856,70 @@ 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_FileInformationProcessor)(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 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, - 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); /** * Simple, useful default implementation of a directory scanner * (GNUNET_FS_DirectoryScanner). This implementation expects to get a - * UNIX filename, will share all files in the directory except hidden + * 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. + * 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 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, - GNUNET_FS_FileProcessor proc, - void *proc_cls); +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); /** - * Create a share-structure from an existing file hierarchy, inferring + * 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 @@ -1585,70 +1928,85 @@ 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 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 share structure entry for the directory, NULL on error + * @param do_index should files in the hierarchy be indexed? + * @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, - GNUNET_FS_DirectoryScanner scanner, - void *scanner_cls, - unsigned int anonymity, - unsigned int priority, - struct GNUNET_TIME_Absolute expirationTime); +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); /** - * Create an entry for an empty directory in a share-structure. + * 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 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? - * @return share structure entry for the directory , NULL on error + * @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, - unsigned int anonymity, - unsigned int 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); /** - * Add an entry to a directory in a share-structure. Clients - * should never modify share structures that were passed to - * "GNUNET_FS_share_start" already. + * 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. * * @param dir the directory - * @param end the entry to add; the entry must not have been - * added to any other directory at this point and + * @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 */ int GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir, - struct GNUNET_FS_FileInformation *end); + struct GNUNET_FS_FileInformation *ent); /** - * Inspect a file or directory in a share-structure. Clients - * should never modify share structures that were passed to - * "GNUNET_FS_share_start" already. When called on a directory, + * 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 * the directory itself and then for each of the files in the * directory (but not for files in subdirectories). When called @@ -1661,13 +2019,13 @@ GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir, */ void GNUNET_FS_file_information_inspect (struct GNUNET_FS_FileInformation *dir, - struct GNUNET_FS_FileInformationProcessor proc, - void *proc_cls); + GNUNET_FS_FileInformationProcessor proc, + void *proc_cls); /** - * Destroy share-structure. Clients should never destroy share - * structures that were passed to "GNUNET_FS_share_start" already. + * Destroy publish-structure. Clients should never destroy publish + * 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 @@ -1677,42 +2035,119 @@ 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 +{ + /** + * 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 +}; /** - * Share a file or directory. + * Publish a file or directory. * * @param h handle to the file sharing subsystem - * @param ctx initial value to use for the '*ctx' - * in the callback (for the GNUNET_FS_STATUS_SHARE_START event). - * @param fi information about the file or directory structure to share - * @param namespace namespace to share the file in, NULL for no namespace - * @param nid identifier to use for the shared content in the namespace + * @param fi information about the file or directory structure to publish + * @param namespace namespace to publish the file in, NULL for no namespace + * @param nid identifier to use for the publishd content in the namespace * (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) - * @return context that can be used to control the share operation + * @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); + + +/** + * 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 +GNUNET_FS_publish_stop (struct GNUNET_FS_PublishContext *pc); + + +/** + * Signature of a function called as the continuation of a KBlock or + * SBlock publication. + * + * @param cls closure + * @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); + + +/** + * Publish a KBlock on GNUnet. + * + * @param h handle to the file sharing subsystem + * @param ksk_uri keywords to use + * @param meta metadata to use + * @param uri URI to refer to in the KBlock + * @param bo block options + * @param options publication options + * @param cont continuation + * @param cont_cls closure for cont */ -struct GNUNET_FS_ShareContext * -GNUNET_FS_share_start (struct GNUNET_FS_Handle *h, - void *ctx, - const struct GNUNET_FS_FileInformation *fi, - struct GNUNET_FS_Namespace *namespace - const char *nid, - const char *nuid); +void +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, + const struct GNUNET_FS_BlockOptions *bo, + enum GNUNET_FS_PublishOptions options, + GNUNET_FS_PublishContinuation cont, void *cont_cls); /** - * Stop an upload. Will abort incomplete uploads (but - * not remove blocks that have already been shared) or - * simply clean up the state for completed uploads. + * Publish an SBlock on GNUnet. * - * @param sc context for the upload to stop + * @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 bo block options + * @param options publication options + * @param cont continuation + * @param cont_cls closure for cont */ -void -GNUNET_FS_share_stop (struct GNUNET_FS_ShareContext *sc); +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, + const struct GNUNET_FS_BlockOptions *bo, + enum GNUNET_FS_PublishOptions options, + GNUNET_FS_PublishContinuation cont, void *cont_cls); /** @@ -1720,10 +2155,11 @@ GNUNET_FS_share_stop (struct GNUNET_FS_ShareContext *sc); * * @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 */ -typedef int (*GNUNET_FS_FileProcessor) (void *cls, - const char *filename); +typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename, + const GNUNET_HashCode * file_id); /** @@ -1732,11 +2168,16 @@ typedef int (*GNUNET_FS_FileProcessor) (void *cls, * @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 */ -void +void GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, - GNUNET_FS_FileProcessor iterator, - void *iterator_cls); + GNUNET_FS_IndexedFileProcessor iterator, + void *iterator_cls, GNUNET_SCHEDULER_Task cont, + void *cont_cls); /** @@ -1744,11 +2185,12 @@ GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h, * * @param h handle to the file sharing subsystem * @param filename file to unindex - * @return NULL on error, otherwise handle + * @param cctx initial value for the client context + * @return NULL on error, otherwise handle */ struct GNUNET_FS_UnindexContext * -GNUNET_FS_unindex (struct GNUNET_FS_Handle *h, - const char *filename); +GNUNET_FS_unindex_start (struct GNUNET_FS_Handle *h, const char *filename, + void *cctx); /** @@ -1761,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_MetaData *meta, - unsigned int anonymity, - unsigned int 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); /** @@ -1796,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); /** @@ -1811,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); /** @@ -1825,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); /** @@ -1838,43 +2273,72 @@ typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, * @param h handle to the file sharing subsystem * @param cb function to call on each known namespace * @param cb_cls closure for cb - * @return GNUNET_SYSERR on error, otherwise the number of pseudonyms in list */ -int +void GNUNET_FS_namespace_list (struct GNUNET_FS_Handle *h, - GNUNET_FS_NamespaceProcessor 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 +}; /** @@ -1884,20 +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 */ struct GNUNET_FS_SearchContext * GNUNET_FS_search_start (struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - unsigned int 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); @@ -1906,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); @@ -1915,10 +2381,52 @@ 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); + + +/** + * 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, + + /** + * 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, + + /** + * 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) +}; + + + /** * Download parts of a file. Note that this will store * the blocks at the respective offset in the given file. Also, the @@ -1927,114 +2435,99 @@ GNUNET_FS_search_stop (struct GNUNET_FS_SearchContext *sc); * given boundaries (if offset and length do not match the 32k FS * block boundaries).
* - * This function should be used to focus a download towards a + * 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 uri the URI of the file (determines what to download); CHK or LOC URI + * @param meta known metadata for the file (can be NULL) * @param filename where to store the file, maybe NULL (then no file is * created on disk and data must be grabbed from the callbacks) + * @param tempname where to store temporary file data, not used if filename is non-NULL; + * can be NULL (in which case we will pick a name if needed); the temporary file + * may already exist, in which case we will try to use the data that is there and + * if it is not what is desired, will overwrite it * @param offset at what offset should we start the download (typically 0) * @param length how many bytes should be downloaded starting at offset * @param anonymity anonymity level to use for the download - * @param no_temporaries set to GNUNET_YES to disallow generation of temporary files - * @param recursive should this be a recursive download (useful for directories - * to automatically trigger download of files in the directories) + * @param options various download options + * @param cctx initial value for the client context for this download * @param parent parent download to associate this download with (use NULL * for top-level downloads; useful for manually-triggered recursive downloads) * @return context that can be used to control this download */ struct GNUNET_FS_DownloadContext * -GNUNET_FS_file_download_start (struct GNUNET_FS_Handle *h, - const struct GNUNET_FS_Uri *uri, - const char *filename, - unsigned long long offset, - unsigned long long length, - unsigned int anonymity, - int no_temporaries, - int recursive, - struct GNUNET_FS_DownloadContext *parent); - - -/** - * Stop a download (aborts if download is incomplete). - * - * @param rm handle for the download - * @param do_delete delete files of incomplete downloads - */ -void -GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *rm, - 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); +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); /** - * 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); /* ******************** Directory API *********************** */ -#define GNUNET_DIRECTORY_MIME "application/gnunet-directory" -#define GNUNET_DIRECTORY_MAGIC "\211GND\r\n\032\n" -#define GNUNET_DIRECTORY_EXT ".gnd" +#define GNUNET_FS_DIRECTORY_MIME "application/gnunet-directory" +#define GNUNET_FS_DIRECTORY_MAGIC "\211GND\r\n\032\n" +#define GNUNET_FS_DIRECTORY_EXT ".gnd" /** * Does the meta-data claim that this is a directory? @@ -2043,27 +2536,40 @@ 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. * * @param cls closure * @param filename name of the file in the directory * @param uri URI of the file - * @param metadata metadata for the file + * @param metadata metadata for the file; metadata for + * the directory if everything else is NULL/zero * @param length length of the available data for the file * (of type size_t since data must certainly fit * into memory; if files are larger than size_t @@ -2071,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_FS_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); /** @@ -2093,14 +2601,63 @@ 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 spcb - */ -void -GNUNET_FS_directory_list_contents (size_t size, - const void *data, - uint64_t offset, - GNUNET_FS_DirectoryEntryProcessor dep, - void *dep_cls); + * @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 + */ +int +GNUNET_FS_directory_list_contents (size_t size, const void *data, + uint64_t offset, + GNUNET_FS_DirectoryEntryProcessor dep, + void *dep_cls); + + +/** + * Opaque handle to a directory builder. + */ +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); + + +/** + * 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 + * @param data raw data of the entry, can be NULL, otherwise + * data must point to exactly the number of bytes specified + * by the uri + */ +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); + + +/** + * Finish building the directory. Frees the + * builder context and returns the directory + * in-memory. + * + * @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 + */ +int +GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld, + size_t * rsize, void **rdata); #if 0 /* keep Emacsens' auto-indent happy */