Doc fixes
[platform/upstream/glib.git] / gio / gcontenttype.c
index 5952cac..2c48a77 100644 (file)
@@ -1,3 +1,5 @@
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
+
 /* GIO - GLib Input, Output and Streaming Library
  * 
  * Copyright (C) 2006-2007 Red Hat, Inc.
  */
 
 #include <config.h>
-
 #include <sys/types.h>
-#include <dirent.h>
 #include <string.h>
 #include <stdio.h>
-
 #include "gcontenttypeprivate.h"
+#include "gthemedicon.h"
 #include "glibintl.h"
 
-/* A content type is a platform specific string that defines the type
-   of a file. On unix it is a mime type, on win32 it is an extension string
-   like ".doc", ".txt" or a percieved string like "audio". Such strings
-   can be looked up in the registry at HKEY_CLASSES_ROOT.
-*/
+#include "gioalias.h"
+
+/**
+ * SECTION:gcontenttype
+ * @short_description: Platform-specific content typing
+ * @include: gio/gio.h
+ *
+ * A content type is a platform specific string that defines the type
+ * of a file. On unix it is a mime type, on win32 it is an extension string
+ * like ".doc", ".txt" or a percieved string like "audio". Such strings
+ * can be looked up in the registry at HKEY_CLASSES_ROOT.
+ **/
 
 #ifdef G_OS_WIN32
 
 #include <windows.h>
 
 static char *
