URL Handler

The main purpose of the wiki page is to describe the way to register an application as URL handler. The idea is, that an application test would be launched by using the url: test://foo Therefore it provides:

  • Description of the Hildon URI API
  • Step-by-step example based on the implementation of Cornelius Hald

Hildon URI API

The most updated revision of the API is revision 2, but it bases on the first revision. So please take both documents into account. The API descriptions, with some examples you will find here:

Up to date revision:

Hildon URI API, revision 2

Revision 2 is based on:

Hildon URI API, revision 1

This information might be needed to understand the following example.

Example

The example is based on a discussion in talk.maemo.org and gives an overview of the result of the discussion. Conboy is used as an example application, with the goal to create an URL handler for "conboy://". The following steps has to be taken:

  • Modification of the .desktop file
Add a X-Osso-URI-Actions line to the Desktop Entry group and add a X-Osso-URI-Action Handler group. For example: 
[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Name=Conboy
Exec=@prefix@/bin/conboy
Icon=conboy
X-Window-Icon=conboy
X-Window-Icon-Dimmed=conboy
X-Osso-Service=de.zwong.conboy
X-Osso-Type=application/x-executable
X-Osso-URI-Actions=conboy

[X-Osso-URI-Action Handler conboy]
Method=load_url
Name=some_name
TranslationDomain=conboy
Important: Set a value for all three keys ('Method', 'Name' and 'TranslationDomain') otherwise it won't work. Still, the only value of these that you get passed to your callback function is the value of 'Method'.
  • Update the changes in your .desktop file: 
update-desktop-database
  • Implement a callback in your code: 
gint dbus_handler(const gchar *interface,
                        const gchar *method,
                        GArray *arguments,
                        gpointer data,
                        osso_rpc_t *retval);
  • Register the callback: 
if (osso_rpc_set_cb_f(osso_context,
       "de.zwong.conboy",
       "/de/zwong/conboy",
       "de.zwong.conboy",
       dbus_handler,
       NULL) != OSSO_OK) {
   g_printerr("Failed to set callback\n");
}
  • Call it from the browser:
Now lets assume in the browser we click on the following link: 
conboy://1234567
In this case the application is started and the provided callback is called with the following parameters. 
interface = "de.zwong.conboy"
method = "load_url"
first element of arguments = "conboy://1234567"
Retrieved from "http://bugs.maemo.org/URL_Handler"