TrackerIndexingTree: Tracker Miner Library Reference Manual

## TrackerIndexingTree TrackerIndexingTree — Indexing tree handling |

## Functions

TrackerIndexingTree * | tracker_indexing_tree_new ()
TrackerIndexingTree * | tracker_indexing_tree_new_with_root ()
void | tracker_indexing_tree_add ()
void | tracker_indexing_tree_remove ()
void | tracker_indexing_tree_add_filter ()
void | tracker_indexing_tree_clear_filters ()
gboolean | tracker_indexing_tree_file_matches_filter ()
gboolean | tracker_indexing_tree_file_is_indexable ()
gboolean | tracker_indexing_tree_parent_is_indexable ()
gboolean | tracker_indexing_tree_get_filter_hidden ()
void | tracker_indexing_tree_set_filter_hidden ()
TrackerFilterPolicy | tracker_indexing_tree_get_default_policy ()
void | tracker_indexing_tree_set_default_policy ()
GFile * | tracker_indexing_tree_get_root ()
GFile * | tracker_indexing_tree_get_master_root ()
gboolean | tracker_indexing_tree_file_is_root ()
GList * | tracker_indexing_tree_list_roots ()

## Properties

gboolean | filter-hidden | Read / Write
GFile * | root | Read / Write / Construct Only

## Signals

void | directory-added | Run Last
void | directory-removed | Run Last
void | directory-updated | Run Last

## Types and Values

struct | TrackerIndexingTree
| TrackerIndexingTreeClass

## Object Hierarchy

        GObject
        ╰── TrackerIndexingTree

## Description

TrackerIndexingTree handles the tree of directories configured to be indexed by the TrackerMinerFS.

## Functions

### tracker_indexing_tree_new ()

    TrackerIndexingTree *
    tracker_indexing_tree_new (void);

Returns a newly created TrackerIndexingTree

#### Returns

a newly allocated TrackerIndexingTree

Since: 0.14.0

### tracker_indexing_tree_new_with_root ()

    TrackerIndexingTree *
    tracker_indexing_tree_new_with_root (GFile *root);

If `root` is `NULL`, the default value is 'file:///'. Using `NULL` here is the equivalent to calling `tracker_indexing_tree_new()` which takes no `root` argument.

#### Parameters

root | The top level URL |

#### Returns

a newly allocated TrackerIndexingTree

Since: 1.2.2

### tracker_indexing_tree_add ()

    void
    tracker_indexing_tree_add (TrackerIndexingTree *tree,
                               GFile *directory,
                               TrackerDirectoryFlags flags);

Adds a directory to the indexing tree with the given configuration flags.

#### Parameters

tree | a TrackerIndexingTree |
directory | GFile pointing to a directory |
flags | Configuration flags for the directory |

### tracker_indexing_tree_remove ()

    void
    tracker_indexing_tree_remove (TrackerIndexingTree *tree,
                                  GFile *directory);

Removes `directory` from the indexing tree, note that only directories previously added with `tracker_indexing_tree_add()` can be effectively removed.

#### Parameters

tree | a TrackerIndexingTree |
directory | GFile pointing to a directory |

### tracker_indexing_tree_add_filter ()

    void
    tracker_indexing_tree_add_filter (TrackerIndexingTree *tree,
                                      TrackerFilterType filter,
                                      const gchar *glob_string);

Adds a new filter for basenames.

#### Parameters

tree | a TrackerIndexingTree |
filter | filter type |
glob_string | glob-style string for the filter |

### tracker_indexing_tree_clear_filters ()

    void
    tracker_indexing_tree_clear_filters (TrackerIndexingTree *tree,
                                         TrackerFilterType type);

Clears all filters of a given type.

#### Parameters

tree | a TrackerIndexingTree |
type | filter type to clear |

### tracker_indexing_tree_file_matches_filter ()

    gboolean
    tracker_indexing_tree_file_matches_filter
                                   (TrackerIndexingTree *tree,
                                    TrackerFilterType type,
                                    GFile *file);

Returns `TRUE` if `file` matches any filter of the given filter type.

#### Parameters

tree | a TrackerIndexingTree |
type | filter type |
file | a GFile |

#### Returns

`TRUE` if `file` is filtered.

