GNOME.org
 

[tracker/external-crawler: 26/42] libtracker-miner: Update all documentation around TrackerEnumerator interface

commit 8dc9a253041c1be4a8841d6a5f1533b564d60486
Author: Martyn Russell <martyn lanedo com>
Date:   Wed Jun 4 13:20:02 2014 +0100

    libtracker-miner: Update all documentation around TrackerEnumerator interface
    
    Including:
    - How we use it in TrackerMinerFS
    - TrackerEnumerator itself
    - TrackerFileEnumerator

 .../libtracker-miner/libtracker-miner-docs.sgml    |    2 +
 .../libtracker-miner/libtracker-miner-sections.txt |   34 +++++-
 src/libtracker-miner/tracker-enumerator.c          |  128 ++++++++++++++++++++
 src/libtracker-miner/tracker-enumerator.h          |   27 ++++
 src/libtracker-miner/tracker-file-enumerator.c     |   31 +++++
 src/libtracker-miner/tracker-file-enumerator.h     |   11 ++
 src/libtracker-miner/tracker-miner-fs.c            |   38 ++++++-
 7 files changed, 267 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml 
b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
index 074f485..582c152 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
+++ b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
@@ -32,12 +32,14 @@
       <title>Base abstract miner classes</title>
       <xi:include href="xml/tracker-miner-object.xml"/>
       <xi:include href="xml/tracker-miner-online.xml"/>
+      <xi:include href="xml/tracker-enumerator.xml"/>
       <xi:include href="xml/tracker-decorator.xml"/>
     </chapter>
 
     <chapter>
       <title>Miner classes for file system</title>
       <xi:include href="xml/tracker-miner-fs.xml"/>
+      <xi:include href="xml/tracker-file-enumerator.xml"/>
       <xi:include href="xml/tracker-indexing-tree.xml"/>
       <xi:include href="xml/tracker-decorator-fs.xml"/>
     </chapter>
diff --git a/docs/reference/libtracker-miner/libtracker-miner-sections.txt 
b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
index cd3dd11..f2d7892 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-sections.txt
+++ b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
@@ -30,7 +30,7 @@ tracker_indexing_tree_get_type
 
 <SECTION>
 <FILE>tracker-miner</FILE>
-
+TrackerMinerError
 </SECTION>
 
 <SECTION>
@@ -216,3 +216,35 @@ TRACKER_IS_DECORATOR_FS
 TRACKER_IS_DECORATOR_FS_CLASS
 TRACKER_TYPE_DECORATOR_FS
 </SECTION>
+
+<SECTION>
+<FILE>tracker-enumerator</FILE>
+<TITLE>TrackerEnumerator</TITLE>
+TrackerEnumeratorIface
+tracker_enumerator_get_children
+tracker_enumerator_get_children_async
+tracker_enumerator_get_children_finish
+TrackerEnumerator
+<SUBSECTION Standard>
+TRACKER_ENUMERATOR
+TRACKER_ENUMERATOR_GET_IFACE
+TRACKER_IS_ENUMERATOR
+TRACKER_TYPE_ENUMERATOR
+tracker_enumerator_get_type
+</SECTION>
+
+<SECTION>
+<FILE>tracker-file-enumerator</FILE>
+<TITLE>TrackerFileEnumerator</TITLE>
+tracker_file_enumerator_new
+<SUBSECTION Standard>
+TRACKER_FILE_ENUMERATOR
+TRACKER_FILE_ENUMERATOR_CLASS
+TRACKER_FILE_ENUMERATOR_GET_CLASS
+TRACKER_IS_FILE_ENUMERATOR
+TRACKER_IS_FILE_ENUMERATOR_CLASS
+TRACKER_TYPE_FILE_ENUMERATOR
+TrackerFileEnumerator
+TrackerFileEnumeratorClass
+tracker_file_enumerator_get_type
+</SECTION>
diff --git a/src/libtracker-miner/tracker-enumerator.c b/src/libtracker-miner/tracker-enumerator.c
index 5cda32f..cc84849 100644
--- a/src/libtracker-miner/tracker-enumerator.c
+++ b/src/libtracker-miner/tracker-enumerator.c
@@ -25,6 +25,53 @@
 
 #include "tracker-enumerator.h"
 
