introduction

   Because filename can be any valid characters except several special char such as '/' and '\0', so filename can be in any encoding, and because there is no way to tell the encoding of one filename, so it is often hard to handle filename across different locale/encoding.In order to access file on the disk through filename, GNOME use URI to represent filename. The biggest advantange of this method is that URIs are independent of current locale, that is to say: No matter what locale you are running your application, you get the same URI filename for the same file one the disk.

How convert filename to URI

GNOME has several method to convert one filename to URI.

• g_filename_to_uri(): this function converts an absolute filename to an escaped ASCII-encoded URI. absolute filename contain hostname (which must be UTF-8 encoded) and filename (which is the on-disk filename bytes on Unix, and UTF-8 on Windows)
• gnome_vfs_escape_string(): this function is similar to g_filename_to_uri(). eel library encapsulate this funcation and provide more flexible API.

The core code is following:

g_escape_uri_string (const gchar *string,
             UnsafeCharacterSet mask)
{
#define ACCEPTABLE(a) ((a)>=32 && (a)<128 && (acceptable[(a)-32] & use_mask))

  const gchar *p;
  gchar *q;
  gchar *result;
  int c;
  gint unacceptable;
  UnsafeCharacterSet use_mask;
 
  g_return_val_if_fail (mask == UNSAFE_ALL
            || mask == UNSAFE_ALLOW_PLUS
            || mask == UNSAFE_PATH
            || mask == UNSAFE_HOST
            || mask == UNSAFE_SLASHES, NULL);
 
  unacceptable = 0;
  use_mask = mask;
  for (p = string; *p != '\0'; p++)
    {
      c = (guchar) *p;
      if (!ACCEPTABLE (c))
    unacceptable++;
    }
 
  result = g_malloc (p \- string + unacceptable * 2 + 1);
 
  use_mask = mask;
  for (q = result, p = string; *p != '\0'; p++)
    {
      c = (guchar) *p;
     
      if (!ACCEPTABLE (c))
    {
      *q++ = '%'; /* means hex coming */
      *q++ = hex[c >> 4];
      *q++ = hex[c & 15];
    }
      else
    *q++ = *p;
    }
 
  *q = '\0';
 
  return result;
}

Example Usage:

Gnome will save recently used files in to $HOME/.recently-used file, and save URI filename in this file. Open several different encoded filename on different locale, you can see that the URI for filename is the same escaped-ASCII string.