## Resources

Resources — Doing SPARQL queries to tracker-store.

## Synopsis

    #include <libtracker-client/tracker-client.h>

    void                (*TrackerReplyGPtrArray)            (GPtrArray *result,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*TrackerReplyVoid)                 (GError *error,
                                                             gpointer user_data);
    GPtrArray *         tracker_resources_sparql_query      (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);
    guint               tracker_resources_sparql_query_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyGPtrArray callback,
                                                             gpointer user_data);
    void                tracker_resources_sparql_update     (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);
    guint               tracker_resources_sparql_update_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);
    GPtrArray *         tracker_resources_sparql_update_blank
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);
    guint               tracker_resources_sparql_update_blank_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyGPtrArray callback,
                                                             gpointer user_data);
    void                tracker_resources_batch_sparql_update
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);
    guint               tracker_resources_batch_sparql_update_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);
    void                tracker_resources_batch_commit      (TrackerClient *client,
                                                             GError **error);
    guint               tracker_resources_batch_commit_async
                                                            (TrackerClient *client,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);
    void                tracker_resources_load              (TrackerClient *client,
                                                             const gchar *uri,
                                                             GError **error);
    guint               tracker_resources_load_async        (TrackerClient *client,
                                                             const gchar *uri,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);

## Description

Tracker uses the SPARQL query language [1] to retrieve data from tracker-store, and the stored information applies to the Nepomuk ontology [2].

## Details

### TrackerReplyGPtrArray ()

    void                (*TrackerReplyGPtrArray)            (GPtrArray *result,
                                                             GError *error,
                                                             gpointer user_data);

The `result` is returned as a GPtrArray containing an array of GStrv with the results from the query unless there is an error. If there is an error the `error` is populated with the details. The `user_data` is provided in the callback.

`result` : |
`error` : |
`user_data` : |

### TrackerReplyVoid ()

    void                (*TrackerReplyVoid)                 (GError *error,
                                                             gpointer user_data);

The `user_data` is returned when the query has completed. If there is an error the `error` is populated with the details.

`error` : | a GError.
`user_data` : | a gpointer for user data.

### tracker_resources_sparql_query ()

    GPtrArray *         tracker_resources_sparql_query      (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);

Queries the database using SPARQL. An example query would be:

Example 1. Using tracker_resource_sparql_query()

An example of using `tracker_resource_sparql_query()` to list all albums by title and include their song count and song total length.

     TrackerClient *client;
     GPtrArray *array;
     GError *error = NULL;
     const gchar *query;

     /* Create D-Bus connection with no warnings and maximum timeout. */
     client = tracker_client_new (0, G_MAXINT);
     query = "SELECT {"
             "  ?album"
             "  ?title"
             "  COUNT(?song) AS songs"
             "  SUM(?length) AS totallength"
             "} WHERE {"
             "  ?album a nmm:MusicAlbum ;"
             "  nie:title ?title ."
             "  ?song nmm:musicAlbum ?album ;"
             "  nfo:duration ?length"
             "} "
             "GROUP BY (?album");

     array = tracker_resources_sparql_query (client, query, &error);

     if (error) {
             g_warning ("Could not query Tracker, %s", error->message);
             g_error_free (error);
             g_object_unref (client);
             return;
     }

     /* Do something with the array */

     g_ptr_array_free (array, TRUE);

This API call is completely synchronous so it may block.

`client` : | a TrackerClient.
`query` : | a string representing SPARQL.
`error` : | a GError.
Returns : | A GPtrArray with the query results which must be freed using `g_ptr_array_free()`.

Since 0.8

### tracker_resources_sparql_query_async ()

    guint               tracker_resources_sparql_query_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyGPtrArray callback,
                                                             gpointer user_data);

Does an asynchronous SPARQL query. See `tracker_resources_sparql_query()` to see how an SPARLQL query should be like.

