* 9.0.0: CPS-style integrated API
* 9.1.1: asynchronous directory scanning
*/
-#define GNUNET_FS_VERSION 0x00090101
+#define GNUNET_FS_VERSION 0x00090102
/* ******************** 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;
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.
*
* @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;
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 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,
const char *identifier, const char *update,
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 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,
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
* @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);
/**
*/
enum GNUNET_FS_DirScannerProgressUpdateReason
{
- /**
- * FIXME
- */
- GNUNET_FS_DIRSCANNER_FIRST = 0,
/**
- * FIXME
+ * We've started processing a file or directory.
*/
- GNUNET_FS_DIRSCANNER_NEW_FILE = 1,
+ GNUNET_FS_DIRSCANNER_FILE_START = 0,
/**
- * FIXME
+ * We're having trouble accessing a file (soft-error); it will
+ * be ignored.
*/
- GNUNET_FS_DIRSCANNER_DOES_NOT_EXIST = 2,
+ GNUNET_FS_DIRSCANNER_FILE_IGNORED,
/**
- * FIXME
+ * We've found all files (in the pre-pass).
*/
- GNUNET_FS_DIRSCANNER_ASKED_TO_STOP = 3,
+ GNUNET_FS_DIRSCANNER_ALL_COUNTED,
/**
- * FIXME
+ * We've finished extracting meta data from a file.
*/
- GNUNET_FS_DIRSCANNER_FINISHED = 4,
+ GNUNET_FS_DIRSCANNER_EXTRACT_FINISHED,
/**
- * FIXME
+ * Last call to the progress function: we have finished scanning
+ * the directory.
*/
- GNUNET_FS_DIRSCANNER_PROTOCOL_ERROR = 5,
+ GNUNET_FS_DIRSCANNER_FINISHED,
/**
- * FIXME
+ * There was an internal error. Application should abort the scan.
*/
- GNUNET_FS_DIRSCANNER_SHUTDOWN = 6,
+ GNUNET_FS_DIRSCANNER_INTERNAL_ERROR
- /**
- * FIXME
- */
- GNUNET_FS_DIRSCANNER_LAST = 7
};
* progress on the job at hand.
*
* @param cls closure
- * @param ds handle to the directory scanner (NEEDED!?)
* @param filename which file we are making progress on
- * @param is_directory GNUNET_YES if this is a directory
+ * @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 int (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
- struct GNUNET_FS_DirScanner *ds,
- const char *filename,
- int is_directory,
- enum GNUNET_FS_DirScannerProgressUpdateReason reason);
+typedef void (*GNUNET_FS_DirScannerProgressCallback) (void *cls,
+ const char *filename,
+ int is_directory,
+ enum GNUNET_FS_DirScannerProgressUpdateReason reason);
/**
char *filename;
/**
- * Base name of the file/directory
+ * Base name of the file/directory.
*/
char *short_filename;
- /**
- * Size of the file (if it is a file), in bytes
- */
- uint64_t file_size;
-
/**
* GNUNET_YES if this is a directory
*/
/**
- * 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 cb_cls closure for 'cb'
/**
- * 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.
+ * Abort the scan. Must not be called from within the progress_callback
+ * function.
*
* @param ds directory scanner structure
- * @param close_pipe GNUNET_YES to close
*/
void
-GNUNET_FS_directory_scan_finish (struct GNUNET_FS_DirScanner *ds,
- int close_pipe);
+GNUNET_FS_directory_scan_abort (struct GNUNET_FS_DirScanner *ds);
/**
- * 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.
+ * 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_cleanup (struct GNUNET_FS_DirScanner *ds);
+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'
- * @return FIXME: what would this handle be used for?
*/
-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