TrackerEnumerator: Tracker Miner Library Reference Manual

## TrackerEnumerator TrackerEnumerator — Enumerate resources |

## Functions

gpointer | tracker_enumerator_next ()
void | tracker_enumerator_next_async ()
gpointer | tracker_enumerator_next_finish ()

## Types and Values

struct | TrackerEnumeratorIface
| TrackerEnumerator

## Includes

    #include <libtracker-miner/miner.h>

## Description

TrackerEnumerator allows you to iterate content or resources.

The common example use case for TrackerEnumerator would be to operate on a set of GFiles, returning a GFileInfo structure for each file enumerated (e.g. `tracker_enumerator_next()` would return a GFileInfo for each resource found in a parent folder or container).

The ordering of returned content 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 a TrackerFileEnumerator which is an implementation of the 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.

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 resources on a per container (or 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.

See the TrackerDataProvider documentation for more details.

## Functions

### tracker_enumerator_next ()

    gpointer
    tracker_enumerator_next (TrackerEnumerator *enumerator,
                             GCancellable *cancellable,
                             GError **error);

Enumerates to the next piece of data according to the `enumerator` implementation.

#### Parameters

enumerator | a TrackerEnumerator |
cancellable | optional GCancellable object, `NULL` to ignore. | [allow-none]
error | location to store the error occurring, or `NULL` to ignore |

#### Returns

Returns a gpointer with the next item from the `enumerator` , or `NULL` when `error` is set or the operation was cancelled in `cancellable` . The data must be freed. The function to free depends on the data returned by the enumerator and the TrackerDataProvider that created the `enumerator` .

[transfer full]

Since: 1.2

### tracker_enumerator_next_async ()

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

Precisely the same operation as `tracker_enumerator_next()` is performing, but asynchronously.

When all i/o for the operation is finished the `callback` will be called with the requested information.

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

enumerator | a TrackerEnumerator. |
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_enumerator_next_finish ()

    gpointer
    tracker_enumerator_next_finish (TrackerEnumerator *enumerator,
                                    GAsyncResult *result,
                                    GError **error);

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

#### Parameters

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

#### Returns

Returns a gpointer with the next item from the `enumerator` , or `NULL` when `error` is set or the operation was cancelled in `cancellable` . The data must be freed. The function to free depends on the data returned by the enumerator and the TrackerDataProvider that created the `enumerator` .

[transfer full]

Since: 1.2

## Types and Values

### struct TrackerEnumeratorIface

    struct TrackerEnumeratorIface {
    	GTypeInterface g_iface;

    	/* Virtual Table */
    	gpointer          (* next)        (TrackerEnumerator    *enumerator,
    	                                   GCancellable         *cancellable,
    	                                   GError              **error);
    	void              (* next_async)  (TrackerEnumerator    *enumerator,
    	                                   gint                  io_priority,
    	                                   GCancellable         *cancellable,
    	                                   GAsyncReadyCallback   callback,
    	                                   gpointer              user_data);
    	gpointer          (* next_finish) (TrackerEnumerator    *enumerator,
    	                                   GAsyncResult         *result,
    	                                   GError              **error);
    };

Virtual methods left to implement.

#### Members

`next` () | Called when the enumerator is synchronously retrieving the next resource to be iterated. |
`next_async` () | Called when the enumerator is asynchronously retrieving the next resource to be iterated. Completed using `next_finish` . |
`next_finish` () | Called when the enumerator is completing the asynchronous operation provided by `next_async` . |

### TrackerEnumerator

    typedef struct _TrackerEnumerator TrackerEnumerator;

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