+/**
+ * SECTION:tracker-enumerator
+ * @short_description: Enumerate URI locations
+ * @include: libtracker-miner/miner.h
+ *
+ * #TrackerEnumerator allows you to operate on a set of #GFiles,
+ * returning a #GFileInfo structure for each file enumerated (e.g.
+ * tracker_enumerator_get_children() will return a #GSList with the
+ * children within a parent directory or structure for the URI.
+ *
+ * This function is similar to g_file_enumerator_next_files_async(),
+ * unlike the g_file_enumerator_next() which will return one #GFile at
+ * a time, this will return all children at once.
+ *
+ * The ordering of returned files is unspecified and dependent on
+ * implementation.
+ *
+ * If your application needs a specific ordering, such as by name or
+ * modification time, you will have to implement that in your
+ * application code.
+ *
+ * There is also a #TrackerFileEnumerator which is an implementation
+ * of this #TrackerEnumerator interface. This makes use of the
+ * #GFileEnumerator API as an example of how to implement your own
+ * enumerator class. Typically, an implementation class (like
+ * #TrackerFileEnumerator) would be used with TrackerCrawler (an
+ * internal class) which feeds URI data for Tracker to insert into the
+ * database.
+ *
+ * The #TrackerMinerFS class which is a subclass to #TrackerMiner
+ * takes a #TrackerEnumerator property which is passed down to the
+ * TrackerCrawler created upon instantiation. This property is
+ * #TrackerMinerFS:enumerator.
+ *
+ * What is important to note about implementations is what is expected
+ * to be returned by an enumerator. There are some simple rules:
+ *
+ * 1. Tracker expects children on a per directory basis only, i.e. not
+ * recursively given for a top level URI. This allows Tracker to
+ * properly construct the database and carry out white/black listing
+ * correctly, amongst other things.
+ * 2. Tracker does not expect the top level URL to be reported in the
+ * children returned. This is considered an error.
+ *
+ * Since: 1.2
+ **/
+
 typedef TrackerEnumeratorIface TrackerEnumeratorInterface;
 G_DEFINE_INTERFACE (TrackerEnumerator, tracker_enumerator, G_TYPE_OBJECT)
 
@@ -33,6 +80,34 @@ tracker_enumerator_default_init (TrackerEnumeratorInterface *iface)
 {
 }
 
