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

Warning: You are not logged in. Your IP address will be recorded in this page's edit history.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.

Learn more about Contributing to the wiki.

= MIME types 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 [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.desktop example_libosso.desktop] file for the application looks like the following:

<code>[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;</code>

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

=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:

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

<nowiki> This entry maps one extension and a ``magic'' string to the ``application/x-example'' MIME type. </nowiki>

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

= 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 ``  8.7.3 Updating platform databases

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

# Copy the mime-information XML under /usr/share/mime/packages: 
 
 [sbox-FREMANTLE_X86: ~] &gt; cp example-mime.xml /usr/share/mime/packages

# Update the MIME and desktop database: 
 
 [sbox-FREMANTLE_X86: ~] &gt; update-mime-database /usr/share/mime
 [sbox-FREMANTLE_X86: ~] &gt; update-desktop-database /usr/share/applications

# Update the OSSO category database: 
 
 [sbox-FREMANTLE_X86: ~] &gt; 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.

= 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:
 <tt>mkdir -p $(CURDIR)/debian/tmp/usr/share/mime/packages
 cp $(CURDIR)/example-mime.xml $(CURDIR)/debian/tmp/usr/share/mime/packages</tt>
* and in .install we need to add
 <tt>usr/share/mime/packages/example-mime.xml</tt>

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:

<tt>'''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'''</tt>

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

= Using hildon-mime-open =

== The hildon-mime-open API ==

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

== 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 <nowiki>[Desktop Entry]</nowiki> 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.

== 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.

Please note that all contributions to maemo.org wiki may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see maemo.org wiki:Copyrights for details). Do not submit copyrighted work without permission!

Summary:

Cancel | Editing help (opens in new window)

Retrieved from "http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Application_Development/MIME_type_mapping"

Personal tools

Navigation

Views

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

