MIME Types

MIME Types This chapter describes how applications detect MIME types, how to register MIME types, and how to add applications to the GNOME Desktop. The purpose of this chapter is to make it easy for an administrator to understand how to configure different parts of the MIME database and give an general overview of the MIME system. Therefore we will not attempt to go into details where it is not necessary. For the gory details, it is recommended that you refer to the XDG shared mime info specification. Introduction to MIME Types MIME types introduction A Multipurpose Internet Mail Extension [MIME] type identifies the format of a file. Applications such as Internet browsers and email applications use the MIME type of a file to decide which actions to perform on it. For example, an email application can use the MIME type to detect the format of an attachment and choose an appropriate viewer for the file, such as opening a text document with gedit. As another example, the Nautilus file manager needs to know the MIME type of a file to perform the following tasks: Open the file in an appropriate application. Display a string that describes the type of file. Display an appropriate icon to represent the file. Display a list of other applications that can open the file. MIME types were originally proposed as a standard for identifying the message body of an e-mail message. Now, many systems use MIME types to identify the format of arbitrary files on the file system. MIME types are composed of a top-level media type followed by a subtype identifier, separated by a forward slash character, /. One example of a MIME type is image/jpeg. The media type in this example is image and the subtype identifier is jpeg. The top-level media type is meant to be a general categorization about the content of the file, while the subtype identifer is meant to specifically identify the format of the file. There are eight media types currently blessed by the IANA [Internet Assigned Naming Authority]. These eight media types are application audio image message model multipart text video . Many subtypes exist for each media type; for more information, see MIME Media Types at the IANA web site. Implementation of MIME types in GNOME follows the XDG shared mime info specification. This specification provides the following advantages: Standard locations for all MIME related files. A standard way for applications to register information about a new MIME type. A standard way to retrieve the MIME type for a file. A standard way to retrieve information about a MIME type. The rest of the chapter describes the files and directories that make up the MIME database, details about source XML files, how to create or modify MIME types, how to register applications as handlers for certain MIME types and finally, how to add an application to the GNOME desktop. The MIME Database MIME types database The MIME database is a collection of files that make up: The set of known MIME types The method for determing the MIME type of a file Meta information regarding a MIME type, such as a human readable description to use when displaying files of this type. Location As an administrator, the most important and basic step to understanding the MIME system is learning the locations where these files are stored. Since the XDG shared mime info specification was drafted by the X Desktop Group, it also makes use of the XDG base directory specification. It is highly recommended that you familiarize yourself with this specification, as it is also important for other system administration tasks such as editing menus. A brief summary of the directory locations as pertaining to the MIME specification is given below. The MIME database is created from the set of files located in the $XDG_DATA_HOME/mime and $XDG_DATA_DIRS/mime directories. If these environment variables are unset, then they default to the values ~/.local/share and /usr/local/share:/usr/share respectively. As can be seen from the default value for $XDG_DATA_DIRS , each environment variable is actually a colon separated list of directories. The user's database at $XDG_DATA_HOME/mime has precedence over the system database at $XDG_DATA_DIRS/mime when conflicting definitions are encountered. Similar to the XDG shared mime specification, we will refer to this set of directories as <MIME> in the rest of this document. For example, assuming default paths for the environment variables, Load <MIME>/text/plain.xml means to load the following files: ~/.local/share/mime/text/plain.xml /usr/local/share/mime/text/plain.xml /usr/share/mime/text/plain.xml Contents The following is a list of directories and files that are found inside the MIME database along with brief descriptions: <MIME>/packages/ This directory contains any number of XML files, each of which describe a collection of MIME types. By default, the freedesktop.org.xml file is installed in the /usr/share/mime/packages directory. This file contains all the default MIME types that are widely used and recognized. Applications which provide information about new MIME types are to install a single new XML file here. Depending on the prefix where the application is installed, it will create the file in the /mime/package subdirectory of one of the directories in $XDG_DATA_HOME:$XDG_DATA_DIRS. For example, an application installed to /usr/bin should install a new source XML file to the /usr/share/mime/packages directory. For more information about the XML files in the packages directory, please see . <MIME>/MEDIA/SUBTYPE.xml These directories and files are automatically generated from the collection of source XML files in the <MIME>/packages/ subdirectory by the update-mime-database application. For example, for each mime-type element in the /usr/share/mime/packages/freedesktop.org.xml file, a directory is created at /usr/share/mime/ with the media type of the MIME type. An XML file is created in that directory with the subtype identifier of that MIME type as well. The contents of the created XML file include comments (and translations for them), subclasses designations and aliases. Example: <filename>/usr/share/mime/text/plain.xml</filename> file <?xml version='1.0' encoding='utf-8'?> <mime-type xmlns="http://www.freedesktop.org/standards/shared-mime-info" type="text/plain">  <comment>plain text document</comment>  <comment xml:lang="es">documento de texto sencillo</comment> <comment xml:lang="eu">testu soileko dokumentua</comment> <comment xml:lang="fi">perustekstiasiakirja</comment> <comment xml:lang="fr">document plein texte</comment>  </mime-type> This file is generated by the update-mime-database application, using the default source XML file freedesktop.org.xml. <MIME>/globs Contains one line with a MIME type and a glob pattern, separated by a colon. Files which match the glob pattern are resolved to the MIME type specified before the colon. There are special rules about how filenames are matched by the glob pattern; for more details see the XDG shared mime specification. This file is also generated by the update-mime-database application, using the default source XML file freedesktop.org.xml. <MIME>/magic A binary file which contains information on how to resolve MIME types by sniffing the content of the file. This is generally a set of one or more rules such as check for the string %PDF- at byte offset 0 in the file; if found, assign it the MIME type application/pdf. This file is also generated by the update-mime-database application. <MIME>/XMLnamespaces Contains a mapping of XML namespaces to MIME types. Each line contains three fields, the namespace, the localName and the MIME type. Each field is separated by a space. If the localName is empty, then there are two spaces between the namespace and the MIME type. This file is also generated by the update-mime-database application. <MIME>/aliases Contains a list of aliases for each MIME type. An alias is simply a MIME type that is sometimes known as another type. For each line in this file there are two fields: the first field is the alias name, and the second field is the MIME type. The fields are separated by a space. This file is also generated by the update-mime-database application. <MIME>/subclasses Contains a list of subclassed MIME types and their parent MIME type. From the XDG shared mime specification:

