TrackerMinerWeb
3
LIBTRACKER-MINER Library

# TrackerMinerWeb

Abstract base class for miners using web services

## Synopsis

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

    #define             TRACKER_MINER_WEB_ERROR_DOMAIN
    #define             TRACKER_MINER_WEB_ERROR
    #define             TRACKER_MINER_WEB_DBUS_INTERFACE
    typedef             TrackerMinerWebPrivate;
    typedef             TrackerMinerWeb;
                        TrackerMinerWebClass;
    GQuark              tracker_miner_web_error_quark       (void);
    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);
    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_ERROR_DOMAIN

    #define TRACKER_MINER_WEB_ERROR_DOMAIN "TrackerMinerWeb"

### TRACKER_MINER_WEB_ERROR

    #define TRACKER_MINER_WEB_ERROR        tracker_miner_web_error_quark ()

### TRACKER_MINER_WEB_DBUS_INTERFACE

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

### TrackerMinerWebPrivate

    typedef struct TrackerMinerWebPrivate TrackerMinerWebPrivate;

### 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.

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.

### tracker_miner_web_error_quark ()

    GQuark              tracker_miner_web_error_quark       (void);

Returns :

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

### 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

### 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

### 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

### 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

Returns :

  a `GHashTable` with the data. On failure `error` will be set and `NULL` will be returned.