The hildon_mime_open_* API
==========================

This document describes how desktop files are used with the
hildon_mime_open_* API.

Note: This document assumes familiarity with adding MIME types to the
system, using the shared-mime-info specification. The specification
can be found at:

  http://standards.freedesktop.org/shared-mime-info-spec/latest/

Also, make sure to be fully aqainted with the desktop entry standard
which libhildonmime builds on top of. This can be found here:

  http://standards.freedesktop.org/desktop-entry-spec/latest/

There are 2 different utilities used when it comes to the MIME
database/desktop files:

  * update-desktop-database
  * update-mime-datebase


Desktop files
=============

These are found in $prefix/share/applications. Each application has a
desktop file, that specifies how it is started, what name it has,
etc. It also specifies which MIME types the application can handle, if
any.

For the hildon_mime_open_* API, there is one addition to the desktop
file format that is relevant: the 'X-Osso-Service' key. This
identifies the D-Bus service to use when trying to open a URI. The key
is used in the standard [Desktop Entry] group in the desktop files.

The 'MimeType' key is part of the Freedesktop standard, and should be
a semi-color separated list of types, for example:

MimeType=image/png;image/jpeg;

Especially note the trailing semi-colon.

When using hildon_mime_open_*, the only thing that is used to identify
the application to launch is the MIME type.


Default application
===================

The notion of "default application" for a MIME type is handled through
the GnomeVFS. It uses a file that lists the default desktop file for
each MIME type. This file is something that the "distro" needs to take
care of, and is not something each application can setup for itself.

The file is usually located at the default XDG data dir location:

$(prefix)/share/applications/defaults.list

But also looks in other directories as specified by the environment
variable XDG_DATA_DIRS.

The file format is simple and can look like this, for example:

[Default Applications]
application/ogg=totem.desktop
application/x-flac=totem.desktop
image/x-png=eog.desktop


(As a side point, the GnomeVFS API also uses a file in the user's home
directory to override the system one, it's located in $XDG_DATA_HOME,
normally set to ~/.local on regular desktops.)


Implementation details
======================

When the hildon_mime_open_* API is called with a URI, GnomeVFS is used
to get the MIME type. Then the list of applications that can handle
that type is listed, and the defualt one (*) is used. If there is no
default, the first one from the list is used.

Then a DBus message is sent to activate the service specified by the
'X-Osso-Service' value for the found applications's desktop file, and
the URI is passed to it for opening.


Updating the desktop and MIME type databases
============================================

The 'update-desktop-database' command parses all the *.desktop files
pointed to and generates a cache for them to speed up the
lookup. This generation is usually done in the post-inst phase in a
Debian package, in addition to "make install" in the makefile target:

  update-desktop-database $prefix/share/applications

Likewise for the 'update-mime-database' command, which generates a
cache for looking up MIME types.

