diff options
author | Martyn Russell <martyn@lanedo.com> | 2014-12-15 13:13:19 +0000 |
---|---|---|
committer | Martyn Russell <martyn@lanedo.com> | 2014-12-15 13:13:55 +0000 |
commit | 7ee5c308920b768f050e51ca644140c0c0e7bdce (patch) | |
tree | 007b8135f393be5f17fc76aa6d6c68456bab6a6c | |
parent | 3742904af9d57dda2ffca6be8af8e5c58e436a72 (diff) | |
download | tracker-7ee5c308920b768f050e51ca644140c0c0e7bdce.tar.gz |
libtracker-miner: Finished documenting public APIs
Only 2 left, mainly because they're a NOP or don't work currently and need
fixing.
-rw-r--r-- | src/libtracker-miner/tracker-decorator.c | 10 | ||||
-rw-r--r-- | src/libtracker-miner/tracker-media-art.c | 12 | ||||
-rw-r--r-- | src/libtracker-miner/tracker-miner-fs.c | 68 | ||||
-rw-r--r-- | src/libtracker-miner/tracker-miner-object.c | 6 | ||||
-rw-r--r-- | src/libtracker-miner/tracker-thumbnailer.c | 15 |
5 files changed, 95 insertions, 16 deletions
diff --git a/src/libtracker-miner/tracker-decorator.c b/src/libtracker-miner/tracker-decorator.c index 8991e97d1..b8978d811 100644 --- a/src/libtracker-miner/tracker-decorator.c +++ b/src/libtracker-miner/tracker-decorator.c @@ -34,7 +34,8 @@ * @include: libtracker-miner/tracker-miner.h * @title: TrackerDecorator * @see_also: #TrackerDecoratorFS - * #TrackerDecorator watches for signal updates based on file changes + * + * #TrackerDecorator watches for signal updates based on content changes * in the database. When new files are added initially, only simple * metadata exists, for example, name, size, mtime, etc. The * #TrackerDecorator queues files for extended metadata extraction @@ -102,11 +103,10 @@ static void tracker_decorator_initable_iface_init (GInitableIface *iface); /** * tracker_decorator_error_quark: * - * Quarks are used as the domain for a #GError. For all errors relating - * to @TrackerDecorator, you can compare the domain to the return - * value of this function. + * Gives the caller the #GQuark used to identify #TrackerDecorator errors + * in #GError structures. The #GQuark is used as the domain for the error. * - * Returns: the @GQuark used for #GErrors related to @TrackerDecorator implementations. + * Returns: the #GQuark used for the domain of a #GError. * * Since: 0.18. **/ diff --git a/src/libtracker-miner/tracker-media-art.c b/src/libtracker-miner/tracker-media-art.c index 1be85c235..c0559e9eb 100644 --- a/src/libtracker-miner/tracker-media-art.c +++ b/src/libtracker-miner/tracker-media-art.c @@ -159,6 +159,7 @@ on_error: } #endif /* HAVE_LIBMEDIAART */ } + /** * tracker_media_art_queue_remove: * @uri: URI of the file @@ -214,9 +215,15 @@ on_timer_destroy (gpointer data) } /** - * tracker_media_art_queue_execute: + * tracker_media_art_queue_empty: + * @connection: a #TrackerSparqlConnection + * + * Using @connection, find all media art associated with content in + * Tracker (so as not to remove media art for other processes) and + * remove caches for that media art. * - * Process all stored media art requests. + * Note, this highly depends on built in support for libmediaart. If + * there is no support, this API does nothing. * * Since: 0.10.4 */ @@ -224,7 +231,6 @@ void tracker_media_art_queue_empty (TrackerSparqlConnection *connection) { if (had_any && timer_id == 0) { - timer_id = g_timeout_add_seconds_full (G_PRIORITY_LOW, 1800 /* Half an hour worth of seconds*/, on_timer_callback, diff --git a/src/libtracker-miner/tracker-miner-fs.c b/src/libtracker-miner/tracker-miner-fs.c index ba4d36026..28842e320 100644 --- a/src/libtracker-miner/tracker-miner-fs.c +++ b/src/libtracker-miner/tracker-miner-fs.c @@ -356,6 +356,16 @@ static GQuark quark_file_iri = 0; static GInitableIface* miner_fs_initable_parent_iface; static guint signals[LAST_SIGNAL] = { 0, }; +/** + * tracker_miner_fs_error_quark: + * + * Gives the caller the #GQuark used to identify #TrackerMinerFS errors + * in #GError structures. The #GQuark is used as the domain for the error. + * + * Returns: the #GQuark used for the domain of a #GError. + * + * Since: 1.2. + **/ G_DEFINE_QUARK (TrackerMinerFSError, tracker_miner_fs_error) G_DEFINE_ABSTRACT_TYPE_WITH_CODE (TrackerMinerFS, tracker_miner_fs, TRACKER_TYPE_MINER, @@ -3957,7 +3967,7 @@ tracker_miner_fs_force_recheck (TrackerMinerFS *fs) * could be changed outside between startup and shutdown of the * process using this API. * - * The default if not set directly is that @mtime_checking is #TRUE. + * The default if not set directly is that @mtime_checking is %TRUE. * * Since: 0.10 **/ @@ -3974,8 +3984,13 @@ tracker_miner_fs_set_mtime_checking (TrackerMinerFS *fs, * tracker_miner_fs_get_mtime_checking: * @fs: a #TrackerMinerFS * - * Returns: #TRUE if mtime checks for directories against the database - * are done when @fs crawls the file system, otherwise #FALSE. + * Returns a boolean used to identify if file modification time checks + * are performed when processing content. This may be set to %FALSE if + * working prodominently with cloud data where you can't perform these + * checks. By default and for local file systems, this is enabled. + * + * Returns: %TRUE if mtime checks for directories against the database + * are done when @fs crawls the file system, otherwise %FALSE. * * Since: 0.10 **/ @@ -4018,6 +4033,30 @@ tracker_miner_fs_force_mtime_checking (TrackerMinerFS *fs, flags); } +/** + * tracker_miner_fs_set_initial_crawling: + * @fs: a #TrackerMinerFS + * @do_initial_crawling: a #gboolean + * + * Tells the @fs that crawling the #TrackerIndexingTree should happen + * initially. This is actually required to set up file system monitor + * using technologies like inotify, etc. + * + * Setting this to #FALSE can dramatically improve the start up the + * crawling of the @fs. + * + * The down side is that using this consistently means that some files + * on the disk may be out of date with files in the database. + * + * The main purpose of this function is for systems where a @fs is + * running the entire time and where it is very unlikely that a file + * could be changed outside between startup and shutdown of the + * process using this API. + * + * The default if not set directly is that @do_initial_crawling is %TRUE. + * + * Since: 0.10 + **/ void tracker_miner_fs_set_initial_crawling (TrackerMinerFS *fs, gboolean do_initial_crawling) @@ -4027,6 +4066,20 @@ tracker_miner_fs_set_initial_crawling (TrackerMinerFS *fs, fs->priv->initial_crawling = do_initial_crawling; } +/** + * tracker_miner_fs_get_initial_crawling: + * @fs: a #TrackerMinerFS + * + * Returns a boolean which indicates if the indexing tree is crawled + * upon start up or not. This may be set to %FALSE if working + * prodominently with cloud data where you can't perform these checks. + * By default and for local file systems, this is enabled. + * + * Returns: %TRUE if a file system structure is crawled for new + * updates on start up, otherwise %FALSE. + * + * Since: 0.10 + **/ gboolean tracker_miner_fs_get_initial_crawling (TrackerMinerFS *fs) { @@ -4039,8 +4092,13 @@ tracker_miner_fs_get_initial_crawling (TrackerMinerFS *fs) * tracker_miner_fs_has_items_to_process: * @fs: a #TrackerMinerFS * - * Returns: #TRUE if there are items to process in the internal - * queues, otherwise #FALSE. + * The @fs keeps many priority queus for content it is processing. + * This function returns %TRUE if the sum of all (or any) priority + * queues is more than 0. This includes items deleted, created, + * updated, moved or being written back. + * + * Returns: %TRUE if there are items to process in the internal + * queues, otherwise %FALSE. * * Since: 0.10 **/ diff --git a/src/libtracker-miner/tracker-miner-object.c b/src/libtracker-miner/tracker-miner-object.c index 470f84ff6..360ac7cd8 100644 --- a/src/libtracker-miner/tracker-miner-object.c +++ b/src/libtracker-miner/tracker-miner-object.c @@ -215,10 +215,10 @@ static void on_tracker_store_disappeared (GDBusConnection *connecti /** * tracker_miner_error_quark: * - * Gives the caller the #GQuark used to identify miner errors in - * GError structures. + * Gives the caller the #GQuark used to identify #TrackerMiner errors + * in #GError structures. The #GQuark is used as the domain for the error. * - * Returns: the error #GQuark + * Returns: the #GQuark used for the domain of a #GError. * * Since: 0.8 **/ diff --git a/src/libtracker-miner/tracker-thumbnailer.c b/src/libtracker-miner/tracker-thumbnailer.c index 2af4d8bb0..c95bacc0c 100644 --- a/src/libtracker-miner/tracker-thumbnailer.c +++ b/src/libtracker-miner/tracker-thumbnailer.c @@ -256,6 +256,21 @@ tracker_thumbnailer_init (TrackerThumbnailer *thumbnailer) { } +/** + * tracker_thumbnailer_new: + * + * Creates a new #TrackerThumbnailer object that can be used to signal + * the system's thumbnailing daemon(s) via D-Bus to add or remove + * content that needs thumbnailing. + * + * For example, when mounting a USB thumb drive, content may not have + * thumbnails and this object allows the content of that thumb drive + * to be queued for processing. + * + * Returns: %TRUE if successfully stored to be reported, %FALSE otherwise. + * + * Since: 0.18. + */ TrackerThumbnailer * tracker_thumbnailer_new (void) { |