+/**
+ * tracker_enumerator_get_children:
+ * @enumerator: a #TrackerEnumerator
+ * @dir: a #GFile to enumerate
+ * @attributes: an attribute query string
+ * @flags: a set of GFileQueryInfoFlags
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @error: location to store the error occurring, or %NULL to ignore
+ *
+ * Enumerates children at the URI provided by @dir.
+ *
+ * The attributes value is a string that specifies the file attributes
+ * that should be gathered. It is not an error if it's not possible to
+ * read a particular requested attribute from a file - it just won't
+ * be set. attributes should be a comma-separated list of attributes
+ * or attribute wildcards. The wildcard "*" means all attributes, and
+ * a wildcard like "standard::*" means all attributes in the standard
+ * namespace. An example attribute query be "standard::*,owner::user".
+ * The standard attributes are available as defines, like
+ * G_FILE_ATTRIBUTE_STANDARD_NAME. See g_file_enumerate_children() for
+ * more details.
+ *
+ * Returns: (transfer full) (element-type Gio.FileInfo): a #GSList of
+ * #GFileInfo pointers. Both must be freed with g_slist_free() and
+ * g_object_unref() when finished with.
+ *
+ * Since: 1.2
+ **/
 GSList *
 tracker_enumerator_get_children (TrackerEnumerator    *enumerator,
                                  GFile                *dir,
@@ -62,6 +137,42 @@ tracker_enumerator_get_children (TrackerEnumerator    *enumerator,
        return (* iface->get_children) (enumerator, dir, attributes, flags, cancellable, error);
 }
 
+/**
+ * tracker_enumerator_get_children_async:
+ * @enumerator: a #TrackerEnumerator.
+ * @dir: a #GFile to enumerate
+ * @attributes: an attribute query string
+ * @flags: a set of GFileQueryInfoFlags
+ * @io_priority: the [I/O priority][io-priority] of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to
+ * ignore
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the
+ * request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Precisely the same operation as tracker_enumerator_get_children()
+ * is performing, but asynchronously.
+ *
+ * When all i/o for the operation is finished the @callback will be
+ * called with the requested information.
+
+ * See the documentation of #TrackerEnumerator for information about the
+ * order of returned files.
+ *
+ * In case of a partial error the callback will be called with any
+ * succeeding items and no error, and on the next request the error
+ * will be reported. If a request is cancelled the callback will be
+ * called with %G_IO_ERROR_CANCELLED.
+ *
+ * During an async request no other sync and async calls are allowed,
+ * and will result in %G_IO_ERROR_PENDING errors.
+ *
+ * Any outstanding i/o request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is %G_PRIORITY_DEFAULT.
+ *
+ * Since: 1.2
+ **/
 void
 tracker_enumerator_get_children_async (TrackerEnumerator    *enumerator,
                                        GFile                *dir,
@@ -86,6 +197,23 @@ tracker_enumerator_get_children_async (TrackerEnumerator    *enumerator,
        (* iface->get_children_async) (enumerator, dir, attributes, flags, io_priority, cancellable, 
callback, user_data);
 }
 
+/**
+ * tracker_enumerator_get_children_finish:
+ * @enumerator: a #TrackerEnumerator.
+ * @result: a #GAsyncResult.
+ * @error: a #GError location to store the error occurring, or %NULL
+ * to ignore.
+ *
+ * Finishes the asynchronous operation started with
+ * tracker_enumerator_get_children_async().
+ *
+ * Returns: (transfer full) (element-type Gio.FileInfo): a #GSList of
+ * #GFileInfos. You must free the list with g_slist_free() and
+ * unref the infos with g_object_unref() when you're done with
+ * them.
+ *
+ * Since: 1.2
+ **/
 GSList *
 tracker_enumerator_get_children_finish (TrackerEnumerator  *enumerator,
                                         GAsyncResult       *result,
diff --git a/src/libtracker-miner/tracker-enumerator.h b/src/libtracker-miner/tracker-enumerator.h
index 22f728a..46a05f9 100644
--- a/src/libtracker-miner/tracker-enumerator.h
+++ b/src/libtracker-miner/tracker-enumerator.h
@@ -35,9 +35,26 @@ G_BEGIN_DECLS
 #define TRACKER_IS_ENUMERATOR(obj)        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), TRACKER_TYPE_ENUMERATOR))
 #define TRACKER_ENUMERATOR_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), TRACKER_TYPE_ENUMERATOR, 
TrackerEnumeratorIface))
 
+/**
+ * TrackerEnumerator:
+ *
+ * An interface to enumerate URIs and feed the data to Tracker.
+ **/
 typedef struct _TrackerEnumerator TrackerEnumerator;
 typedef struct _TrackerEnumeratorIface TrackerEnumeratorIface;
 
+/**
+ * TrackerEnumeratorIface:
+ * @g_iface: Parent interface type.
+ * @get_children: Called when the enumerator is synchronously
+ * retrieving children.
+ * @get_children_async: Called when the enumerator is asynchronously
+ * retrieving children.
+ * @get_children_finish: Called when the enumerator is completing the
+ * asynchronous operation provided by @get_children_async.
+ *
+ * Virtual methods left to implement.
+ **/
 struct _TrackerEnumeratorIface {
        GTypeInterface g_iface;
 
@@ -60,6 +77,16 @@ struct _TrackerEnumeratorIface {
                                          GAsyncResult         *result,
                                          GError              **error);
 
+       /*< private >*/
+       /* Padding for future expansion */
+       void (*_tracker_reserved1) (void);
+       void (*_tracker_reserved2) (void);
+       void (*_tracker_reserved3) (void);
+       void (*_tracker_reserved4) (void);
+       void (*_tracker_reserved5) (void);
+       void (*_tracker_reserved6) (void);
+       void (*_tracker_reserved7) (void);
+       void (*_tracker_reserved8) (void);
 };
 
 GType   tracker_enumerator_get_type             (void) G_GNUC_CONST;
diff --git a/src/libtracker-miner/tracker-file-enumerator.c b/src/libtracker-miner/tracker-file-enumerator.c
index 8251d78..f60162c 100644
--- a/src/libtracker-miner/tracker-file-enumerator.c
+++ b/src/libtracker-miner/tracker-file-enumerator.c
@@ -35,6 +35,20 @@ typedef struct {
        GFileQueryInfoFlags flags;
 } GetChildrenData;
 
+/**
+ * SECTION:tracker-file-enumerator
+ * @short_description: File based enumerator for file:// descendant URIs
+ * @include: libtracker-miner/miner.h
+ *
+ * #TrackerFileEnumerator is a local file implementation of the
+ * #TrackerEnumerator interface, charged with handling all file:// type URIs.
+ *
+ * Underneath it all, this implementation makes use of the
+ * #GFileEnumerator APIs.
+ *
+ * Since: 1.2
+ **/
+
 G_DEFINE_TYPE_WITH_CODE (TrackerFileEnumerator, tracker_file_enumerator, G_TYPE_OBJECT,
                          G_IMPLEMENT_INTERFACE (TRACKER_TYPE_ENUMERATOR,
                                                 tracker_file_enumerator_file_iface_init))
@@ -163,6 +177,11 @@ file_enumerator_get_children (TrackerEnumerator    *enumerator,
                        break;
                }
 
+               g_message ("--> Found:'%s' (%s)",
+                          g_file_info_get_name (info),
+                          g_file_info_get_file_type (info) == G_FILE_TYPE_DIRECTORY ? "Dir" : "File");
+
+
                files = g_slist_prepend (files, info);
        }
 
