DBUS_API_SUBJECT_TO_CHANGE

#define DBUS_API_SUBJECT_TO_CHANGE

enum HildonMimeCategory

typedef enum {
	HILDON_MIME_CATEGORY_BOOKMARKS = 1 << 0,
	HILDON_MIME_CATEGORY_CONTACTS  = 1 << 1,
	HILDON_MIME_CATEGORY_DOCUMENTS = 1 << 2,
	HILDON_MIME_CATEGORY_EMAILS    = 1 << 3,
	HILDON_MIME_CATEGORY_IMAGES    = 1 << 4,
	HILDON_MIME_CATEGORY_AUDIO     = 1 << 5,
	HILDON_MIME_CATEGORY_VIDEO     = 1 << 6,
	HILDON_MIME_CATEGORY_OTHER     = 1 << 7,
	HILDON_MIME_CATEGORY_ALL       = (1 << 8) - 1
} HildonMimeCategory;

hildon_mime_get_category_for_mime_type ()

HildonMimeCategory  hildon_mime_get_category_for_mime_type
                                                        (const gchar *mime_type);

This function returns the HildonMimeCategory for the specified mime_type. See hildon_mime_get_mime_types_for_category() for more information.

Return: The category that the mime_type is in.

hildon_mime_get_mime_types_for_category ()

GList*              hildon_mime_get_mime_types_for_category
                                                        (HildonMimeCategory category);

This function returns a GList of const gchar pointer mime types that are in the specified category.

The mapping between category and mime type is handled through the shared mime info. Add the tag <category></category> to a mime type to specify that the mime type is in the category "name". Valid category names are:

audio, bookmarks, contacts, documents, emails, images, video

An example:

<mime-type> <category></category> </mime-type>

Return: A newly allocated GList which should be freed with hildon_mime_types_list_free() OR NULL if none were found.

hildon_mime_types_list_free ()

void                hildon_mime_types_list_free         (GList *list);

Frees the list of mime types returned by hildon_mime_get_mime_types_for_category().

hildon_mime_open_file ()

gint                hildon_mime_open_file               (DBusConnection *con,
                                                         const gchar *file);

This function opens a file in the application that has registered as the handler for the mime type of the file.

The file parameter must be a full URI, that is to say that it must be in the form of 'file:///etc/hosts'.

The mapping from mime type to D-BUS service is done by looking up the application for the mime type and in the desktop file for that application the X-Osso-Service field is used to get the D-BUS service.

This function operates asynchronously, this means that if D-BUS has to open the application that handles this file type and your application quits prematurely, the application may not open the file. An event loop is expected to be used here to ensure D-BUS has a chance to send the message if the application isn't already started.

Return: 1 in case of success, < 1 if an error occurred or if some parameter is invalid.

hildon_mime_open_file_list ()

gint                hildon_mime_open_file_list          (DBusConnection *con,
                                                         GSList *files);

This function opens a list of files. The files will be sent to each application that handles their MIME-type. If more then one type of file is specified, many applications may be launched.

For more information on opening files, see hildon_mime_open_file().

Return: 1 in case of success, < 1 if an error occurred or if some parameter is invalid.

hildon_mime_open_file_with_mime_type ()

gint                hildon_mime_open_file_with_mime_type
                                                        (DBusConnection *con,
                                                         const gchar *file,
                                                         const gchar *mime_type);

This function opens file in the application that has registered as the handler for mime_type.

The file is optional. If it is omitted, the mime_type is used to know which application to launch.

For more information on opening files, see hildon_mime_open_file().

Return: 1 in case of success, < 1 if an error occurred or if some parameter is invalid.

hildon_mime_get_category_name ()

const gchar*        hildon_mime_get_category_name       (HildonMimeCategory category);

This function returns the name of the specified category.

Return: The const gchar pointer name of the category, this should not be freed or modified.

hildon_mime_get_category_from_name ()

HildonMimeCategory  hildon_mime_get_category_from_name  (const gchar *category);

This function returns the HildonMimeCategory corresponding to category.

Return: The HildonMimeCategory.

hildon_mime_application_get_mime_types ()

GList*              hildon_mime_application_get_mime_types
                                                        (const gchar *application_id);

hildon_mime_application_mime_types_list_free ()

void                hildon_mime_application_mime_types_list_free
                                                        (GList *mime_types);

Frees the list of mime_types as returned by hildon_mime_application_get_mime_types().

hildon_mime_get_icon_names ()

gchar**             hildon_mime_get_icon_names          (const gchar *mime_type,
                                                         GnomeVFSFileInfo *file_info);

This function returns a NULL terminated array of icon names for the specified mime_type. The icon names are GtkIconTheme names. A number of names are returned, ordered by how specific they are. For example, if the mime type "image/png" is passed, the first icon name might correspond to a png file, the second to an image file, and the third to a regular file.

In order to decide which icon to use, the existance of it in the icon theme should be checked with gtk_icon_theme_has_icon(). If the first icon is not available, try the next etc.

The optional GnomeVFSFileInfo struct is used to get additional information about a file or directory that might help to get the right icon.

Return: A newly allocated array of icon name strings which should be freed with g_strfreev() OR NULL if none were found.