`client` : | a TrackerClient
`query` : | a string representing SPARQL.
`callback` : | callback function to be called when the data is ready.
`user_data` : | user data to pass to `callback`
Returns : | A guint representing the operation ID. See `tracker_cancel_call()`. In the event of failure, 0 is returned.

Since 0.8

### tracker_resources_sparql_update ()

    void                tracker_resources_sparql_update     (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);

Updates the database using SPARQL.

This API behaves the same way `tracker_resources_sparql_query()` does but with the difference that it is intended to be used for data updates.

This API call is completely synchronous so it may block.

`client` : | a TrackerClient.
`query` : | a string representing SPARQL.
`error` : | a GError.

Since 0.8

### tracker_resources_sparql_update_async ()

    guint               tracker_resources_sparql_update_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);

Does an asynchronous SPARQL update.

`client` : | a TrackerClient.
`query` : | a string representing an SPARQL update.
`callback` : | callback function to be called when the update has been processed.
`user_data` : | user data to pass to `callback`.
Returns : | A guint representing the operation ID. See `tracker_cancel_call()`. In the event of failure, 0 is returned.

Since 0.8

### tracker_resources_sparql_update_blank ()

    GPtrArray *         tracker_resources_sparql_update_blank
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);

`client` : |
`query` : |
`error` : |
Returns : |

### tracker_resources_sparql_update_blank_async ()

    guint               tracker_resources_sparql_update_blank_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyGPtrArray callback,
                                                             gpointer user_data);

`client` : |
`query` : |
`callback` : |
`user_data` : |
Returns : |

### tracker_resources_batch_sparql_update ()

    void                tracker_resources_batch_sparql_update
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             GError **error);

Updates the database using SPARQL. Updates done this way have to be committed explicitly through `tracker_resources_batch_commit()` or `tracker_resources_batch_commit_async()`. This API call is synchronous so it may block.

`client` : | a TrackerClient.
`query` : | a string representing SPARQL.
`error` : | return location for errors.

Since 0.8

### tracker_resources_batch_sparql_update_async ()

    guint               tracker_resources_batch_sparql_update_async
                                                            (TrackerClient *client,
                                                             const gchar *query,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);

Updates the database using SPARQL. see `tracker_resources_batch_sparql_update()`.

`client` : | a TrackerClient.
`query` : | a string representing SPARQL.
`callback` : | function to be called when the batch update has been performed.
`user_data` : | user data to pass to `callback`.
Returns : | A guint representing the operation ID. See `tracker_cancel_call()`. In the event of failure, 0 is returned.

Since 0.8

### tracker_resources_batch_commit ()

    void                tracker_resources_batch_commit      (TrackerClient *client,
                                                             GError **error);

Commits a batch of already issued SPARQL updates. This API call is synchronous so it may block.

`client` : | a TrackerClient.
`error` : | return location for errors.

Since 0.8

### tracker_resources_batch_commit_async ()

    guint               tracker_resources_batch_commit_async
                                                            (TrackerClient *client,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);

Commits a batch of already issued SPARQL updates.

`client` : | a TrackerClient.
`callback` : | callback to be called when the operation is finished.
`user_data` : | user data to pass to `callback`.
Returns : | A guint representing the operation ID. See `tracker_cancel_call()`. In the event of failure, 0 is returned.

Since 0.8

### tracker_resources_load ()

    void                tracker_resources_load              (TrackerClient *client,
                                                             const gchar *uri,
                                                             GError **error);

`client` : |
`uri` : |
`error` : |

### tracker_resources_load_async ()

    guint               tracker_resources_load_async        (TrackerClient *client,
                                                             const gchar *uri,
                                                             TrackerReplyVoid callback,
                                                             gpointer user_data);

`client` : |
`uri` : |
`callback` : |
`user_data` : |
Returns : |

[1] SPARQL query language for RDF (W3C)

[2] Nepomuk - The social semantic desktop