A type is a subclass of another type if any instance of the first type is also an instance of the second. For example, all image/svg files are also text/xml, text/plain and application/octet-stream files. Subclassing is about the format, rather than the catagory of the data (for example, there is no 'generic spreadsheet' class that all spreadsheets inherit from).

The format of this file is similar to the aliases file. Each line contains two fields, where the first field is the subclassed MIME type and the second field is the parent MIME type. Each field is separated by a space. This file is also generated by the update-mime-database application. Refreshing the MIME Database Understanding how to refresh the MIME database is important for administrators who wish to add new MIME types to the system, or otherwise modify information about a MIME type. The application update-mime-database is intended for this purpose. For example, if an application installs information about a new MIME type to /usr/share/mime/packages/diff.xml, then update-mime-database must be called with the parameter /usr/share/mime. # update-mime-database /usr/share/mime *** * Updating MIME database in /usr/share/mime... *** The MIME database is refreshed by scanning all the source XML files in the directory <MIME>/packages. The source XML files MIME types source XML files Located in the <MIME>/packages directory, these XML files provide all the information regarding MIME types that is installed into the database by the update-mime-database application. There are a few rules about the XML file itself: It must specify the namespace as http://www.freedesktop.org/standards/shared-mime-info The root element must be mime-info Zero or more mime-type elements can be specified as children of the mime-info element. The type attribute is used to specify the MIME type that is being defined. By default, the freedesktop.org.xml file is installed to the packages directory in one of the <MIME> paths (usually /usr/share/mime/packages). gives a brief description for each of the elements that can occur as children to the mime-type element. Child elements of <literal><mime-type></literal> Element (and attributes) Description <glob pattern="*.xyz"> This element specifies a glob pattern against filenames. If the filename matches, then it is assigned the MIME type of the parent mime-type element. The pattern attribute is mandatory. <magic priority="50"> This element contains a list of match elements as its children. The priority attribute is optional, and specifies a priority between 0 and 100, with 100 being the highest matching priority. Each child match element has three required attributes: type offset value and a fourth optional attribute, mask. For details on these attributes, see the XDG shared mime info specification. <alias type="media/subtype"> This element defines an alias for the parent mime-type element. An alias is simply a MIME type that is sometimes known as another type. For example, application/x-pdf is an alias for the MIME type application/pdf. <sub-class-of type="media/subtype"> This element defines the parent mime-type element as a subclass of the MIME type specified in the type attribute. For example, image/svg is a sub class of the MIME type text/xml, text/plain, and application/octet-stream. <comment xml:lang="locale"> This element provides a human readable description for the MIME type. There can be zero or more occurrences of this element as long as each one contains a unique value for the xml:lang attribute. <root-XML namespaceURI="namespace" localName=""> If a file is determined to an XML file, then this element helps to further classify it through the use of the namespaceURI and localName attributes, both of which are required. The attribute namespaceURI is the namespace of the document, and localName is the name of the root element for the document. If localName is present but its value is empty, then the root element may have any name, but the namespace must still match.