@@ Line 1: / Line 1: @@
-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 file format|Desktop files]] are found in <code>$prefix/share/applications</code>. 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.
+= MIME types 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 [https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/example_libosso.desktop example_libosso.desktop] file for the application looks like the following:
-<pre>
-[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;
-</pre>
-The last line is the most important one, and specifies that this application can handle the MIME type <code>application/x-example</code>.
+ <code>[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;</code>
+<nowiki> The last line is the most important one, and specifies that this application can handle the MIME type ``application/x-example''. </nowiki>
+=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:
-== New MIME type with OSSO category extension ==
+ <tt><span>'''<span><font color="#000080">&lt;?xml</font></span>'''</span> <span><font color="#009900">version</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"1.0"</font></span> <span><font color="#009900">encoding</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"UTF-8"</font></span><span>'''<span><font color="#000080">?&gt;</font></span>'''</span>
+ <span>'''<span><font color="#0000FF">&lt;mime-info</font></span>'''</span> <span><font color="#009900">xmlns</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"http://www.freedesktop.org/standards/shared-mime-info"</font></span>
+            <span><font color="#009900">xmlns:osso</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"http://nokia.com/osso/mime-categories"</font></span><span>'''<span><font color="#0000FF">&gt;</font></span>'''</span>
+   <span>'''<span><font color="#0000FF">&lt;mime-type</font></span>'''</span> <span><font color="#009900">type</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"application/x-example"</font></span><span>'''<span><font color="#0000FF">&gt;</font></span>'''</span>
+         <span>'''<span><font color="#0000FF">&lt;comment&gt;</font></span>'''</span>Example application file<span>'''<span><font color="#0000FF">&lt;/comment&gt;</font></span>'''</span>
+         <span>'''<span><font color="#0000FF">&lt;osso:category</font></span>'''</span> <span><font color="#009900">name</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"images"</font></span><span>'''<span><font color="#0000FF">/&gt;</font></span>'''</span>
+         <span>'''<span><font color="#0000FF">&lt;magic</font></span>'''</span> <span><font color="#009900">priority</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"50"</font></span><span>'''<span><font color="#0000FF">&gt;</font></span>'''</span>
+                <span>'''<span><font color="#0000FF">&lt;match</font></span>'''</span> <span><font color="#009900">type</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"string"</font></span> <span><font color="#009900">value</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"FOO"</font></span> <span><font color="#009900">offset</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"0"</font></span><span>'''<span><font color="#0000FF">/&gt;</font></span>'''</span>
+         <span>'''<span><font color="#0000FF">&lt;/magic&gt;</font></span>'''</span>
+         <span>'''<span><font color="#0000FF">&lt;glob</font></span>'''</span> <span><font color="#009900">pattern</font></span><span><font color="#990000"><nowiki>=</nowiki></font></span><span><font color="#FF0000">"*.foo"</font></span><span>'''<span><font color="#0000FF">/&gt;</font></span>'''</span>
+   <span>'''<span><font color="#0000FF">&lt;/mime-type&gt;</font></span>'''</span>
+ <span>'''<span><font color="#0000FF">&lt;/mime-info&gt;</font></span>'''</span>
+ </tt>
-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 <code>example-mime.xml</code> file for the application looks as follows:
+<nowiki> This entry maps one extension and a ``magic'' string to the ``application/x-example'' MIME type. </nowiki>
-<source lang="xml">
-<?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>
-</source>
-This entry maps one extension and a ''magic'' string to the <code>application/x-example</code> MIME type.
 '''N.B.''' The glob pattern should be given in lowercase.
-== What is OSSO category ==
+= What is OSSO category =
 The platform has a notion of file categories for the user's data files. The available categories are:
@@ Line 58: / Line 60: @@
   /usr/share/mime/packages/
-The file format is the same XML format used for MIME types, with an added tag
-=== Updating platform databases ===
+The file format is the same XML format used for MIME types, with an added tag ``  8.7.3 Updating platform databases
 To introduce the newly defined MIME type(s) to the platform, do the following:
-<ol>
+# Copy the mime-information XML under /usr/share/mime/packages:
-<li>
-Copy the mime-information XML under <code>/usr/share/mime/packages</code>:
+ [sbox-FREMANTLE_X86: ~] &gt; cp example-mime.xml /usr/share/mime/packages
-<pre>
-[sbox-FREMANTLE_X86: ~] > cp example-mime.xml /usr/share/mime/packages
-</pre>
-</li>
-<li>
-Update the MIME and desktop database:
-<pre>
-[sbox-FREMANTLE_X86: ~] > update-mime-database /usr/share/mime
-[sbox-FREMANTLE_X86: ~] > update-desktop-database /usr/share/applications
-</pre>
-</li>
-<li>
-Update the OSSO category database:
-<pre>
-[sbox-FREMANTLE_X86: ~] > hildon-update-category-database /usr/share/mime
-</pre>
-</li>
-</ol>
-To remove the MIME from the platform, delete the XML file in <code>/usr/share/mime/packages/</code> and update the databases as above.
-== Registering MIME type with package ==
+# Update the MIME and desktop database:
+ [sbox-FREMANTLE_X86: ~] &gt; update-mime-database /usr/share/mime
+ [sbox-FREMANTLE_X86: ~] &gt; update-desktop-database /usr/share/applications
+# Update the OSSO category database:
+ [sbox-FREMANTLE_X86: ~] &gt; 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.
+= 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.
@@ Line 93: / Line 87: @@
 The steps are similar to the ones shown above.
-To install the MIME information XML under <code>/usr/share/mime/packages</code>, edit the package rules and install the files. In this case it looks as follows:
+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
+  <tt>mkdir -p <span><font color="#009900">$(CURDIR)</font></span>/debian/tmp/usr/share/mime/packages
-  cp $(CURDIR)/example-mime.xml $(CURDIR)/debian/tmp/usr/share/mime/packages
+  cp <span><font color="#009900">$(CURDIR)</font></span>/example-mime<span><font color="#990000">.</font></span>xml <span><font color="#009900">$(CURDIR)</font></span>/debian/tmp/usr/share/mime/packages</tt>
-* and in .install we need to add<pre>usr/share/mime/packages/example-mime.xml</pre>
+* and in .install we need to add
+ <tt>usr/share/mime/packages/example-mime<span><font color="#990000">.</font></span>xml</tt>
-This way, it can be assured that the mime information XML is being installed under <code>/usr/share/mime/packages</code>.
+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:
-<source lang="bash">
-if [ -x /usr/bin/update-mime-database ]; then
+ <tt><span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">[</font></span> -x /usr/bin/update-mime-database <span><font color="#990000">];</font></span> <span>'''<span><font color="#0000FF">then</font></span>'''</span>
- update-mime-database /usr/share/mime
+  update-mime-database /usr/share/mime
-fi
+ <span>'''<span><font color="#0000FF">fi</font></span>'''</span>
-if [ -x /usr/bin/update-desktop-database ]; then
+ <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">[</font></span> -x /usr/bin/update-desktop-database <span><font color="#990000">];</font></span> <span>'''<span><font color="#0000FF">then</font></span>'''</span>
- update-desktop-database /usr/share/applications
+  update-desktop-database /usr/share/applications
-fi
+ <span>'''<span><font color="#0000FF">fi</font></span>'''</span>
-if [ -x /usr/bin/hildon-update-category-database ]; then
+ <span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">[</font></span> -x /usr/bin/hildon-update-category-database <span><font color="#990000">];</font></span> <span>'''<span><font color="#0000FF">then</font></span>'''</span>
- hildon-update-category-database /usr/share/mime
+  hildon-update-category-database /usr/share/mime
-fi
+ <span>'''<span><font color="#0000FF">fi</font></span>'''</span></tt>
-</source>
 This keeps the platform mime information and OSSO category databases up-to-date.
-== Using hildon-mime-open ==
+= Using hildon-mime-open =
-=== The hildon-mime-open API ===
+== The hildon-mime-open API ==
-This section describes how desktop files are used with the <code>hildon_mime_open_*</code> API.
+This section describes how desktop files are used with the hildon_mime_open_* API.
-=== Desktop files ===
+== Desktop files ==
-For the <code>hildon_mime_open_*</code> 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.
+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 <nowiki>[Desktop Entry]</nowiki> 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:
@@ Line 132: / Line 127: @@
 Especially note the trailing semicolon.
-When using <code>hildon_mime_open_*</code>, the only thing that is used to identify the application to launch is the MIME type.
+When using hildon_mime_open_*, the only thing that is used to identify the application to launch is the MIME type.
-=== Default application ===
+== 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.
@@ Line 142: / Line 137: @@
   $(prefix)/share/applications/defaults.list
-But also looks in other directories as specified by the environment variable <code>XDG_DATA_DIRS</code>.
+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:
@@ Line 151: / Line 146: @@
   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 <code>$XDG_DATA_HOME</code>, normally set to <code>~/.local</code> on regular desktops.)
+(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 <code>hildon_mime_open_*</code> 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.
+== Implementation details ==
-Then a D-Bus message is sent to activate the service specified by the '<code>X-Osso-Service</code>' value for the found applications's desktop file, and the URI is passed to it for opening.
+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.
-[[Category:Development]]
+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.
-[[Category:Documentation]]
-[[Category:Fremantle]]