• Intro
• Downloads
• Community
• Development
• News
• TALK

Documentation/Maemo 5 Developer Guide/Application Development/MIME type mapping

MIME types mapping specifies for the platform which application should handle a given MIME type. A mapping has to be defined in the desktop file of the application by adding to it the MimeType field. Desktop files 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.

An example_libosso.desktop file for the application looks like the following:

[Desktop Entry]
Encoding=UTF-8
Version=1.0
Type=Application
Name=Example libOSSO
Exec=/usr/bin/example_libosso
X-Osso-Service=org.maemo.example_libosso
Icon=qgn_list_gene_default_app
MimeType=application/x-example;

The last line is the most important one, and specifies that this application can handle the MIME type application/x-example.

[edit] New MIME type with OSSO category extension

If the application is introducing a new MIME type to the system, it is necessary to provide the mime-info XML (see more at http://standards.freedesktop.org/shared-mime-info-spec/) that defines it, in this case an example-mime.xml file for the application looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"
           xmlns:osso="http://nokia.com/osso/mime-categories">
  <mime-type type="application/x-example">
        <comment>Example application file</comment>
        <osso:category name="images"/>
        <magic priority="50">
               <match type="string" value="FOO" offset="0"/>
        </magic>
        <glob pattern="*.foo"/>
  </mime-type>
</mime-info>

This entry maps one extension and a magic string to the application/x-example MIME type.

N.B. The glob pattern should be given in lowercase.

[edit] What is OSSO category

The platform has a notion of file categories for the user's data files. The available categories are:

• Bookmarks
• Contacts
• Documents
• Emails
• Images
• Audio
• Video
• Other

A mapping is set up between categories and MIME types, so that the MIME type of a file determines its category. The MIME type setup is handled by the shared-mime-info infrastructure, and the category information is added to that same framework.

Adding a mapping between a category and a number of MIME types is performed much like adding or editing the supported MIME types in the system.

Each application or library that adds a category mapping should add a file in

/usr/share/mime/packages/

The file format is the same XML format used for MIME types, with an added tag

[edit] Updating platform databases

To introduce the newly defined MIME type(s) to the platform, do the following:

1. Copy the mime-information XML under /usr/share/mime/packages:

   [sbox-FREMANTLE_X86: ~] > cp example-mime.xml /usr/share/mime/packages
   

2. Update the MIME and desktop database:

    
   [sbox-FREMANTLE_X86: ~] > update-mime-database /usr/share/mime
   [sbox-FREMANTLE_X86: ~] > update-desktop-database /usr/share/applications
   

3. Update the OSSO category database:

   [sbox-FREMANTLE_X86: ~] > hildon-update-category-database /usr/share/mime
   

To remove the MIME from the platform, delete the XML file in /usr/share/mime/packages/ and update the databases as above.

[edit] Registering MIME type with package

Because most of the applications are installed on the platform via pre-compiled packages, the MIME type registration has to be performed as well.

The steps are similar to the ones shown above.

To install the MIME information XML under /usr/share/mime/packages, edit the package rules and install the files. In this case it looks as follows:

• in the rules file under install section, add the following lines:

mkdir -p $(CURDIR)/debian/tmp/usr/share/mime/packages
cp $(CURDIR)/example-mime.xml $(CURDIR)/debian/tmp/usr/share/mime/packages

• and in .install we need to add

  usr/share/mime/packages/example-mime.xml

This way, it can be assured that the mime information XML is being installed under /usr/share/mime/packages.

Add the following lines to both the postinst and postrm files of the package:

if [ -x /usr/bin/update-mime-database ]; then
 update-mime-database /usr/share/mime
fi
if [ -x /usr/bin/update-desktop-database ]; then
 update-desktop-database /usr/share/applications
fi
if [ -x /usr/bin/hildon-update-category-database ]; then
 hildon-update-category-database /usr/share/mime
fi

This keeps the platform mime information and OSSO category databases up-to-date.

[edit] Using hildon-mime-open

[edit] The hildon-mime-open API

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

[edit] Desktop files

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 semicolon separated list of types, for example:

MimeType=image/png;image/jpeg;

Especially note the trailing semicolon.

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

[edit] 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.)

[edit] 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 default one is used. If there is no default, the first one from the list is used.

Then a D-Bus 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.