### tracker_indexing_tree_file_is_indexable ()

    gboolean
    tracker_indexing_tree_file_is_indexable
                                   (TrackerIndexingTree *tree,
                                    GFile *file,
                                    GFileType file_type);

returns `TRUE` if `file` should be indexed according to the parameters given through `tracker_indexing_tree_add()` and `tracker_indexing_tree_add_filter()`.

If `file_type` is G_FILE_TYPE_UNKNOWN, file type will be queried to the file system.

#### Parameters

tree | a TrackerIndexingTree |
file | a GFile |
file_type | a GFileType |

#### Returns

`TRUE` if `file` should be indexed.

### tracker_indexing_tree_parent_is_indexable ()

    gboolean
    tracker_indexing_tree_parent_is_indexable
                                   (TrackerIndexingTree *tree,
                                    GFile *parent,
                                    GList *children);

returns `TRUE` if `parent` should be indexed based on its contents.

#### Parameters

tree | a TrackerIndexingTree |
parent | parent directory |
children | children within `parent` . | [element-type GFile]

#### Returns

`TRUE` if `parent` should be indexed.

### tracker_indexing_tree_get_filter_hidden ()

    gboolean
    tracker_indexing_tree_get_filter_hidden
                                   (TrackerIndexingTree *tree);

Describes if the `tree` should index hidden content. To change this setting, see `tracker_indexing_tree_set_filter_hidden()`.

#### Parameters

tree | a TrackerIndexingTree |

#### Returns

`FALSE` if hidden files are indexed, otherwise `TRUE`.

Since: 0.18.

### tracker_indexing_tree_set_filter_hidden ()

    void
    tracker_indexing_tree_set_filter_hidden
                                   (TrackerIndexingTree *tree,
                                    gboolean filter_hidden);

When indexing content, sometimes it is preferable to ignore hidden content, for example, files prefixed with ".". This is common for files in a home directory which are usually config files.

Sets the indexing policy for `tree` with hidden files and content. To ignore hidden files, `filter_hidden` should be `TRUE`, otherwise `FALSE`.

#### Parameters

tree | a TrackerIndexingTree |
filter_hidden | a boolean |

Since: 0.18.

### tracker_indexing_tree_get_default_policy ()

    TrackerFilterPolicy
    tracker_indexing_tree_get_default_policy
                                   (TrackerIndexingTree *tree,
                                    TrackerFilterType filter);

Get the default filtering policies for `tree` when indexing content. Some content is black listed or white listed and the default policy for that is returned here. The `filter` allows specific type of policies to be returned, for example, the default policy for files (TRACKER_FILTER_FILE).

#### Parameters

tree | a TrackerIndexingTree |
filter | a TrackerFilterType |

#### Returns

Either TRACKER_FILTER_POLICY_DENY or TRACKER_FILTER_POLICY_ALLOW.

Since: 0.18.

### tracker_indexing_tree_set_default_policy ()

    void
    tracker_indexing_tree_set_default_policy
                                   (TrackerIndexingTree *tree,
                                    TrackerFilterType filter,
                                    TrackerFilterPolicy policy);

Set the default `policy` (to allow or deny) for content in `tree` based on the type - in this case `filter` . Here, `filter` is a file or directory and there are some other options too.

For example, you can (by default), disable indexing all directories using this function.

#### Parameters

tree | a TrackerIndexingTree |
filter | a TrackerFilterType |
policy | a TrackerFilterPolicy |

Since: 0.18.

### tracker_indexing_tree_get_root ()

    GFile *
    tracker_indexing_tree_get_root (TrackerIndexingTree *tree,
                                    GFile *file,
                                    TrackerDirectoryFlags *directory_flags);

Returns the GFile that was previously added through `tracker_indexing_tree_add()` and would equal or contain `file` , or `NULL` if none applies.

If the return value is non-`NULL`, `directory_flags` would contain the TrackerDirectoryFlags applying to `file` .

#### Parameters

tree | a TrackerIndexingTree |
file | a GFile |
directory_flags | return location for the applying TrackerDirectoryFlags. | [out]

#### Returns

the effective parent in `tree` , or `NULL`.

[transfer none]

### tracker_indexing_tree_get_master_root ()

    GFile *
    tracker_indexing_tree_get_master_root (TrackerIndexingTree *tree);

