TrackerMinerWeb

TrackerMinerWeb — Abstract base class for miners using web services

Synopsis

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

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

TrackerMinerWebPrivate

typedef struct TrackerMinerWebPrivate TrackerMinerWebPrivate;


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 ()


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_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_DBUS_INTERFACE

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


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.


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