## TrackerMinerFS

TrackerMinerFS — Abstract base class for filesystem miners

## Synopsis

    #include <libtracker-miner/tracker-miner-fs.h>

    typedef             TrackerMinerFSPrivate;
    typedef             TrackerMinerFS;
                        TrackerMinerFSClass;
    const gchar *       tracker_miner_fs_get_parent_urn     (TrackerMinerFS *fs,
                                                             GFile *file);
    const gchar *       tracker_miner_fs_get_urn            (TrackerMinerFS *fs,
                                                             GFile *file);
    void                tracker_miner_fs_directory_add      (TrackerMinerFS *fs,
                                                             GFile *file,
                                                             gboolean recurse);
    gboolean            tracker_miner_fs_directory_remove   (TrackerMinerFS *fs,
                                                             GFile *file);
    void                tracker_miner_fs_file_add           (TrackerMinerFS *fs,
                                                             GFile *file);
    void                tracker_miner_fs_file_notify        (TrackerMinerFS *fs,
                                                             GFile *file,
                                                             const GError *error);
    void                tracker_miner_fs_set_throttle       (TrackerMinerFS *fs,
                                                             gdouble throttle);
    gdouble             tracker_miner_fs_get_throttle       (TrackerMinerFS *fs);

## Object Hierarchy

      GObject
       +----TrackerMiner
             +----TrackerMinerFS

## Properties

      "process-pool-limit"       guint                 : Read / Write / Construct
      "throttle"                 gdouble               : Read / Write

## Signals

      "check-directory"                                : Run Last
      "check-directory-contents"                       : Run Last
      "check-file"                                     : Run Last
      "finished"                                       : Run Last
      "ignore-next-update-file"                        : Run Last
      "monitor-directory"                              : Run Last
      "process-file"                                   : Run Last

## Description

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.

## Details

### TrackerMinerFSPrivate

    typedef struct TrackerMinerFSPrivate TrackerMinerFSPrivate;

### TrackerMinerFS

    typedef struct TrackerMinerFS        TrackerMinerFS;

Abstract miner abstract implementation to get data from the filesystem.

### TrackerMinerFSClass

    typedef struct {
    	TrackerMinerClass parent;

    	gboolean (* check_file)               (TrackerMinerFS       *fs,
                                                   GFile                *file);
    	gboolean (* check_directory)          (TrackerMinerFS       *fs,
                                                   GFile                *file);
    	gboolean (* check_directory_contents) (TrackerMinerFS       *fs,
    	                                       GFile                *parent,
    	                                       GList                *children);
    	gboolean (* process_file)             (TrackerMinerFS       *fs,
                                                   GFile                *file,
                                                   TrackerSparqlBuilder *builder,
                                                   GCancellable         *cancellable);
    	gboolean (* ignore_next_update_file)  (TrackerMinerFS       *fs,
                                                   GFile                *file,
                                                   TrackerSparqlBuilder *builder,
                                                   GCancellable         *cancellable);
    	gboolean (* monitor_directory)        (TrackerMinerFS       *fs,
                                                   GFile                *file);
    	void     (* finished)                 (TrackerMinerFS       *fs);
    } TrackerMinerFSClass;

Prototype for the abstract class, `check_file`, `check_directory`, `check_directory_contents`, `process_file` and `monitor_directory` must be implemented in the deriving class in order to actually extract data.

TrackerMinerClass `parent`; | parent object class
`check_file` () | Called when a file should be checked for further processing
`check_directory` () | Called when a directory should be checked for further processing
`check_directory_contents` () | Called when a directory should be checked for further processing, based on the directory contents.
`process_file` () | Called when the metadata associated to a file is requested.
`ignore_next_update_file` () | Called after a writeback event happens on a file.
`monitor_directory` () | Called to check whether a directory should be modified.
`finished` () | Called when all processing has been performed.

### tracker_miner_fs_get_parent_urn ()

    const gchar *       tracker_miner_fs_get_parent_urn     (TrackerMinerFS *fs,
                                                             GFile *file);

