Tracker Miner Library Reference Manual: TrackerMinerWeb

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

## Functions

void | tracker_miner_web_associate ()
void | tracker_miner_web_authenticate ()
void | tracker_miner_web_dissociate ()
GQuark | tracker_miner_web_error_quark ()
GHashTable * | tracker_miner_web_get_association_data ()

## Types and Values

#define | TRACKER_MINER_WEB_DBUS_INTERFACE
#define | TRACKER_MINER_WEB_ERROR
#define | TRACKER_MINER_WEB_ERROR_DOMAIN
typedef | TrackerMinerWeb
| TrackerMinerWebClass
enum | TrackerMinerWebError

## Object Hierarchy

## Includes

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

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

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

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

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.

#### Members

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

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

#### Members

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