TrackerEnumerator

TrackerEnumerator — Enumerate resources

Functions

Types and Values

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

GTypeInterface g_iface;

Parent interface type.

 

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.