Tracker Miner Library Reference Manual: TrackerMinerWeb

## TrackerMinerWeb TrackerMinerWeb — Abstract base class for miners using web services |

## Synopsis

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

    #define             TRACKER_MINER_WEB_DBUS_INTERFACE
    #define             TRACKER_MINER_WEB_ERROR
    #define             TRACKER_MINER_WEB_ERROR_DOMAIN
    typedef             TrackerMinerWeb;
                        TrackerMinerWebClass;
    enum                TrackerMinerWebError;
    void                tracker_miner_web_associate         (TrackerMinerWeb *miner,
                                                             GHashTable *association_data,
                                                             GError **error);
    void                tracker_miner_web_authenticate      (TrackerMinerWeb *miner,
                                                             GError **error);
    void                tracker_miner_web_dissociate        (TrackerMinerWeb *miner,
                                                             GError **error);
    GQuark              tracker_miner_web_error_quark       (void);
    GHashTable *        tracker_miner_web_get_association_data
                                                            (TrackerMinerWeb *miner,
                                                             GError **error);

## Description

TrackerMinerWeb is an abstract base class for miners retrieving data from web services. It's a very thin layer above TrackerMiner, only adding virtual methods needed to handle association with the remote service.

## Details

### TRACKER_MINER_WEB_DBUS_INTERFACE

    #define TRACKER_MINER_WEB_DBUS_INTERFACE "org.freedesktop.Tracker1.MinerWeb"

### TRACKER_MINER_WEB_ERROR

    #define TRACKER_MINER_WEB_ERROR        tracker_miner_web_error_quark ()

### TRACKER_MINER_WEB_ERROR_DOMAIN

    #define TRACKER_MINER_WEB_ERROR_DOMAIN "TrackerMinerWeb"

### TrackerMinerWeb

    typedef struct TrackerMinerWeb TrackerMinerWeb;

### TrackerMinerWebClass

    typedef struct {
    	TrackerMinerClass parent_class;

    	/* vmethods */
    	void        (* authenticate)         (TrackerMinerWeb   *miner,
    	                                      GError           **error);
    	GHashTable* (* get_association_data) (TrackerMinerWeb   *miner,
    	                                      GError           **error);
    	void        (* associate)            (TrackerMinerWeb   *miner,
    	                                      const GHashTable  *association_data,
    	                                      GError           **error);
    	void        (* dissociate)           (TrackerMinerWeb   *miner,
    	                                      GError           **error);
    } TrackerMinerWebClass;

For the `authenticate` function, a username/password can be used and this should return an empty `GHashTable`. If the authentication is based on a token, the following keys must be returned in the `GHashTable`:

- url: the url to point the user to.

Additionally, the miner may define the following keys:

- post_message: a message to display after the user completes the association process.

- post_url: a url to point the user to after they have completed the association.

### Note

If both post_message and post_url are defined, the message will be displayed before the url is opened.

For the `associate` function, in the case of a username/password based authentication, the following keys must be defined:

- username: the username.

- password: the password.

In the case of a token based authentication, the `GHashTable` can be ignored since it will be empty.

For the `dissociate` function, miners must forget any user credentials stored.

TrackerMinerClass `parent_class`; | parent object class
`authenticate` () | called when a miner must authenticate against a remote service
`get_association_data` () | called when one requests the miner's associated data
`associate` () | called when the miner is asked to associate a remote service
`dissociate` () | called when the miner is asked to revoke an association with a remote service

Since 0.8.

### enum TrackerMinerWebError

    typedef enum {
    	TRACKER_MINER_WEB_ERROR_WRONG_CREDENTIALS,
    	TRACKER_MINER_WEB_ERROR_TOKEN_EXPIRED,
    	TRACKER_MINER_WEB_ERROR_NO_CREDENTIALS,
    	TRACKER_MINER_WEB_ERROR_KEYRING,
    	TRACKER_MINER_WEB_ERROR_SERVICE,
    	TRACKER_MINER_WEB_ERROR_TRACKER
    } TrackerMinerWebError;

The following errors are possible during any of the performed actions with a remote service.

`TRACKER_MINER_WEB_ERROR_WRONG_CREDENTIALS` | The credentials were refused by the remote service
`TRACKER_MINER_WEB_ERROR_TOKEN_EXPIRED` | The remote service token has expired
`TRACKER_MINER_WEB_ERROR_NO_CREDENTIALS` | There are currenty no credentials stored for this service
`TRACKER_MINER_WEB_ERROR_KEYRING` | The credential storage failed to retrieve the relevant information. See `TrackerPasswordProvider`
`TRACKER_MINER_WEB_ERROR_SERVICE` | Could not contact the remote service
`TRACKER_MINER_WEB_ERROR_TRACKER` | Could not contact the Tracker service

Since 0.8

### tracker_miner_web_associate ()

    void                tracker_miner_web_associate         (TrackerMinerWeb *miner,
                                                             GHashTable *association_data,
                                                             GError **error);

Asks `miner` to associate with a remote service using `association_data`. To know what data to put into `association_data`, see `TrackerMinerWebClass` for more information.

On failure `error` will be set.

`miner` : | a TrackerMinerWeb
`association_data` : | a `GHashTable` with the data to use for associating with a remote service.
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]

Since 0.8

### tracker_miner_web_authenticate ()

    void                tracker_miner_web_authenticate      (TrackerMinerWeb *miner,
                                                             GError **error);

Asks `miner` to authenticate with a remote service. On failure `error` will be set.

`miner` : | a TrackerMinerWeb
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]

Since 0.8

### tracker_miner_web_dissociate ()

    void                tracker_miner_web_dissociate        (TrackerMinerWeb *miner,
                                                             GError **error);

Asks `miner` to dissociate from a remote service. At this point, the miner should stop storing any credentials or sensitive information which could be used to authenticate with the remote service.

On failure `error` will be set.

`miner` : | a TrackerMinerWeb
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]

Since 0.8

### tracker_miner_web_error_quark ()

    GQuark              tracker_miner_web_error_quark       (void);

Returns : | the GQuark used to identify miner web errors in GError structures.

Since 0.8

### tracker_miner_web_get_association_data ()

    GHashTable *        tracker_miner_web_get_association_data
                                                            (TrackerMinerWeb *miner,
                                                             GError **error);

Asks `miner` to retrieve association_data for. The data returned in the `GHashTable` depends on the `miner` implementation and the type of authentication. See `TrackerMinerWebClass` for more information.

`miner` : | a TrackerMinerWeb
`error` : | return location for errors. [out callee-allocates][transfer full][allow-none]
Returns : | a `GHashTable` with the data. On failure `error` will be set and `NULL` will be returned. [transfer full]

Since 0.8