If `file` is currently being processed by `fs`, this function will return the parent folder URN if any. This function is useful to set the nie:belongsToContainer relationship. The processing order of TrackerMinerFS guarantees that a folder has been already fully processed for indexing before any children is processed, so most usually this function should return non-`NULL`.

`fs` : | a TrackerMinerFS
`file` : | a GFile obtained in "process-file"
Returns : | The parent folder URN, or `NULL`.

### tracker_miner_fs_get_urn ()

    const gchar *       tracker_miner_fs_get_urn            (TrackerMinerFS *fs,
                                                             GFile *file);

If the item exists in the store, this function retrieves the URN for a GFile being currently processed.

If `file` is not being currently processed by `fs`, or doesn't exist in the store yet, `NULL` will be returned.

`fs` : | a TrackerMinerFS
`file` : | a GFile obtained in "process-file"
Returns : | The URN containing the data associated to `file`, or `NULL`.

### tracker_miner_fs_directory_add ()

    void                tracker_miner_fs_directory_add      (TrackerMinerFS *fs,
                                                             GFile *file,
                                                             gboolean recurse);

Tells the filesystem miner to inspect a directory.

`fs` : | a TrackerMinerFS
`file` : | GFile for the directory to inspect
`recurse` : | whether the directory should be inspected recursively

### tracker_miner_fs_directory_remove ()

    gboolean            tracker_miner_fs_directory_remove   (TrackerMinerFS *fs,
                                                             GFile *file);

Removes a directory from being inspected by `fs`.

`fs` : | a TrackerMinerFS
`file` : | GFile for the directory to be removed
Returns : | `TRUE` if the directory was successfully removed.

### tracker_miner_fs_file_add ()

    void                tracker_miner_fs_file_add           (TrackerMinerFS *fs,
                                                             GFile *file);

Tells the filesystem miner to inspect a file.

`fs` : | a TrackerMinerFS
`file` : | GFile for the file to inspect

### tracker_miner_fs_file_notify ()

    void                tracker_miner_fs_file_notify        (TrackerMinerFS *fs,
                                                             GFile *file,
                                                             const GError *error);

Notifies `fs` that all processing on `file` has been finished, if any error happened during file data processing, it should be passed in `error`, else that parameter will contain `NULL` to reflect success.

`fs` : | a TrackerMinerFS
`file` : | a GFile
`error` : | a GError with the error that happened during processing, or `NULL`.

### tracker_miner_fs_set_throttle ()

    void                tracker_miner_fs_set_throttle       (TrackerMinerFS *fs,
                                                             gdouble throttle);

Tells the filesystem miner to throttle its operations. a value of 0 means no throttling at all, so the miner will perform operations at full speed, 1 is the slowest value.

`fs` : | a TrackerMinerFS
`throttle` : | throttle value, between 0 and 1

### tracker_miner_fs_get_throttle ()

    gdouble             tracker_miner_fs_get_throttle       (TrackerMinerFS *fs);

Gets the current throttle value. see `tracker_miner_fs_set_throttle()`.

`fs` : | a TrackerMinerFS
Returns : | current throttle value.

## Property Details

### The `"process-pool-limit"` property

      "process-pool-limit"       guint                 : Read / Write / Construct

Number of files that can be concurrently processed.

Allowed values: >= 1

Default value: 1

### The `"throttle"` property

      "throttle"                 gdouble               : Read / Write

Modifier for the indexing speed, 0 is max speed.

Allowed values: [0,1]

Default value: 0

## Signal Details

### The `"check-directory"` signal

    gboolean            user_function                      (TrackerMinerFS *miner_fs,
                                                            GFile          *directory,
                                                            gpointer        user_data)      : Run Last

The ::check-directory signal is emitted either on the filesystem crawling phase or whenever a new directory appears in a monitored directory in order to check whether `directory` must be inspected my `miner_fs`.

`miner_fs` : | the TrackerMinerFS
`directory` : | a GFile
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if `directory` must be inspected.

