* 6.0.0: with support for OR in KSKs
* 6.1.x: with simplified namespace support
* 9.0.0: CPS-style integrated API
+ * 9.1.1: asynchronous directory scanning
*/
-#define GNUNET_FS_VERSION 0x00090001
+#define GNUNET_FS_VERSION 0x00090103
/* ******************** URI API *********************** */
*/
struct GNUNET_FS_Uri;
-struct GNUNET_FS_DirScanner;
-
/**
* Iterator over keywords
*
* @param key wherer to store the unique key
*/
void
-GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, GNUNET_HashCode * key);
+GNUNET_FS_uri_to_key (const struct GNUNET_FS_Uri *uri, struct GNUNET_HashCode * key);
/**
* Convert a URI to a UTF-8 String.
* @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);
+GNUNET_FS_uri_sks_create_from_nsid (struct GNUNET_HashCode * nsid, const char *id);
/**
*/
int
GNUNET_FS_uri_sks_get_namespace (const struct GNUNET_FS_Uri *uri,
- GNUNET_HashCode * nsid);
+ struct GNUNET_HashCode * nsid);
/**
*/
uint64_t data_len;
+ /**
+ * How much time passed between us asking for this block and
+ * actually getting it? GNUNET_TIME_UNIT_FOREVER_REL if unknown.
+ */
+ struct GNUNET_TIME_Relative block_download_duration;
+
/**
* Depth of the given block in the tree;
* 0 would be the lowest level (DBLOCKS).
unsigned int depth;
/**
- * How much trust did we offer for downloading this block?
+ * How much respect did we offer for downloading this block? (estimate,
+ * because we might have the same request pending for multiple clients,
+ * and of course because a transmission may have failed at a lower
+ * layer).
*/
- unsigned int trust_offered;
+ uint32_t respect_offered;
/**
- * How much time passed between us asking for this block and
- * actually getting it? GNUNET_TIME_UNIT_FOREVER_REL if unknown.
+ * How often did we transmit the request? (estimate,
+ * because we might have the same request pending for multiple clients,
+ * and of course because a transmission may have failed at a lower
+ * layer).
*/
- struct GNUNET_TIME_Relative block_download_duration;
+ uint32_t num_transmissions;
} progress;
/**
* Hash-identifier for the namespace.
*/
- GNUNET_HashCode id;
+ struct GNUNET_HashCode id;
- } namespace;
+ } ns;
} specifics;
* field in the GNUNET_FS_ProgressInfo struct.
*/
typedef void *(*GNUNET_FS_ProgressCallback) (void *cls,
- const struct GNUNET_FS_ProgressInfo
- * info);
+ const struct GNUNET_FS_ProgressInfo *info);
/**
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.
- */
+ /**
+ * 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).
- */
+ /**
+ * 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.
- */
+ /**
+ * 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
};
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 publish-structure.
*
const char *
GNUNET_FS_file_information_get_filename (struct GNUNET_FS_FileInformation *s);
+
/**
* Set the filename in the file information structure.
* If filename was already set, frees it before setting the new one.
GNUNET_FS_file_information_set_filename (struct GNUNET_FS_FileInformation *s,
const char *filename);
+
/**
* Create an entry for a file in a publish-structure.
*
* @param cls closure
* @param offset offset to read from; it is possible
* that the caller might need to go backwards
- * a bit at times
+ * a bit at times; set to UINT64_MAX to tell
+ * the reader that we won't be reading for a while
+ * (used to close the file descriptor but NOT fully
+ * clean up the reader's state); in this case,
+ * a value of '0' for max should be ignored
* @param max maximum number of bytes that should be
* copied to buf; readers are not allowed
* to provide less data unless there is an error;
GNUNET_FS_BlockOptions *bo);
-/**
- * Function that a "GNUNET_FS_DirectoryScanner" should call
- * for each entry in the directory.
- *
- * @param cls closure
- * @param filename name of the file (including path); must end
- * in a "/" (even on W32) if this is a directory
- * @param fi information about the file (should not be
- * used henceforth by the caller)
- */
-typedef void (*GNUNET_FS_FileProcessor) (void *cls, const char *filename,
- struct GNUNET_FS_FileInformation * fi);
-
-
-/**
- * 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,
- 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 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
- * 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, 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 publish-structure from an existing file hierarchy, inferring
- * and organizing keywords and metadata as much as possible. This
- * function primarily performs the recursive build and re-organizes
- * keywords and metadata; for automatically getting metadata
- * extraction, scanning of directories and creation of the respective
- * GNUNET_FS_FileInformation entries the default scanner should be
- * passed (GNUNET_FS_directory_scanner_default). This is strictly a
- * convenience function.
- *
- * @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 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 (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 publish-structure.
* This function should be used by applications for which the
*
* @param h handle to the file sharing subsystem
* @param fi information about the file or directory structure to publish
- * @param namespace namespace to publish the file in, NULL for no namespace
+ * @param ns namespace to publish the file in, NULL for no namespace
* @param nid identifier to use for the publishd content in the namespace
* (can be NULL, must be NULL if namespace is NULL)
* @param nuid update-identifier that will be used for future updates
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,
+ struct GNUNET_FS_Namespace *ns, const char *nid,
const char *nuid,
enum GNUNET_FS_PublishOptions options);
const char *emsg);
+/**
+ * Handle to cancel publish KSK operation.
+ */
+struct GNUNET_FS_PublishKskContext;
+
+
/**
* Publish a KBlock on GNUnet.
*
* @param options publication options
* @param cont continuation
* @param cont_cls closure for cont
+ * @return NULL on error ('cont' will still be called)
*/
-void
+struct GNUNET_FS_PublishKskContext *
GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
const struct GNUNET_FS_Uri *ksk_uri,
const struct GNUNET_CONTAINER_MetaData *meta,
GNUNET_FS_PublishContinuation cont, void *cont_cls);
+/**
+ * Abort the KSK publishing operation.
+ *
+ * @param pkc context of the operation to abort.
+ */
+void
+GNUNET_FS_publish_ksk_cancel (struct GNUNET_FS_PublishKskContext *pkc);
+
+
+/**
+ * Handle to cancel publish SKS operation.
+ */
+struct GNUNET_FS_PublishSksContext;
+
+
/**
* Publish an SBlock on GNUnet.
*
* @param h handle to the file sharing subsystem
- * @param namespace namespace to publish in
+ * @param ns namespace to publish in
* @param identifier identifier to use
* @param update update identifier to use
* @param meta metadata to use
* @param options publication options
* @param cont continuation
* @param cont_cls closure for cont
+ * @return NULL on error ('cont' will still be called)
*/
-void
+struct GNUNET_FS_PublishSksContext *
GNUNET_FS_publish_sks (struct GNUNET_FS_Handle *h,
- struct GNUNET_FS_Namespace *namespace,
+ struct GNUNET_FS_Namespace *ns,
const char *identifier, const char *update,
const struct GNUNET_CONTAINER_MetaData *meta,
const struct GNUNET_FS_Uri *uri,
GNUNET_FS_PublishContinuation cont, void *cont_cls);
+/**
+ * Abort the SKS publishing operation.
+ *
+ * @param psc context of the operation to abort.
+ */
+void
+GNUNET_FS_publish_sks_cancel (struct GNUNET_FS_PublishSksContext *psc);
+
+
/**
* Type of a function called by "GNUNET_FS_get_indexed_files".
*
* @param cls closure
- * @param filename the name of the file
+ * @param filename the name of the file, NULL for end of list
* @param file_id hash of the contents of the indexed file
* @return GNUNET_OK to continue iteration, GNUNET_SYSERR to abort
*/
typedef int (*GNUNET_FS_IndexedFileProcessor) (void *cls, const char *filename,
- const GNUNET_HashCode * file_id);
+ const struct GNUNET_HashCode * file_id);
+
+
+/**
+ * Handle to cancel 'GNUNET_FS_get_indexed_files'.
+ */
+struct GNUNET_FS_GetIndexedContext;
/**
* @param h handle to the file sharing subsystem
* @param iterator function to call on each indexed file
* @param iterator_cls closure for iterator
- * @param cont continuation to call when done;
- * reason should be "TIMEOUT" (on
- * error) or "PREREQ_DONE" (on success)
- * @param cont_cls closure for cont
+ * @return NULL on error ('iter' is not called)
*/
-void
+struct GNUNET_FS_GetIndexedContext *
GNUNET_FS_get_indexed_files (struct GNUNET_FS_Handle *h,
GNUNET_FS_IndexedFileProcessor iterator,
- void *iterator_cls, GNUNET_SCHEDULER_Task cont,
- void *cont_cls);
+ void *iterator_cls);
+
+
+/**
+ * Cancel iteration over all indexed files.
+ *
+ * @param gic operation to cancel
+ */
+void
+GNUNET_FS_get_indexed_files_cancel (struct GNUNET_FS_GetIndexedContext *gic);
/**
GNUNET_FS_unindex_stop (struct GNUNET_FS_UnindexContext *uc);
+/**
+ * Context for advertising a namespace.
+ */
+struct GNUNET_FS_AdvertisementContext;
+
+
/**
* 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 ns handle for the namespace that should be advertised
* @param meta meta-data for the namespace advertisement
* @param bo block options
* @param rootEntry name of the root of the namespace
* @param cont continuation
* @param cont_cls closure for cont
+ * @return NULL on error ('cont' will still be called)
*/
-void
+struct GNUNET_FS_AdvertisementContext *
GNUNET_FS_namespace_advertise (struct GNUNET_FS_Handle *h,
struct GNUNET_FS_Uri *ksk_uri,
- struct GNUNET_FS_Namespace *namespace,
+ struct GNUNET_FS_Namespace *ns,
const struct GNUNET_CONTAINER_MetaData *meta,
const struct GNUNET_FS_BlockOptions *bo,
const char *rootEntry,
void *cont_cls);
+/**
+ * Abort the namespace advertisement operation.
+ *
+ * @param ac context of the operation to abort.
+ */
+void
+GNUNET_FS_namespace_advertise_cancel (struct GNUNET_FS_AdvertisementContext *ac);
+
+
/**
* Create a namespace with the given name; if one already
* exists, return a handle to the existing namespace.
*
* @param h handle to the file sharing subsystem
* @param name name to use for the namespace
- * @return handle to the namespace, NULL on error
+ * @return handle to the namespace, NULL on error (i.e. invalid filename)
*/
struct GNUNET_FS_Namespace *
GNUNET_FS_namespace_create (struct GNUNET_FS_Handle *h, const char *name);
+/**
+ * Duplicate a namespace handle.
+ *
+ * @param ns namespace handle
+ * @return duplicated handle to the namespace
+ */
+struct GNUNET_FS_Namespace *
+GNUNET_FS_namespace_dup (struct GNUNET_FS_Namespace *ns);
+
+
/**
* Delete a namespace handle. Can be used for a clean shutdown (free
* memory) or also to freeze the namespace to prevent further
* insertions by anyone.
*
- * @param namespace handle to the namespace that should be deleted / freed
+ * @param ns handle to the namespace that should be deleted / freed
* @param freeze prevents future insertions; creating a namespace
* with the same name again will create a fresh namespace instead
*
* @return GNUNET_OK on success, GNUNET_SYSERR on error
*/
int
-GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *namespace, int freeze);
+GNUNET_FS_namespace_delete (struct GNUNET_FS_Namespace *ns, int freeze);
/**
* @param id hash identifier for the namespace
*/
typedef void (*GNUNET_FS_NamespaceInfoProcessor) (void *cls, const char *name,
- const GNUNET_HashCode * id);
+ const struct GNUNET_HashCode * id);
/**
* 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 ns namespace to inspect for updateable content
* @param next_id ID to look for; use NULL to look for SCC roots
* @param ip function to call on each updateable identifier
* @param ip_cls closure for ip
*/
void
-GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *namespace,
+GNUNET_FS_namespace_list_updateable (struct GNUNET_FS_Namespace *ns,
const char *next_id,
GNUNET_FS_IdentifierProcessor ip,
void *ip_cls);
/* ******************** DirScanner API *********************** */
+/**
+ * Progress reasons of the directory scanner.
+ */
enum GNUNET_FS_DirScannerProgressUpdateReason
{
- GNUNET_FS_DIRSCANNER_FIRST = 0,
- GNUNET_FS_DIRSCANNER_NEW_FILE = 1,
- GNUNET_FS_DIRSCANNER_DOES_NOT_EXIST = 2,
- GNUNET_FS_DIRSCANNER_ASKED_TO_STOP = 3,
- GNUNET_FS_DIRSCANNER_FINISHED = 4,
- GNUNET_FS_DIRSCANNER_PROTOCOL_ERROR = 5,
- GNUNET_FS_DIRSCANNER_SHUTDOWN = 6,
- GNUNET_FS_DIRSCANNER_LAST = 7
+
+ /**
+ * We've started processing a file or directory.
+ */
+ GNUNET_FS_DIRSCANNER_FILE_START = 0,
+
+ /**
+ * We're having trouble accessing a file (soft-error); it will
+ * be ignored.
+ */
+ GNUNET_FS_DIRSCANNER_FILE_IGNORED,
+
+ /**
+ * We've found all files (in the pre-pass).
+ */
+ GNUNET_FS_DIRSCANNER_ALL_COUNTED,
+
+ /**
+ * We've finished extracting meta data from a file.
+ */
+ GNUNET_FS_DIRSCANNER_EXTRACT_FINISHED,
+
+ /**
+ * Last call to the progress function: we have finished scanning
+ * the directory.
+ */
+ GNUNET_FS_DIRSCANNER_FINISHED,
+
+ /**
+ * There was an internal error. Application should abort the scan.
+ */
+ GNUNET_FS_DIRSCANNER_INTERNAL_ERROR
+
};
-typedef int (* GNUNET_FS_DirScannerProgressCallback) (
- void *cls, struct GNUNET_FS_DirScanner *ds, const char *filename,
- char is_directory, enum GNUNET_FS_DirScannerProgressUpdateReason reason);
+/**
+ * Function called over time as the directory scanner makes
+ * progress on the job at hand.
+ *
+ * @param cls closure
+ * @param filename which file we are making progress on
+ * @param is_directory GNUNET_YES if this is a directory,
+ * GNUNET_NO if this is a file
+ * GNUNET_SYSERR if it is neither (or unknown)
+ * @param reason kind of progress we are making
+ */
+typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
+ const char *filename,
+ int is_directory,
+ enum GNUNET_FS_DirScannerProgressUpdateReason reason);
+
/**
* A node of a directory tree (produced by dirscanner)
char *filename;
/**
- * Base name of the file/directory
+ * Base name of the file/directory.
*/
char *short_filename;
/**
- * 1 if this is a directory
+ * GNUNET_YES if this is a directory
*/
- char is_directory;
+ int is_directory;
- /**
- * Size of the file (if it's a file), in bytes
- */
- uint64_t file_size;
};
-/* opaqe */
-struct GNUNET_FS_DirScanner;
/**
- * Signals the scanner to finish the scan as fast as possible.
- * Does not block.
- * Can close the pipe if asked to, but that is only used by the
- * internal call to this function during cleanup. The client
- * must understand the consequences of closing the pipe too early.
- *
- * @param ds directory scanner structure
- * @param close_pipe GNUNET_YES to close
+ * Opaqe handle to an asynchronous directory scanning activity.
*/
-void
-GNUNET_FS_directory_scan_finish (struct GNUNET_FS_DirScanner *ds,
- int close_pipe);
+struct GNUNET_FS_DirScanner;
-/**
- * Signals the scanner thread to finish (in case it isn't finishing
- * already) and joins the scanner thread. Closes the pipes, frees the
- * scanner contexts (both of them), returns the results of the scan.
- * Results are valid (and have to be freed) even if the scanner had
- * an error or was rushed to finish prematurely.
- * Blocks until the scanner is finished.
- *
- * @param ds directory scanner structure
- * @return the results of the scan (a directory tree)
- */
-struct GNUNET_FS_ShareTreeItem *
-GNUNET_FS_directory_scan_cleanup (struct GNUNET_FS_DirScanner *ds);
/**
- * Start a directory scanner thread.
+ * Start a directory scanner.
*
* @param filename name of the directory to scan
- * @param GNUNET_YES to not to run libextractor on files (only build a tree)
+ * @param disable_extractor GNUNET_YES to not to run libextractor on files (only build a tree)
* @param ex if not NULL, must be a list of extra plugins for extractor
* @param cb the callback to call when there are scanning progress messages
- * @param cls closure for 'cb'
+ * @param cb_cls closure for 'cb'
* @return directory scanner object to be used for controlling the scanner
*/
struct GNUNET_FS_DirScanner *
GNUNET_FS_directory_scan_start (const char *filename,
- int disable_extractor, const char *ex,
- GNUNET_FS_DirScannerProgressCallback cb, void *cls);
+ int disable_extractor,
+ const char *ex,
+ GNUNET_FS_DirScannerProgressCallback cb,
+ void *cb_cls);
+
+/**
+ * Abort the scan. Must not be called from within the progress_callback
+ * function.
+ *
+ * @param ds directory scanner structure
+ */
+void
+GNUNET_FS_directory_scan_abort (struct GNUNET_FS_DirScanner *ds);
+
+
+/**
+ * Obtain the result of the scan after the scan has signalled
+ * completion. Must not be called prior to completion. The 'ds' is
+ * freed as part of this call.
+ *
+ * @param ds directory scanner structure
+ * @return the results of the scan (a directory tree)
+ */
+struct GNUNET_FS_ShareTreeItem *
+GNUNET_FS_directory_scan_get_result (struct GNUNET_FS_DirScanner *ds);
-/* opaque */
-struct GNUNET_FS_ProcessMetadataContext;
/**
* Process a share item tree, moving frequent keywords up and
* copying frequent metadata up.
*
* @param toplevel toplevel directory in the tree, returned by the scanner
- * @param cb called after processing is done
- * @param cls closure for 'cb'
*/
-struct GNUNET_FS_ProcessMetadataContext *
-GNUNET_FS_trim_share_tree (struct GNUNET_FS_ShareTreeItem *toplevel,
- GNUNET_SCHEDULER_Task cb, void *cls);
+void
+GNUNET_FS_share_tree_trim (struct GNUNET_FS_ShareTreeItem *toplevel);
+
+
+/**
+ * Release memory of a share item tree.
+ *
+ * @param toplevel toplevel of the tree to be freed
+ */
+void
+GNUNET_FS_share_tree_free (struct GNUNET_FS_ShareTreeItem *toplevel);
#if 0 /* keep Emacsens' auto-indent happy */
projects / oweals / gnunet.git / blobdiff