Returns the GFile that represents the master root location for all indexing locations. For example, if `file:///etc` is an indexed path and so was `file:///home/user`, the master root is `file:///`. Only one scheme per `tree` can be used, so you can not mix `http` and `file` roots in `tree` .

The return value should NEVER be `NULL`. In cases where no root is given, we fallback to `file:///`.

Roots explained:

- master root = top most level root node, e.g. file:///

- config root = a root node from GSettings, e.g. file:///home/martyn/Documents

- root = ANY root, normally config root, but it can also apply to roots added for devices, which technically are not a config root or a master root.

#### Parameters

tree | a TrackerIndexingTree |

#### Returns

the effective root for all locations, or `NULL` on error. The root is owned by `tree` and should not be freed. It can be referenced using `g_object_ref()`.

[transfer none]

Since: 1.2.

### tracker_indexing_tree_file_is_root ()

    gboolean
    tracker_indexing_tree_file_is_root (TrackerIndexingTree *tree,
                                        GFile *file);

Evaluates if the URL represented by `file` is the same of that for the root of the `tree` .

#### Parameters

tree | a TrackerIndexingTree |
file | a GFile to compare |

#### Returns

`TRUE` if `file` matches the URL canonically, otherwise `FALSE`.

Since: 1.2.

### tracker_indexing_tree_list_roots ()

    GList *
    tracker_indexing_tree_list_roots (TrackerIndexingTree *tree);

Returns the list of indexing roots in `tree`

#### Parameters

tree | a TrackerIndexingTree |

#### Returns

The list of roots, the list itself must be freed with `g_list_free()`, the list elements are owned by `tree` and should not be freed.

[transfer container][element-type GFile]

## Types and Values

### struct TrackerIndexingTree

    struct TrackerIndexingTree;

Base object used to configure indexing within TrackerMinerFS items.

### TrackerIndexingTreeClass

    typedef struct {
    	GObjectClass parent_class;

    	void (* directory_added)   (TrackerIndexingTree *indexing_tree,
    	                            GFile               *directory);
    	void (* directory_removed) (TrackerIndexingTree *indexing_tree,
    	                            GFile               *directory);
    	void (* directory_updated) (TrackerIndexingTree *indexing_tree,
    	                            GFile               *directory);

    	/* <Private> */
    	gpointer padding[10];
    } TrackerIndexingTreeClass;

Class for the TrackerIndexingTree.

#### Members

GObjectClass `parent_class`; | parent object class |
`directory_added` () | Called when a directory is added. |
`directory_removed` () | Called when a directory is removed. |
`directory_updated` () | Called when a directory is updated. |
gpointer `padding`[10]; | Reserved for future API improvements. |

## Property Details

### The `“filter-hidden”` property

      “filter-hidden”            gboolean

Whether hidden resources are filtered.

Flags: Read / Write

Default value: FALSE

### The `“root”` property

      “root”                     GFile *

The root GFile for the indexing tree.

Flags: Read / Write / Construct Only

## Signal Details

### The `“directory-added”` signal

    void
    user_function (TrackerIndexingTree *indexing_tree,
                   GFile               *directory,
                   gpointer             user_data)

the ::directory-added signal is emitted when a new directory is added to the list of other directories which are to be considered for indexing. Typically this is signalled when the `tracker_indexing_tree_add()` API is called.

#### Parameters

indexing_tree | a TrackerIndexingTree |
directory | a GFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.14.0

### The `“directory-removed”` signal

    void
    user_function (TrackerIndexingTree *indexing_tree,
                   GFile               *directory,
                   gpointer             user_data)

the ::directory-removed signal is emitted when a directory is removed from the list of other directories which are to be considered for indexing. Typically this is signalled when the `tracker_indexing_tree_remove()` API is called.

#### Parameters

indexing_tree | a TrackerIndexingTree |
directory | a GFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.14.0

### The `“directory-updated”` signal

    void
    user_function (TrackerIndexingTree *indexing_tree,
                   GFile               *directory,
                   gpointer             user_data)

the ::directory-updated signal is emitted when `directory` that was previously added has had its indexing flags updated due to another directory that is a parent of `directory` changing. This tends to happen uppon `tracker_indexing_tree_add()` API calls.

#### Parameters

indexing_tree | a TrackerIndexingTree |
directory | a GFile |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.14.0