TrackerDataProvider: Tracker Miner Library Reference Manual

## TrackerDataProvider TrackerDataProvider — Provide data to be indexed |

## Functions

TrackerEnumerator * | tracker_data_provider_begin ()
void | tracker_data_provider_begin_async ()
TrackerEnumerator * | tracker_data_provider_begin_finish ()
gboolean | tracker_data_provider_end ()
void | tracker_data_provider_end_async ()
gboolean | tracker_data_provider_end_finish ()

## Types and Values

struct | TrackerDataProviderIface
| TrackerDataProvider

## Object Hierarchy

        GInterface
        ╰── TrackerDataProvider

## Prerequisites

TrackerDataProvider requires GObject.

## Includes

    #include <libtracker-miner/miner.h>

## Description

TrackerDataProvider allows you to operate on a set of GFiles, returning a GFileInfo structure for each file enumerated (e.g. `tracker_data_provider_begin()` will return a TrackerEnumerator which can be used to enumerate resources provided by the TrackerDataProvider.

There is also a TrackerFileDataProvider which is an implementation of this TrackerDataProvider interface.

The TrackerMinerFS class which is a subclass to TrackerMiner takes a TrackerDataProvider property which is passed down to the TrackerCrawler created upon instantiation. This property is “data-provider”.

See the TrackerEnumerator documentation for more details.

## Functions

### tracker_data_provider_begin ()

    TrackerEnumerator *
    tracker_data_provider_begin (TrackerDataProvider *data_provider,
                                 GFile *url,
                                 const gchar *attributes,
                                 TrackerDirectoryFlags flags,
                                 GCancellable *cancellable,
                                 GError **error);

Creates a TrackerEnumerator to enumerate children at the URI provided by `url` .

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.

#### Parameters

data_provider | a TrackerDataProvider |
url | a GFile to enumerate |
attributes | an attribute query string |
flags | a set of TrackerDirectoryFlags |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

a TrackerEnumerator or `NULL` on failure. This must be freed with `g_object_unref()`.

[transfer full]

Since: 1.2

### tracker_data_provider_begin_async ()

    void
    tracker_data_provider_begin_async (TrackerDataProvider *data_provider,
                                       GFile *url,
                                       const gchar *attributes,
                                       TrackerDirectoryFlags flags,
                                       gint io_priority,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Precisely the same operation as `tracker_data_provider_begin()` 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 TrackerDataProvider 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`.

#### Parameters

data_provider | a TrackerDataProvider. |
url | a GFile to enumerate |
attributes | an attribute query string |
flags | a set of TrackerDirectoryFlags |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 1.2

### tracker_data_provider_begin_finish ()

    TrackerEnumerator *
    tracker_data_provider_begin_finish (TrackerDataProvider *data_provider,
                                        GAsyncResult *result,
                                        GError **error);

Finishes the asynchronous operation started with `tracker_data_provider_begin_async()`.

#### Parameters

data_provider | a TrackerDataProvider. |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

a TrackerEnumerator or `NULL` on failure. This must be freed with `g_object_unref()`.

[transfer full]

Since: 1.2

### tracker_data_provider_end ()

    gboolean
    tracker_data_provider_end (TrackerDataProvider *data_provider,
                               TrackerEnumerator *enumerator,
                               GCancellable *cancellable,
                               GError **error);

Closes any caches or operations related to creating the TrackerEnumerator to enumerate data at `url` .

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.

#### Parameters

data_provider | a TrackerDataProvider |
enumerator | a TrackerEnumerator originally created by `tracker_data_provider_begin()`. |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

`TRUE` on success, otherwise `FALSE` and `error` is set.

Since: 1.2

### tracker_data_provider_end_async ()

    void
    tracker_data_provider_end_async (TrackerDataProvider *data_provider,
                                     TrackerEnumerator *enumerator,
                                     gint io_priority,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Precisely the same operation as `tracker_data_provider_end()` 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 TrackerDataProvider 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`.

#### Parameters

data_provider | a TrackerDataProvider. |
enumerator | a TrackerEnumerator originally created by `tracker_data_provider_begin()`. |
io_priority | the I/O priority of the request |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
callback | a GAsyncReadyCallback to call when the request is satisfied. | [scope async]
user_data | the data to pass to callback function. | [closure]

Since: 1.2

### tracker_data_provider_end_finish ()

    gboolean
    tracker_data_provider_end_finish (TrackerDataProvider *data_provider,
                                      GAsyncResult *result,
                                      GError **error);

Finishes the asynchronous operation started with `tracker_data_provider_end_async()`.

#### Parameters

data_provider | a TrackerDataProvider. |
result | a GAsyncResult. |
error | a GError location to store the error occurring, or `NULL` to ignore. |

#### Returns

`TRUE` on success, otherwise `FALSE` and `error` is set.

Since: 1.2

## Types and Values

### struct TrackerDataProviderIface

    struct TrackerDataProviderIface {
    	GTypeInterface g_iface;

    	/* Virtual Table */

    	/* Start the data_provider for a given location, attributes and flags */
    	TrackerEnumerator *   (* begin)              (TrackerDataProvider    *data_provider,
    	                                              GFile                  *url,
    	                                              const gchar            *attributes,
    	                                              TrackerDirectoryFlags   flags,
    	                                              GCancellable           *cancellable,
    	                                              GError                **error);
    	void                  (* begin_async)        (TrackerDataProvider    *data_provider,
    	                                              GFile                  *url,
    	                                              const gchar            *attributes,
    	                                              TrackerDirectoryFlags   flags,
    	                                              gint                    io_priority,
    	                                              GCancellable           *cancellable,
    	                                              GAsyncReadyCallback     callback,
    	                                              gpointer                user_data);
    	TrackerEnumerator *   (* begin_finish)       (TrackerDataProvider    *data_provider,
    	                                              GAsyncResult           *result,
    	                                              GError                **error);

    	/* Close the given location */
    	gboolean              (* end)                (TrackerDataProvider    *data_provider,
    	                                              TrackerEnumerator      *enumerator,
    	                                              GCancellable           *cancellable,
    	                                              GError                **error);
    	void                  (* end_async)          (TrackerDataProvider    *data_provider,
    	                                              TrackerEnumerator      *enumerator,
    	                                              gint                    io_priority,
    	                                              GCancellable           *cancellable,
    	                                              GAsyncReadyCallback     callback,
    	                                              gpointer                user_data);
    	gboolean              (* end_finish)         (TrackerDataProvider    *data_provider,
    	                                              GAsyncResult           *result,
    	                                              GError                **error);
    };

Virtual methods left to implement.

#### Members

`begin` () | Called when the data_provider is synchronously opening and starting the iteration of a given location. |
`begin_async` () | Called when the data_provider is synchronously opening and starting the iteration of a given location. Completed using `begin_finish` . |
`begin_finish` () | Called when the data_provider is completing the asynchronous operation provided by `begin_async` . |
`end` () | Called when the data_provider is synchronously closing and cleaning up the iteration of a given location. |
`end_async` () | Called when the data_provider is asynchronously closing and cleaning up the iteration of a given location. Completed using `end_finish` . |
`end_finish` () | Called when the data_provider is completing the asynchronous operation provided by `end_async` . |

### TrackerDataProvider

    typedef struct _TrackerDataProvider TrackerDataProvider;

An interface to enumerate URIs and feed the data to Tracker.