-get_registry_classes_key (const char *subdir,
+get_registry_classes_key (const char    *subdir,
                          const wchar_t *key_name)
 {
   wchar_t *wc_key;
@@ -75,16 +82,6 @@ get_registry_classes_key (const char *subdir,
   return value_utf8;
 }
 
-/**
- * g_content_type_equals:
- * @type1: a content type string.
- * @type2: a content type string.
- *
- * Compares two content types for equality.
- *
- * Returns: %TRUE if the two strings are identical or equivalent,
- * %FALSE otherwise.
- **/  
 gboolean
 g_content_type_equals (const char *type1,
                       const char *type2)
@@ -110,19 +107,9 @@ g_content_type_equals (const char *type1,
   return res;
 }
 
-/**
- * g_content_type_is_a:
- * @type: a content type string. a content type string.
- * @supertype: a string.
- *
- * Determines if @type is a subset of @supertype.  
- *
- * Returns: %TRUE if @type is a kind of @supertype,
- * %FALSE otherwise. 
- **/  
 gboolean
-g_content_type_is_a (const char   *type,
-                    const char   *supertype)
+g_content_type_is_a (const char *type,
+                    const char *supertype)
 {
   gboolean res;
   char *value_utf8;
@@ -142,12 +129,6 @@ g_content_type_is_a (const char   *type,
   return res;
 }
 
-/**
- * g_content_type_is_unknown:
- * @type: a content type string. a content type string.
- * 
- * Returns:
- **/  
 gboolean
 g_content_type_is_unknown (const char *type)
 {
@@ -156,12 +137,6 @@ g_content_type_is_unknown (const char *type)
   return strcmp ("*", type) == 0;
 }
 
-/**
- * g_content_type_get_description:
- * @type: a content type string. a content type string.
- * 
- * Returns: a short description of the content type @type. 
- **/  
 char *
 g_content_type_get_description (const char *type)
 {
@@ -185,14 +160,8 @@ g_content_type_get_description (const char *type)
   return g_strdup_printf (_("%s filetype"), type);
 }
 
-/**
- * g_content_type_get_mime_type:
- * @type: a content type string. a content type string.
- * 
- * Returns: the registered mime-type for the given @type.
- **/  
 char *
-g_content_type_get_mime_type (const char   *type)
+g_content_type_get_mime_type (const char *type)
 {
   char *mime;
 
@@ -210,14 +179,8 @@ g_content_type_get_mime_type (const char   *type)
   return g_strdup ("application/octet-stream");
 }
 
-/**
- * g_content_type_get_icon:
- * @type: a content type string. a content type string.
- * 
- * Returns: #GIcon corresponding to the content type.
- **/  
 GIcon *
-g_content_type_get_icon (const char   *type)
+g_content_type_get_icon (const char *type)
 {
   g_return_val_if_fail (type != NULL, NULL);
 
@@ -231,16 +194,8 @@ g_content_type_get_icon (const char   *type)
   return NULL;
 }
 
-/**
- * g_content_type_can_be_executable:
- * @type: a content type string.
- * 
- * Returns: %TRUE if the file type corresponds to something that
- * can be executable, %FALSE otherwise. Note that for instance
- * things like textfiles can be executables (i.e. scripts)
- **/  
 gboolean
-g_content_type_can_be_executable (const char   *type)
+g_content_type_can_be_executable (const char *type)
 {
   g_return_val_if_fail (type != NULL, FALSE);
 
@@ -252,7 +207,8 @@ g_content_type_can_be_executable (const char   *type)
 }
 
 static gboolean
-looks_like_text (const guchar *data, gsize data_size)
+looks_like_text (const guchar *data, 
+                 gsize         data_size)
 {
   gsize i;
   guchar c;
@@ -265,18 +221,6 @@ looks_like_text (const guchar *data, gsize data_size)
   return TRUE;
 }
 
-/**
- * g_content_type_guess:
- * @filename: a string.
- * @data: a stream of data.
- * @data_size: the size of @data.
- * @result_uncertain: a flag indicating the certainty of the 
- * result.
- * 
- * Returns: a string indicating a guessed content type for the 
- * given data. If the function is uncertain, @result_uncertain 
- * will be set to %TRUE.
- **/  
 char *
 g_content_type_guess (const char   *filename,
                      const guchar *data,
@@ -307,11 +251,6 @@ g_content_type_guess (const char   *filename,
   return g_strdup ("*");
 }
 
-/**
- * g_content_types_get_registered:
- * 
- * Returns: #GList of the registered content types.
- **/  
 GList *
 g_content_types_get_registered (void)
 {
@@ -350,6 +289,8 @@ g_content_types_get_registered (void)
 
 #else /* !G_OS_WIN32 - Unix specific version */
 
+#include <dirent.h>
+
 #define XDG_PREFIX _gio_xdg
 #include "xdgmime/xdgmime.h"
 
@@ -384,7 +325,7 @@ char **
 _g_unix_content_type_get_parents (const char *type)
 {
   const char *umime;
-  const char **parents;
+  char **parents;
   GPtrArray *array;
   int i;
 
@@ -393,12 +334,15 @@ _g_unix_content_type_get_parents (const char *type)
   G_LOCK (gio_xdgmime);
   
   umime = xdg_mime_unalias_mime_type (type);
+  
   g_ptr_array_add (array, g_strdup (umime));
   
-  parents = xdg_mime_get_mime_parents (umime);
+  parents = xdg_mime_list_mime_parents (umime);
   for (i = 0; parents && parents[i] != NULL; i++)
     g_ptr_array_add (array, g_strdup (parents[i]));
   
+  free (parents);
+  
   G_UNLOCK (gio_xdgmime);
   
   g_ptr_array_add (array, NULL);
@@ -406,9 +350,19 @@ _g_unix_content_type_get_parents (const char *type)
   return (char **)g_ptr_array_free (array, FALSE);
 }
 
+/**
+ * g_content_type_equals:
+ * @type1: a content type string.
+ * @type2: a content type string.
+ *
+ * Compares two content types for equality.
+ *
+ * Returns: %TRUE if the two strings are identical or equivalent,
+ * %FALSE otherwise.
+ **/  
 gboolean
-g_content_type_equals (const char   *type1,
-                      const char   *type2)
+g_content_type_equals (const char *type1,
+                      const char *type2)
 {
   gboolean res;
   
@@ -422,9 +376,19 @@ g_content_type_equals (const char   *type1,
   return res;
 }
 
+/**
+ * g_content_type_is_a:
+ * @type: a content type string. 
+ * @supertype: a string.
+ *
+ * Determines if @type is a subset of @supertype.  
+ *
+ * Returns: %TRUE if @type is a kind of @supertype,
+ * %FALSE otherwise. 
+ **/  
 gboolean
-g_content_type_is_a (const char   *type,
-                    const char   *supertype)
+g_content_type_is_a (const char *type,
+                    const char *supertype)
 {
   gboolean res;
     
@@ -438,6 +402,16 @@ g_content_type_is_a (const char   *type,
   return res;
 }
 
+/**
+ * g_content_type_is_unknown:
+ * @type: a content type string. 
+ * 
+ * Checks if the content type is the generic "unknown" type.
+ * On unix this is the "application/octet-stream" mimetype,
+ * while on win32 it is "*".
+ * 
+ * Returns: %TRUE if the type is the unknown type.
+ **/  
 gboolean
 g_content_type_is_unknown (const char *type)
 {
@@ -478,12 +452,12 @@ language_level (const char *lang)
 }
 
 static void
-mime_info_start_element (GMarkupParseContext *context,
-                        const gchar         *element_name,
-                        const gchar        **attribute_names,
-                        const gchar        **attribute_values,
-                        gpointer             user_data,
-                        GError             **error)
+mime_info_start_element (GMarkupParseContext  *context,
+                        const gchar          *element_name,
+                        const gchar         **attribute_names,
+                        const gchar         **attribute_values,
+                        gpointer              user_data,
+                        GError              **error)
 {
   int i;
   const char *lang;
@@ -508,10 +482,10 @@ mime_info_start_element (GMarkupParseContext *context,
 }
 
 static void
-mime_info_end_element (GMarkupParseContext *context,
-                      const gchar         *element_name,
-                      gpointer             user_data,
-                      GError             **error)
+mime_info_end_element (GMarkupParseContext  *context,
+                      const gchar          *element_name,
+                      gpointer              user_data,
+                      GError              **error)
 {
   MimeParser *parser = user_data;
   
@@ -519,11 +493,11 @@ mime_info_end_element (GMarkupParseContext *context,
 }
 
 static void
-mime_info_text (GMarkupParseContext *context,
-               const gchar         *text,
-               gsize                text_len,  
-               gpointer             user_data,
-               GError             **error)
+mime_info_text (GMarkupParseContext  *context,
+               const gchar          *text,
+               gsize                 text_len,  
+               gpointer              user_data,
+               GError              **error)
 {
   MimeParser *parser = user_data;
 
@@ -537,7 +511,8 @@ mime_info_text (GMarkupParseContext *context,
 }
 
 static char *
-load_comment_for_mime_helper (const char *dir, const char *basename)
+load_comment_for_mime_helper (const char *dir, 
+                              const char *basename)
 {
   GMarkupParseContext *context;
   char *filename, *data;
@@ -602,6 +577,14 @@ load_comment_for_mime (const char *mimetype)
   return g_strdup_printf (_("%s type"), mimetype);
 }
 
+/**
+ * g_content_type_get_description:
+ * @type: a content type string. 
+ * 
+ * Gets the human readable description of the content type.
+ * 
+ * Returns: a short description of the content type @type. 
+ **/  
 char *
 g_content_type_get_description (const char *type)
 {
@@ -611,6 +594,8 @@ g_content_type_get_description (const char *type)
   g_return_val_if_fail (type != NULL, NULL);
   
   G_LOCK (gio_xdgmime);
+  type = xdg_mime_unalias_mime_type (type);
+
   if (type_comment_cache == NULL)
     type_comment_cache = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, g_free);
 
@@ -632,33 +617,76 @@ g_content_type_get_description (const char *type)
   return comment;
 }
 
+/**
+ * g_content_type_get_mime_type:
+ * @type: a content type string. 
+ * 
+ * Gets the mime-type for the content type. If one is registered
+ * 
+ * Returns: the registered mime-type for the given @type, or NULL if unknown.
+ **/  
 char *
-g_content_type_get_mime_type (const char   *type)
+g_content_type_get_mime_type (const char *type)
 {
   g_return_val_if_fail (type != NULL, NULL);
 
   return g_strdup (type);
 }
 
+/**
+ * g_content_type_get_icon:
+ * @type: a content type string.
+ * 
+ * Gets the icon for a content type.
+ * 
+ * Returns: #GIcon corresponding to the content type.
+ **/  
 GIcon *
-g_content_type_get_icon (const char   *type)
+g_content_type_get_icon (const char *type)
 {
+  char *mimetype_icon, *generic_mimetype_icon, *p;
+  char *icon_names[2];
+  GThemedIcon *themed_icon;
+  
   g_return_val_if_fail (type != NULL, NULL);
-
-  /* TODO: Implement */
-  return NULL;
+  
+  mimetype_icon = g_strdup (type);
+  
+  while ((p = strchr (mimetype_icon, '/')) != NULL)
+    *p = '-';
+  
+  p = strchr (type, '/');
+  if (p == NULL)
+    p = type + strlen (type);
+  
+  generic_mimetype_icon = g_malloc (p - type + strlen ("-x-generic") + 1);
+  memcpy (generic_mimetype_icon, type, p - type);
+  memcpy (generic_mimetype_icon + (p - type), "-x-generic", strlen ("-x-generic"));
+  generic_mimetype_icon[(p - type) + strlen ("-x-generic")] = 0;
+  
+  icon_names[0] = mimetype_icon;
+  icon_names[1] = generic_mimetype_icon;
+  
+  themed_icon = g_themed_icon_new_from_names (icon_names, 2);
+  
+  g_free (mimetype_icon);
+  g_free (generic_mimetype_icon);
+  
+  return G_ICON (themed_icon);
 }
 
 /**
  * g_content_type_can_be_executable:
  * @type: a content type string.
  * 
- * Returns: %TRUE if the file type corresponds to something that
- * can be executable, %FALSE otherwise. Note that for instance
- * things like textfiles can be executables (i.e. scripts)
+ * Checks if a content type can be executable. Note that for instance
+ * things like text files can be executables (i.e. scripts and batch files).
+ * 
+ * Returns: %TRUE if the file type corresponds to a type that
+ * can be executable, %FALSE otherwise. 
  **/  
 gboolean
-g_content_type_can_be_executable (const char   *type)
+g_content_type_can_be_executable (const char *type)
 {
   g_return_val_if_fail (type != NULL, FALSE);
 
@@ -673,14 +701,33 @@ static gboolean
 looks_like_text (const guchar *data, gsize data_size)
 {
   gsize i;
+  char c;
+  
   for (i = 0; i < data_size; i++)
     {
-      if g_ascii_iscntrl (data[i])
+      c = data[i];
+      
+      if (g_ascii_iscntrl (c) &&
+         !g_ascii_isspace (c))
        return FALSE;
     }
   return TRUE;
 }
 
+/**
+ * g_content_type_guess:
+ * @filename: a string.
+ * @data: a stream of data.
+ * @data_size: the size of @data.
+ * @result_uncertain: a flag indicating the certainty of the 
+ * result.
+ * 
+ * Guesses the content type based on example data. If the function is 
+ * uncertain, @result_uncertain will be set to %TRUE.
+ * 
+ * Returns: a string indicating a guessed content type for the 
+ * given data. 
+ **/  
 char *
 g_content_type_guess (const char   *filename,
                      const guchar *data,
@@ -773,19 +820,10 @@ g_content_type_guess (const char   *filename,
   return mimetype;
 }
 
-static gboolean
-foreach_mimetype (gpointer  key,
-                 gpointer  value,
-                 gpointer  user_data)
-{
-  GList **l = user_data;
-
-  *l = g_list_prepend (*l, (char *)key);
-  return TRUE;
-}
-
 static void
-enumerate_mimetypes_subdir (const char *dir, const char *prefix, GHashTable *mimetypes)
+enumerate_mimetypes_subdir (const char *dir, 
+                            const char *prefix, 
+                            GHashTable *mimetypes)
 {
   DIR *d;
   struct dirent *ent;
@@ -807,7 +845,8 @@ enumerate_mimetypes_subdir (const char *dir, const char *prefix, GHashTable *mim
 }
 
 static void
-enumerate_mimetypes_dir (const char *dir, GHashTable *mimetypes)
+enumerate_mimetypes_dir (const char *dir, 
+                         GHashTable *mimetypes)
 {
   DIR *d;
   struct dirent *ent;
@@ -835,15 +874,25 @@ enumerate_mimetypes_dir (const char *dir, GHashTable *mimetypes)
   g_free (mimedir);
 }
 
+/**
+ * g_content_types_get_registered:
+ * 
+ * Gets a list of strings containing all the registered content types
+ * known to the system. The list and its data should be freed using 
+ * @g_list_foreach(list, g_free, NULL) and @g_list_free(list)
+ * Returns: #GList of the registered content types.
+ **/  
 GList *
 g_content_types_get_registered (void)
 {
   const char * const* dirs;
   GHashTable *mimetypes;
+  GHashTableIter iter;
+  gpointer key;
   int i;
   GList *l;
 
-  mimetypes = g_hash_table_new_full (g_str_hash, g_str_equal, g_free, NULL);
+  mimetypes = g_hash_table_new (g_str_hash, g_str_equal);
 
   enumerate_mimetypes_dir (g_get_user_data_dir (), mimetypes);
   dirs = g_get_system_data_dirs ();
@@ -852,10 +901,16 @@ g_content_types_get_registered (void)
     enumerate_mimetypes_dir (dirs[i], mimetypes);
 
   l = NULL;
-  g_hash_table_foreach_steal (mimetypes, foreach_mimetype, &l);
+  g_hash_table_iter_init (&iter, mimetypes);
+  while (g_hash_table_iter_next (&iter, &key, NULL))
+    l = g_list_prepend (l, key);
+
   g_hash_table_destroy (mimetypes);
 
   return l;
 }
 
 #endif /* Unix version */
+
+#define __G_CONTENT_TYPE_C__
+#include "gioaliasdef.c"