@@ -243,6 +262,18 @@ tracker_file_enumerator_file_iface_init (TrackerEnumeratorIface *iface)
        iface->get_children_finish = file_enumerator_get_children_finish;
 }
 
+/**
+ * tracker_file_enumerator_new:
+ *
+ * Creates a new TrackerEnumerator which can be used to create new
+ * #TrackerMinerFS classes. See #TrackerMinerFS for an example of how
+ * to use your #TrackerEnumerator.
+ *
+ * Returns: (transfer full): a #TrackerEnumerator which must be
+ * unreferenced with g_object_unref().
+ *
+ * Since: 1.2:
+ **/
 TrackerEnumerator *
 tracker_file_enumerator_new (void)
 {
diff --git a/src/libtracker-miner/tracker-file-enumerator.h b/src/libtracker-miner/tracker-file-enumerator.h
index 4ac3800..750a0a6 100644
--- a/src/libtracker-miner/tracker-file-enumerator.h
+++ b/src/libtracker-miner/tracker-file-enumerator.h
@@ -34,9 +34,20 @@ G_BEGIN_DECLS
 #define TRACKER_IS_FILE_ENUMERATOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), TRACKER_TYPE_FILE_ENUMERATOR))
 #define TRACKER_FILE_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_FILE_ENUMERATOR, 
TrackerFileEnumeratorClass))
 
+/**
+ * TrackerFileEnumerator:
+ *
+ * An implementation of the #TrackerEnumerator interface.
+ **/
 typedef struct _TrackerFileEnumerator        TrackerFileEnumerator;
 typedef struct _TrackerFileEnumeratorClass   TrackerFileEnumeratorClass;
 
+/**
+ * TrackerFileEnumeratorClass:
+ * @parent_class: Parent object class.
+ *
+ * Prototype for the class implementation.
+ **/
 struct _TrackerFileEnumeratorClass {
        GObjectClass parent_class;
 };
diff --git a/src/libtracker-miner/tracker-miner-fs.c b/src/libtracker-miner/tracker-miner-fs.c
index 4b54a5d..9ad5941 100644
--- a/src/libtracker-miner/tracker-miner-fs.c
+++ b/src/libtracker-miner/tracker-miner-fs.c
@@ -109,9 +109,41 @@ static gboolean miner_fs_queues_status_trace_timeout_cb (gpointer data);
  * @include: libtracker-miner/tracker-miner.h
  *
  * #TrackerMinerFS is an abstract base class for miners that collect data
- * from the filesystem, all the filesystem crawling and monitoring is
- * abstracted away, leaving to implementations the decisions of what
- * directories/files should it process, and the actual data extraction.
+ * from a filesystem where parent/child relationships need to be
+ * inserted into the database correctly with queue management.
+ *
+ * All the filesystem crawling and monitoring is abstracted away,
+ * leaving to implementations the decisions of what directories/files
+ * should it process, and the actual data extraction.
+ *
+ * Example creating a TrackerMinerFS with our own file system root and
+ * enumerator.
+ *
+ * First create our class and base it on TrackerMinerFS:
+ * |[
+ * G_DEFINE_TYPE_WITH_CODE (MyMinerFiles, my_miner_files, TRACKER_TYPE_MINER_FS,
+ *                          G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE,
+ *                                                 my_miner_files_initable_iface_init))
+ * ]|
+ *
+ * Later in our class creation function, we are supplying the
+ * arguments we want. In this case, the 'root' is a #GFile pointing to
+ * a root URI location (for example 'file:///') and 'enumerator' is a
+ * #TrackerEnumerator used to enumerate 'root' and return children it
+ * finds. If 'enumerator' is %NULL (the default), then a
+ * #TrackerFileEnumerator is created automatically.
+ * |[
+ * // Note that only 'name' is mandatory
+ * miner = g_initable_new (MY_TYPE_MINER_FILES,
+ *                         NULL,
+ *                         error,
+ *                         "name", "MyMinerFiles",
+ *                         "root", root,
+ *                         "enumerator", enumerator,
+ *                         "processing-pool-wait-limit", 10,
+ *                         "processing-pool-ready-limit", 100,
+ *                         NULL);
+ * ]|
  **/
 
 #define TRACKER_MINER_FS_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), TRACKER_TYPE_MINER_FS, 
TrackerMinerFSPrivate))
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]