Don't forget to also have a look at the code at http://git.mymadcat.com/index.php/p/gsoc/source/tree/master/

What is a bridge

A bridge is a standalone program which connects to a remote web service and extracts some data which is then inserted into Tracker, via its SPARQL interface.In this documentation we explain how the API works, which should be enough to know how to use a bridge and how to write one.

Definitions

The API defines several concepts, although these might not be relevant for all the bridges. * Association : when a webservice allows a bridge to access its data, generally involves a confirmation from the user through a webpage. This is usually accomplished only once. This concept is only relevant for services using token based authentication. * Authentication : when a bridge authenticates itself to a webservice, ie sends some data prior to issuing API calls. This is usually done every time the bridge starts, or before every call.

Token based authentication vs. user/pass based authentication

Webservices generally use either of these authentication mechanism. Both are detailed thereafter.

Token based authentication

A webservice using a token based authentication mechanism requires the user to sign his calls with using a secret token. This token is obtained during the association step. The full sequence is : 1. The bridge gets a first token and generates a URL 2. The user goes to that URL, confirms the association and closes the page 3. The bridge gets a second token, which will be used to sign its future calls. The validity time of this token depends on the webservice. For example, Facebook requires an additionnal step to make a token last forever, and not only one week.

User/pass based authentication

Generally, no association is needed for user/pass based authentication. The bridge just needs to send the user/pass data once and gets a session cookie.

Using a bridge

Bridges use DBus to expose a common interface named org.freedesktop.Tracker.Bridge. They are started automatically by DBus, and can be stopped using the Shutdown() method. Bridges also ship a desktop file describing them. In the desktop file are the name and object path where the API calls must be issued, and the type of authentication they use. To know if you need to associate the bridge, call the Authenticate () method. The bridge will try to authenticate and emit the StatusChanged signal with one of the following enumerated values : 0 - Authenticated : the bridge is ready to extract data 1 - WrongToken : the bridge has already been associated, but the stored token is not working anymore 2 - NotAuthenticated : the bridge has never been authenticated In cases 1 and 2, you need to associate the bridge.

Association

To know the type of authentication the bridge uses, read the X-Tracker-Bridge-AuthScheme key in the Desktop Entry group. This can can have the following values : * Token : Token based authentication * UserPass : User/pass based authentication

For token based services

1. Call GetAssociationData() on the bridge. This will return a dictionary of strings. The following keys are always defined :

• url : the url to point the user to in order to confirm the association The following keys can be defined :
• post_message : a message to show to the user once he confirms the association (ie. when he has finished the steps in the web browser)
• post_url : a url to point the user to when he has confirmed the association. If post_message is also defined, then the message should be shown before opening the browser

2. When the user confirms the association, call FinishAssociation (dict), where dict is an empty dictionnary of strings.

For user/pass based services

1. Since the bridge only needs the user and the password, you don't need to call GetAssociationData () (doing so would return an empty dictionary). 2. Prompt the user for his username and password 3. Call FinishAssociation (dict) where dict is a dictionary of strings with the following keys defined :

• user : the username
• password : the password Any additionnal keys will be ignored.

Once association is done, the bridge will emit the StatusChanged signal. If everything went well, it should emit the Authenticated status. If any error happens during association, the Error signal will fire.

Authentication

Just call the Authenticate, and wait until you receive the StatusChanged signal. The status value should be Authenticated, if not associating again might be necessary. Watch for the Error signal for more details.

Pulling data

Once the bridge is authenticated, call the Pull () method to retrieve the data and insert it into Tracker. This method is supposed to be async, though it's not currently. The Error signal will fire in case of a problem. Bridges can emit the Progress () signal to inform about their work, but it's not required.