### The `"check-directory-contents"` signal

    gboolean            user_function                      (TrackerMinerFS *miner_fs,
                                                            GFile          *directory,
                                                            gpointer        children,
                                                            gpointer        user_data)      : Run Last

The ::check-directory-contents signal is emitted either on the filesystem crawling phase or whenever a new directory appears in a monitored directory in order to check whether `directory` must be inspected my `miner_fs` based on the directory contents, for some implementations this signal may be useful to discard backup directories for example.

`miner_fs` : | the TrackerMinerFS
`directory` : | a GFile
`children` : | GList of GFiles
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if `directory` must be inspected.

### The `"check-file"` signal

    gboolean            user_function                      (TrackerMinerFS *miner_fs,
                                                            GFile          *file,
                                                            gpointer        user_data)      : Run Last

The ::check-file signal is emitted either on the filesystem crawling phase or whenever a new file appears in a monitored directory in order to check whether `file` must be inspected my `miner_fs`.

`miner_fs` : | the TrackerMinerFS
`file` : | a GFile
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if `file` must be inspected.

### The `"finished"` signal

    void                user_function                      (TrackerMinerFS *miner_fs,
                                                            gdouble         elapsed,
                                                            guint           directories_found,
                                                            guint           directories_ignored,
                                                            guint           files_found,
                                                            guint           files_ignored,
                                                            gpointer        user_data)                : Run Last

The ::finished signal is emitted when `miner_fs` has finished all pending processing.

`miner_fs` : | the TrackerMinerFS
`elapsed` : | elapsed time since mining was started
`directories_found` : | number of directories found
`directories_ignored` : | number of ignored directories
`files_found` : | number of files found
`files_ignored` : | number of ignored files
`user_data` : | user data set when the signal handler was connected.

### The `"ignore-next-update-file"` signal

    gboolean            user_function                      (TrackerMinerFS       *miner_fs,
                                                            GFile                *file,
                                                            TrackerSparqlBuilder *builder,
                                                            GCancellable         *cancellable,
                                                            gpointer              user_data)        : Run Last

The ::ignore-next-update-file signal is emitted whenever a file should be marked as to ignore on next update, and it's metadata prepared for that.

`builder` is the TrackerSparqlBuilder where all sparql updates to be performed for `file` will be appended.

`miner_fs` : | the TrackerMinerFS
`file` : | a GFile
`builder` : | a TrackerSparqlBuilder
`cancellable` : | a GCancellable
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` on success `FALSE` on failure

### The `"monitor-directory"` signal

    gboolean            user_function                      (TrackerMinerFS *miner_fs,
                                                            GFile          *directory,
                                                            gpointer        user_data)      : Run Last

The ::monitor-directory is emitted either on the filesystem crawling phase or whenever a new directory appears in a monitored directory in order to check whether `directory` must be monitored for filesystem changes or not.

`miner_fs` : | the TrackerMinerFS
`directory` : | a GFile
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the directory must be monitored for changes.

### The `"process-file"` signal

    gboolean            user_function                      (TrackerMinerFS       *miner_fs,
                                                            GFile                *file,
                                                            TrackerSparqlBuilder *builder,
                                                            GCancellable         *cancellable,
                                                            gpointer              user_data)        : Run Last

The ::process-file signal is emitted whenever a file should be processed, and it's metadata extracted.

`builder` is the TrackerSparqlBuilder where all sparql updates to be performed for `file` will be appended.

This signal allows both synchronous and asynchronous extraction, in the synchronous case `cancellable` can be safely ignored. In either case, on successful metadata extraction, implementations must call `tracker_miner_fs_file_notify()` to indicate that processing has finished on `file`, so the miner can execute the SPARQL updates and continue processing other files.

`miner_fs` : | the TrackerMinerFS
`file` : | a GFile
`builder` : | a TrackerSparqlBuilder
`cancellable` : | a GCancellable
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` if the file is accepted for processing, `FALSE` if the file should be ignored.