The easiest way to understand these files is to take a look at an example. Borrowing from the XDG shared mime specification, displays the contents of a source XML file called diff.xml. This example defines the MIME type text/x-diff. There are multiple comment elements which give a human readable name to the MIME type in a number of different languages. This MIME type has both rules for matching through glob patterns and through the use of content sniffing (better known as magic rules). Any file with the extension .diff or .patch will resolve to this MIME type. Additionally any file whose contents start with the strings specified in the value attributes of the match element, will resolve to the text/x-diff MIME type. The order in which glob patterns and magic rules apply is beyond the scope of this document. For details on this, see the XDG shared mime info specification. Example of a source XML file: <filename>diff.xml</filename> <?xml version='1.0'?> <mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'> <mime-type type="text/x-diff"> <comment>Differences between files</comment> <comment xml:lang="af">verskille tussen lêers</comment>  <magic priority="50"> <match type="string" offset="0" value="diff\t"/> <match type="string" offset="0" value="***\t"/> <match type="string" offset="0" value="Common subdirectories: "/> </magic> <glob pattern="*.diff"/> <glob pattern="*.patch"/> </mime-type> </mime-info> Modifying MIME types MIME types verifying changes MIME types modifying You should never directly modify the source XML files that are installed to the <MIME>/packages directory by applications. Instead, modify the Overrides.xml file. This file has precedence over all other source XML files installed into the same packages directory. If you are an application author, then this rule does not apply. You should create a new source XML file and place it in the proper <MIME>/packages directory (your Makefile will take care of this, of course). You can modify the MIME database for all users on the system or for a particular user depending on the location of the file you change. To modify the database for all users, make changes to the file Overrides.xml in the $XDG_DATA_DIRS/mime/packages directory. To modify the database for a single user, make changes to the file Overrides.xml in the $XDG_DATA_HOME/mime/packages directory. After changes are made, you must always run the update-mime-database application, with the directory location of the MIME database as the first parameter. Adding or Modifying MIME types To add one or more MIME types for all users: Create or modify an existing Overrides.xml source XML file, containing the definitions for the MIME types. For more information, see . Place the Overrides.xml file in the /usr/share/mime/packages directory. Update the MIME database by running update-mime-database using the system account.update-mime-database /usr/share/mime To add one or more MIME types for a single user, follow the same steps, except place your Overrides.xml file in the ~/.local/share/mime/packages directory. Additionally, call update-mime-database with ~/.local/share/mime/packages as the first parameter. Verifying Changes After you have made a change to the MIME database and refreshed its contents, you can verify that the change has taken effect using the gnomevfs-info application. This application prints the MIME type and other useful information about a file. Running gnomevfs-info on a SVG file gives you the output shown below. You'll notice the default application for this MIME type is eog.desktop; We will discuss default applications in . $ gnomevfs-info mime-diagram.svg Name : mime-diagram.svg Type : Regular MIME type : image/svg+xml Default app : eog.desktop Size : 14869 Blocks : 32 I/O block size : 4096 Local : YES SUID : NO SGID : NO Sticky : NO Permissions : 600644 Link count : 1 UID : 1000 GID : 100 Access time : Wed Feb 22 18:24:47 2006 Modification time : Wed Feb 22 18:24:42 2006 Change time : Wed Feb 22 18:24:42 2006 Device # : 775 Inode # : 297252 Readable : YES Writable : YES Executable : NO $ walks through the steps of creating a new MIME type and then verifying the changes using gnomevfs-info. <literal>application/x-newtype</literal> Example To create (or override) a MIME type and verify the changes: Make a new, empty file in your home directory called testing.xyz. Use gnomevfs-info on the file to find out the MIME type.The MIME type for this file should be detected as text/plain because there are not any glob patterns or magic rules that match it When no glob patterns or magic rules match a file, then it is resolved to the MIME type text/plain if it contains textual data or application/octet-stream for binary data. If the file is empty, then it defaults to text/plain. . Create (or modify) the Overrides.xml file as described in with the contents given in . Refresh the database using update-mime-database. Use gnomevfs-info to verify that your change has taken effect. You should see the MIME type for the testing.xyz file resolved as application/x-newtype. $ gnomevfs-info testing.xyz | grep MIME MIME type : application/x-newtype $ <filename>Overrides.xml</filename> file <?xml version='1.0' encoding='utf-8'?> <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"> <mime-type type="application/x-newtype"><comment>new mime type</comment><glob pattern="*.xyz"/></mime-type> </mime-info> Registering Applications for MIME Types MIME types registering applications for applications registry Registering applications to handle MIME types is fairly straightforward. Applications are registered by creating a MimeType key in their .desktop entry file and listing each MIME type separated by a semicolon. The MimeType key should only be used in .desktop files whose Type key has the value Application. For more information on .desktop files, see . After creating or modifying a .desktop entry file, you must update the application database using the update-desktop-database application (very similar to update-mime-database, except it does not take a parameter). This will create a mimeinfo.cache file in the applications subdirectory for each directory in $XDG_DATA_HOME:$XDG_DATA_DIRS. The cache file is necessary so that all the .desktop files do not need to be scanned for just the MimeType key, as this causes unnecessary disk I/O. Default applications to use for specific MIME types should be specified in a file called defaults.list. This file is located in the applications subdirectory for each directory in $XDG_DATA_HOME and $XDG_DATA_DIRS. The format for this file consists of the MIME type, the = symbol and the Desktop File ID (which is the filename for the desktop entry file). is a short example of a defaults.list file in a user's ~/.local/share/applications directory. A User's <filename>defaults.list</filename> file [Default Applications] application/pdf=evince.desktop text/html=epiphany.desktop text/plain=gedit.desktop image/jpeg=eog.desktop image/png=eog.desktop text/xml=gedit.desktop XDG Desktop Entry Specification How to register MIME types for applications is part of the XDG desktop entry specification, rather than the XDG shared mime info specification. Adding an Application to the GNOME Desktop MIME types adding applications applications adding To add an application to the GNOME Desktop, perform the following steps: Add a menu item for the application. For more information on how to add an item to a menu, see . Add an icon for the application to /usr/share/icons/theme-name/icon-size/apps. For more information on icons and themes, see . If the application uses a new MIME type, add a source XML file to the MIME database. For more information, see . If the application uses a new MIME type, add an icon for the MIME type to /usr/share/icons/theme-name/icon-size/mimetypes. For more information on icons and themes, see . To associate the application with a MIME type, include a MimeType key in your .desktop file. For more information, see .