Top | ![]() |
![]() |
![]() |
![]() |
gpointer | tracker_enumerator_next () |
void | tracker_enumerator_next_async () |
gpointer | tracker_enumerator_next_finish () |
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:
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.
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.
gpointer tracker_enumerator_next (TrackerEnumerator *enumerator
,GCancellable *cancellable
,GError **error
);
Enumerates to the next piece of data according to the enumerator
implementation.
enumerator |
||
cancellable |
optional GCancellable object, |
[allow-none] |
error |
location to store the error occurring, or |
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
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
.
enumerator |
||
io_priority |
the I/O priority of the request |
|
cancellable |
optional GCancellable object, |
[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
gpointer tracker_enumerator_next_finish (TrackerEnumerator *enumerator
,GAsyncResult *result
,GError **error
);
Finishes the asynchronous operation started with
tracker_enumerator_next_async()
.
enumerator |
||
result |
a GAsyncResult. |
|
error |
a GError location to store the error occurring, or |
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
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.
Called when the enumerator is synchronously retrieving the next resource to be iterated. |
||
Called when the enumerator is asynchronously
retrieving the next resource to be iterated. Completed using
|
||
Called when the enumerator is completing the
asynchronous operation provided by |