Configuration of DataProvider

Contents

Configuration of DataProvider

This page is only a draft and is still work in progress

All passive DataProvider can be configured either via DBus or by changing its configuration in a configfile.

Options

Per default each DataProvider has a configurable option called enabled, which is per default set to True.

Config-File

The config file for dataproviders is placed in

    ~/.config/zeitgeist/dataproviders.conf

Each DataProvider can have its own section here. To globally disable the firefox dataprovider just change/add the [firefox_history] like:

    [firefox_history]
    enabled = False

Configuration over DBus

Each DataProvider can have its own Configuration service. All configuration services are using the SessionBus with

    'org.gnome.zeitgeist.datahub'

as bus name.

To follow the official naming recommendations from the DBus spec bus names should be all lower case org.gnome.zeitgeist.dataprovider. That said - if these providers are running inside the zeitgeist-datahub then a better bus name might be org.gnome.zeitgeist.datahub. Following this naming the engine should sit on org.gnome.zeitgeist.engine -- MikkelKamstrup 2009-06-18 05:34:40 [FIXED]

The bus path is different for each DataProvider, it is like

    '/org/gnome/zeitgeist/datahub/dataprovider/$NAME'

where $NAME is the name of the DataProvider.

Again, following the DBus spec, it should be all lowercase. Object paths should pretty much be constructed like you would a directory structure. So if these are really objects inside the datahub I would say that /org/gnome/zeitgeist/datahub/dataprovider/$NAME. The extra "dataprovider" path element after "datahub" is there because the datahub might put other objects on the bus as well in the future -- MikkelKamstrup 2009-06-18 05:34:40 [FIXED]

To find out which dataprovider are configurable over DBus send request the GetDataProviders method of the service root:

    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub \
        org.gnome.zeitgeist.DataHub.GetDataProviders

This returns a list of all valid values for $NAME.

From this it looks like the bus name and interface name is mixed up... The DBus spec recommends that the interface name is CamelCase. So the primary interface exposed by the datahub would be org.gnome.zeitgeist.DataHub -- MikkelKamstrup 2009-06-18 05:34:40 [FIXED]
It would be more natural to return a list of real DBus object paths (ie. DBus return type signature of ao), instead of the object names relative to /org/gnome/zeitgeist/datahub/dataproviders -- MikkelKamstrup 2009-06-19 08:53:35
- I thought about returning the full path here, but I decided to not to this. Because I want to return the same value here which can also be used in the config file as section headers. And I'm not sure if [/org/gnome/zeitgeist/datahub/dataprovider/firefox_history] will work as such a header. -- MarkusKorn 2009-06-22 18:53:24

The first thing which has to be done by a client in order to change the configuration of a DataProvider is to request a ConfigToken. To request such token send a random integer to to the RequestSetupRun method of a DataProvider's Configuration service:

    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/firefox_history \
        org.gnome.zeitgeist.DataHub.RequestSetupRun \
        int32:123456

I don't get why one has to request a config token..? Also it seems that an object on /org/gnome/zeitgeist/datahub/dataprovider/firefox_history use the same interface namespace as the datahub (ie. org.gnome.zeitgeist.DataHub). It would be more natural if there was a separate interface for dataproviders, fx. org.gnome.zeitgeist.DataProvider -- MikkelKamstrup 2009-06-19 08:53:35
- In theory it is possible to connect multiple fontends to the same zeitgeist-daemon. And to not interfere with different clients to set configurations at the same time I added this token, does this make sense? This different .DataProvider interface makes sense to me, will change it. -- MarkusKorn 2009-06-22 18:53:24

The Configuration service returns True if this token can be used for further configurations or returns False if this client is not allowed to change the configuration. One possible reason is that already another client is configuring the DataProvider.

To get a list of all options for a DataProvider run:

    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/firefox_history \
        org.gnome.zeitgeist.DataHub.GetOptions \
        int32:123456

This returns a list of tuples, where the first element of each tuple is the name of the option and the second is True is this option is required, otherwise it's False.

To actually change an option, send to the set_configuration method something like:

    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/firefox_history \
        org.gnome.zeitgeist.DataHub.SetConfiguration \
        int32:123456 \
        string:"enabled" string:"1"

The first argument is always the accepted token of the first step. Followed by the name of the option to change and the new value. All values have to be send as string. The configuration service is smart enough to convert this string to the correct type.

Why is the option value encoded as a string and not a DBus variant (type signature v)?.
- ConfigParser handles all options as strings anyway, so the logic to convert to the real internal values is already there and I decided to reuse it for the DBUs interface. I also think that "options have to be strings" is easier to document. -- MarkusKorn 2009-06-22 18:53:24

More complex Configuration (not implemented yet)

The launchpad DataProvider in zeitgeist_launchpad.py is already using a more complex way of configuration. In order to authenticate with launchpad a user needs credentials. This credentials are stored in the gnome-keyring. When no credentials are found in the keyring, the user has to create such credentials by:

    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/launchpad \
        org.gnome.zeitgeist.DataHub.RequestSetupRun \
        int32:123456
        
    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/launchpad \
        org.gnome.zeitgeist.DataHub.SetConfiguration \
        int32:123456 \
        string:"login" string:"yourlogin@email.com"
        
    dbus-send --print-reply --dest=org.gnome.zeitgeist.datahub \
        /org/gnome/zeitgeist/datahub/dataprovider/launchpad \
        org.gnome.zeitgeist.DataHub.SetConfiguration \
        int32:123456 \
        string:"password" string:"yoursecretpassword"

This will request the credentials, store them in the keyring and create a Launchpad object to access launchpad.net via the API. If all this succedes the DataProvider will start to collect the data. password and login are secret options, so they will never be stored to the config file. launchpad's configuration has also optional options like service (staging or edge) or access_level.

Why can each dataprovider not use the Gnome keyring directly? There seems to be no reason to expose this via the Zeitgeist interface. See fx. the Web utility module for deskbar-applet -- MikkelKamstrup 2009-06-19 08:53:35