GnomeVFSURI

## GnomeVFSURI GnomeVFSURI — A uniform resource identifier. |

## Synopsis

                        GnomeVFSURI;
                        GnomeVFSToplevelURI;
    enum                GnomeVFSURIHideOptions;
    #define             GNOME_VFS_URI_MAGIC_CHR
    #define             GNOME_VFS_URI_MAGIC_STR
    #define             GNOME_VFS_URI_PATH_CHR
    #define             GNOME_VFS_URI_PATH_STR
    GnomeVFSURI *       gnome_vfs_uri_new                   (const gchar *text_uri);
    GnomeVFSURI *       gnome_vfs_uri_resolve_relative      (const GnomeVFSURI *base,
                                                             const gchar *relative_reference);
    GnomeVFSURI *       gnome_vfs_uri_resolve_symbolic_link (const GnomeVFSURI *base,
                                                             const gchar *relative_reference);
    GnomeVFSURI *       gnome_vfs_uri_ref                   (GnomeVFSURI *uri);
    void                gnome_vfs_uri_unref                 (GnomeVFSURI *uri);
    GnomeVFSURI *       gnome_vfs_uri_append_string         (const GnomeVFSURI *uri,
                                                             const char *uri_fragment);
    GnomeVFSURI *       gnome_vfs_uri_append_path           (const GnomeVFSURI *uri,
                                                             const char *path);
    GnomeVFSURI *       gnome_vfs_uri_append_file_name      (const GnomeVFSURI *uri,
                                                             const gchar *filename);
    gchar *             gnome_vfs_uri_to_string             (const GnomeVFSURI *uri,
                                                             GnomeVFSURIHideOptions hide_options);
    GnomeVFSURI *       gnome_vfs_uri_dup                   (const GnomeVFSURI *uri);
    gboolean            gnome_vfs_uri_is_local              (const GnomeVFSURI *uri);
    gboolean            gnome_vfs_uri_has_parent            (const GnomeVFSURI *uri);
    GnomeVFSURI *       gnome_vfs_uri_get_parent            (const GnomeVFSURI *uri);
    GnomeVFSToplevelURI * gnome_vfs_uri_get_toplevel        (const GnomeVFSURI *uri);
    const gchar *       gnome_vfs_uri_get_host_name         (const GnomeVFSURI *uri);
    const gchar *       gnome_vfs_uri_get_scheme            (const GnomeVFSURI *uri);
    guint               gnome_vfs_uri_get_host_port         (const GnomeVFSURI *uri);
    const gchar *       gnome_vfs_uri_get_user_name         (const GnomeVFSURI *uri);
    const gchar *       gnome_vfs_uri_get_password          (const GnomeVFSURI *uri);
    void                gnome_vfs_uri_set_host_name         (GnomeVFSURI *uri,
                                                             const gchar *host_name);
    void                gnome_vfs_uri_set_host_port         (GnomeVFSURI *uri,
                                                             guint host_port);
    void                gnome_vfs_uri_set_user_name         (GnomeVFSURI *uri,
                                                             const gchar *user_name);
    void                gnome_vfs_uri_set_password          (GnomeVFSURI *uri,
                                                             const gchar *password);
    gboolean            gnome_vfs_uri_equal                 (const GnomeVFSURI *a,
                                                             const GnomeVFSURI *b);
    gboolean            gnome_vfs_uri_is_parent             (const GnomeVFSURI *possible_parent,
                                                             const GnomeVFSURI *possible_child,
                                                             gboolean recursive);
    const gchar *       gnome_vfs_uri_get_path              (const GnomeVFSURI *uri);
    const gchar *       gnome_vfs_uri_get_fragment_identifier
                                                            (const GnomeVFSURI *uri);
    gchar *             gnome_vfs_uri_extract_dirname       (const GnomeVFSURI *uri);
    gchar *             gnome_vfs_uri_extract_short_name    (const GnomeVFSURI *uri);
    gchar *             gnome_vfs_uri_extract_short_path_name
                                                            (const GnomeVFSURI *uri);
    gint                gnome_vfs_uri_hequal                (gconstpointer a,
                                                             gconstpointer b);
    guint               gnome_vfs_uri_hash                  (gconstpointer p);
    GList *             gnome_vfs_uri_list_parse            (const gchar *uri_list);
    GList *             gnome_vfs_uri_list_ref              (GList *list);
    GList *             gnome_vfs_uri_list_unref            (GList *list);
    GList *             gnome_vfs_uri_list_copy             (GList *list);
    void                gnome_vfs_uri_list_free             (GList *list);
    char *              gnome_vfs_uri_make_full_from_relative
                                                            (const char *base_uri,
                                                             const char *relative_uri);

## Description

A GnomeVFSURI is a semi-textual representation of a uniform resource identifier. It contains the information about a resource location encoded as canononicalized text, but also holds extra information about the context in which the URI is used.

## Details

### GnomeVFSURI

    typedef struct {
    	guint ref_count;

    	gchar *text;
    	gchar *fragment_id;

    	gchar *method_string;
    	struct GnomeVFSMethod *method;

    	struct GnomeVFSURI *parent;
    } GnomeVFSURI;

Holds information about the location of a particular resource.

guint `ref_count`; | Reference count. The URI is freed when it drops to zero.
gchar *`text`; | A canonical representation of the path associated with this resource.
gchar *`fragment_id`; | Extra data identifying this resource.
gchar *`method_string`; | The `method`'s method associated with this resource. One GnomeVFSMethod can be used for multiple method strings.
struct GnomeVFSMethod *`method`; | The GnomeVFSMethod associated with this resource.
struct GnomeVFSURI *`parent`; | Pointer to the parent element, or `NULL` for GnomeVFSURI that have no enclosing GnomeVFSURI. The process of encapsulating one URI in another one is called URI chaining.

### GnomeVFSToplevelURI

    typedef struct {
    	GnomeVFSURI uri;

    	gchar *host_name;
    	guint host_port;

    	gchar *user_name;
    	gchar *password;

    	gchar *urn;
    } GnomeVFSToplevelURI;

This is the toplevel URI element used to access ressources stored on a remote server. Toplevel method implementations should cast the GnomeVFSURI argument to this type to get the additional host and authentication information.

If any of the elements is 0 respectively `NULL`, it is unspecified.

GnomeVFSURI `uri`; |
gchar *`host_name`; | The name of the host used to access this resource, o `NULL`.
guint `host_port`; | The port used to access this resource, or `0`.
gchar *`user_name`; | Unescaped user name used to access this resource, or `NULL`.
gchar *`password`; | Unescaped password used to access this resource, or `NULL`.
gchar *`urn`; | The parent URN, or `NULL` if it doesn't exist.

### enum GnomeVFSURIHideOptions

    typedef enum
    {
    	GNOME_VFS_URI_HIDE_NONE = 0,
    	GNOME_VFS_URI_HIDE_USER_NAME = 1 << 0,
    	GNOME_VFS_URI_HIDE_PASSWORD = 1 << 1,
    	GNOME_VFS_URI_HIDE_HOST_NAME = 1 << 2,
    	GNOME_VFS_URI_HIDE_HOST_PORT = 1 << 3,
    	GNOME_VFS_URI_HIDE_TOPLEVEL_METHOD = 1 << 4,
    	GNOME_VFS_URI_HIDE_FRAGMENT_IDENTIFIER = 1 << 8
    } GnomeVFSURIHideOptions;

Packed boolean bitfield controlling hiding of various elements of a GnomeVFSURI when it is converted to a string using `gnome_vfs_uri_to_string()`.

`GNOME_VFS_URI_HIDE_NONE` | don't hide anything
`GNOME_VFS_URI_HIDE_USER_NAME` | hide the user name
`GNOME_VFS_URI_HIDE_PASSWORD` | hide the password
`GNOME_VFS_URI_HIDE_HOST_NAME` | hide the host name
`GNOME_VFS_URI_HIDE_HOST_PORT` | hide the port
`GNOME_VFS_URI_HIDE_TOPLEVEL_METHOD` | hide the method (e.g. http, file)
`GNOME_VFS_URI_HIDE_FRAGMENT_IDENTIFIER` | hide the fragment identifier

### GNOME_VFS_URI_MAGIC_CHR

    #define GNOME_VFS_URI_MAGIC_CHR '#'

The character used to divide location from extra "arguments" passed to the method.

### GNOME_VFS_URI_MAGIC_STR

    #define GNOME_VFS_URI_MAGIC_STR "#"

The character used to divide location from extra "arguments" passed to the method.

### GNOME_VFS_URI_PATH_CHR

    #define GNOME_VFS_URI_PATH_CHR '/'

Defines the path seperator character.

### GNOME_VFS_URI_PATH_STR

    #define GNOME_VFS_URI_PATH_STR "/"

Defines the path seperator string.

### gnome_vfs_uri_new ()

    GnomeVFSURI *       gnome_vfs_uri_new                   (const gchar *text_uri);

Create a new uri from `text_uri`. Unsupported and unsafe methods are not allowed and will result in `NULL` being returned. URL transforms are allowed.

The `a` text_uri must be an escaped URI string such as returned by `gnome_vfs_get_uri_from_local_path()`, `gnome_vfs_make_uri_from_input()`, or `gtk_file_chooser_get_uri()`.

`text_uri` : | an escaped string representing a uri.
Returns : | The new uri.

### gnome_vfs_uri_resolve_relative ()

    GnomeVFSURI *       gnome_vfs_uri_resolve_relative      (const GnomeVFSURI *base,
                                                             const gchar *relative_reference);

Create a new uri from `relative_reference`, relative to `base`. The resolution algorithm in some aspects follows RFC 2396, section 5.2, but is not identical due to some extra assumptions GnomeVFS makes about URIs.

If `relative_reference` begins with a valid scheme identifier followed by ':', it is assumed to refer to an absolute URI, and a GnomeVFSURI is created from it using `gnome_vfs_uri_new()`.

Otherwise, depending on its precise syntax, it inherits some aspects of the parent URI, but the parents' fragment and query components are ignored.

If `relative_reference` begins with "//", it only inherits the `base` scheme, if it begins with '/' (i.e. is an absolute path reference), it inherits everything ecxept the `base` path. Otherwise, it replaces the part of `base` after the last '/'.

### Note

This function should not be used by application authors unless they expect very distinct semantics. Instead, authors should use `gnome_vfs_uri_append_file_name()`, `gnome_vfs_uri_append_path()`, `gnome_vfs_uri_append_string()` or `gnome_vfs_uri_resolve_symbolic_link()`.

`base` : | base uri.
`relative_reference` : | a string representing a possibly relative uri reference.
Returns : | A GnomeVFSURI referring to `relative_reference`, or `NULL` if `relative_reference` was malformed.

### gnome_vfs_uri_resolve_symbolic_link ()

    GnomeVFSURI *       gnome_vfs_uri_resolve_symbolic_link (const GnomeVFSURI *base,
                                                             const gchar *relative_reference);

Create a new uri from `symbolic_link`, relative to `base`.

If `symbolic_link` begins with a '/', it replaces the path of `base`, otherwise it is appended after the last '/' character of `base`.

`base` : | base uri.
`relative_reference` : |
Returns : | A new GnomeVFSURI referring to `symbolic_link`.

Since 2.16

### gnome_vfs_uri_ref ()

    GnomeVFSURI *       gnome_vfs_uri_ref                   (GnomeVFSURI *uri);

Increment `uri`'s reference count.

`uri` : | a GnomeVFSURI.
Returns : | `uri`.

### gnome_vfs_uri_unref ()

    void                gnome_vfs_uri_unref                 (GnomeVFSURI *uri);

Decrement `uri`'s reference count. If the reference count reaches zero, `uri` is destroyed.

`uri` : | a GnomeVFSURI.

### gnome_vfs_uri_append_string ()

    GnomeVFSURI *       gnome_vfs_uri_append_string         (const GnomeVFSURI *uri,
                                                             const char *uri_fragment);

Create a new uri obtained by appending `uri_fragment` to `uri`. This will take care of adding an appropriate directory separator between the end of `uri` and the start of `uri_fragment` if necessary.

`uri` : | a GnomeVFSURI.
`uri_fragment` : | a piece of a uri (ie a fully escaped partial path).
Returns : | The new uri obtained by combining `uri` and `uri_fragment`.

### gnome_vfs_uri_append_path ()

    GnomeVFSURI *       gnome_vfs_uri_append_path           (const GnomeVFSURI *uri,
                                                             const char *path);

Create a new uri obtained by appending `path` to `uri`. This will take care of adding an appropriate directory separator between the end of `uri` and the start of `path` if necessary as well as escaping `path` as necessary.

`uri` : | a GnomeVFSURI.
`path` : | a non-escaped file path.
Returns : | The new uri obtained by combining `uri` and `path`.

### gnome_vfs_uri_append_file_name ()

    GnomeVFSURI *       gnome_vfs_uri_append_file_name      (const GnomeVFSURI *uri,
                                                             const gchar *filename);

Create a new uri obtained by appending `file_name` to `uri`. This will take care of adding an appropriate directory separator between the end of `uri` and the start of `file_name` if necessary. `file_name` might, for instance, be the result of a call to `g_dir_read_name()`.

`uri` : | a GnomeVFSURI.
`filename` : | any "regular" file name (can include #, /, etc) in the file system encoding. This is not an escaped URI.
Returns : | The new uri obtained by combining `uri` and `path`.

### gnome_vfs_uri_to_string ()

    gchar *             gnome_vfs_uri_to_string             (const GnomeVFSURI *uri,
                                                             GnomeVFSURIHideOptions hide_options);

Translate `uri` into a printable string. The string will not contain the uri elements specified by `hide_options`.

A file: URI on Win32 might look like file:///x:/foo/bar.txt. Note that the part after file:// is not a legal file name, you need to remove the / in front of the drive letter. This function does that automatically if `hide_options` specifies that the toplevel method, user name, password, host name and host port should be hidden.

On the other hand, a file: URI for a UNC path looks like file:////server/share/foo/bar.txt, and in that case the part after file:// is the correct file name.

`uri` : | a GnomeVFSURI.
`hide_options` : | bitmask specifying what uri elements (e.g. password, user name etc.) should not be represented in the returned string.
Returns : | a malloc'd printable string representing `uri`.

### gnome_vfs_uri_dup ()

    GnomeVFSURI *       gnome_vfs_uri_dup                   (const GnomeVFSURI *uri);

Duplicate `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to a new uri that is exactly the same as `uri`.

### gnome_vfs_uri_is_local ()

    gboolean            gnome_vfs_uri_is_local              (const GnomeVFSURI *uri);

Check if `uri` is a local URI. Note that the return value of this function entirely depends on the GnomeVFSMethod associated with the URI. It is up to the method author to distinguish between remote URIs add URIs referring to entities on the local computer.

Warning, this can be slow, as it does i/o to detect things like NFS mounts.

`uri` : | a GnomeVFSURI.
Returns : | `TRUE` if `uri` refers to a local entity, `FALSE` otherwise.

### gnome_vfs_uri_has_parent ()

    gboolean            gnome_vfs_uri_has_parent            (const GnomeVFSURI *uri);

Check if uri has a parent or not.

`uri` : | a GnomeVFSURI.
Returns : | `TRUE` if `uri` has a parent, `FALSE` otherwise.

### gnome_vfs_uri_get_parent ()

    GnomeVFSURI *       gnome_vfs_uri_get_parent            (const GnomeVFSURI *uri);

Retrieve `uri`'s parent uri.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to `uri`'s parent uri.

### gnome_vfs_uri_get_toplevel ()

    GnomeVFSToplevelURI * gnome_vfs_uri_get_toplevel        (const GnomeVFSURI *uri);

Retrieve the toplevel uri in `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to the toplevel uri object.

### gnome_vfs_uri_get_host_name ()

    const gchar *       gnome_vfs_uri_get_host_name         (const GnomeVFSURI *uri);

Retrieve the host name for `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a string representing the host name.

### gnome_vfs_uri_get_scheme ()

    const gchar *       gnome_vfs_uri_get_scheme            (const GnomeVFSURI *uri);

Retrieve the scheme used for `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a string representing the scheme.

### gnome_vfs_uri_get_host_port ()

    guint               gnome_vfs_uri_get_host_port         (const GnomeVFSURI *uri);

Retrieve the host port number in `uri`.

`uri` : | a GnomeVFSURI.
Returns : | The host port number used by `uri`. If the value is zero, the default port value for the specified toplevel access method is used.

### gnome_vfs_uri_get_user_name ()

    const gchar *       gnome_vfs_uri_get_user_name         (const GnomeVFSURI *uri);

Retrieve the user name in `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a string representing the user name in `uri`.

### gnome_vfs_uri_get_password ()

    const gchar *       gnome_vfs_uri_get_password          (const GnomeVFSURI *uri);

Retrieve the password for `uri`.

`uri` : | a GnomeVFSURI.
Returns : | The password for `uri`.

### gnome_vfs_uri_set_host_name ()

    void                gnome_vfs_uri_set_host_name         (GnomeVFSURI *uri,
                                                             const gchar *host_name);

Set `host_name` as the host name accessed by `uri`.

`uri` : | a GnomeVFSURI.
`host_name` : | a string representing a host name.

### gnome_vfs_uri_set_host_port ()

    void                gnome_vfs_uri_set_host_port         (GnomeVFSURI *uri,
                                                             guint host_port);

Set the host port number in `uri`. If `host_port` is zero, the default port for `uri`'s toplevel access method is used.

`uri` : | a GnomeVFSURI.
`host_port` : | a TCP/IP port number.

### gnome_vfs_uri_set_user_name ()

    void                gnome_vfs_uri_set_user_name         (GnomeVFSURI *uri,
                                                             const gchar *user_name);

Set `user_name` as the user name for `uri`.

`uri` : | a GnomeVFSURI.
`user_name` : | a string representing a user name on the host accessed by `uri`.

### gnome_vfs_uri_set_password ()

    void                gnome_vfs_uri_set_password          (GnomeVFSURI *uri,
                                                             const gchar *password);

Set `password` as the password for `uri`.

`uri` : | a GnomeVFSURI.
`password` : | a password string.

### gnome_vfs_uri_equal ()

    gboolean            gnome_vfs_uri_equal                 (const GnomeVFSURI *a,
                                                             const GnomeVFSURI *b);

Compare `a` and `b`.

FIXME: This comparison should take into account the possiblity that unreserved characters may be escaped. ...or perhaps `gnome_vfs_uri_new()` should unescape unreserved characters?

`a` : | a GnomeVFSURI.
`b` : | a GnomeVFSURI.
Returns : | `TRUE` if `a` and `b` are equal, `FALSE` otherwise.

### gnome_vfs_uri_is_parent ()

    gboolean            gnome_vfs_uri_is_parent             (const GnomeVFSURI *possible_parent,
                                                             const GnomeVFSURI *possible_child,
                                                             gboolean recursive);

Check if `possible_child` is contained by `possible_parent`. If `recursive` is `FALSE`, just try the immediate parent directory, else search up through the hierarchy.

`possible_parent` : | a GnomeVFSURI.
`possible_child` : | a GnomeVFSURI.
`recursive` : | a flag to turn recursive check on.
Returns : | `TRUE` if `possible_child` is contained in `possible_parent`.

### gnome_vfs_uri_get_path ()

    const gchar *       gnome_vfs_uri_get_path              (const GnomeVFSURI *uri);

Retrieve full path name for `uri`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to the full path name in `uri`. Notice that the pointer points to the path name stored in `uri`, so the path name returned must not be modified nor freed.

### gnome_vfs_uri_get_fragment_identifier ()

    const gchar *       gnome_vfs_uri_get_fragment_identifier
                                                            (const GnomeVFSURI *uri);

`uri` : |
Returns : |

### gnome_vfs_uri_extract_dirname ()

    gchar *             gnome_vfs_uri_extract_dirname       (const GnomeVFSURI *uri);

Extract the name of the directory in which the file pointed to by `uri` is stored as a newly allocated string. The string will end with a `GNOME_VFS_URI_PATH_CHR`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to the newly allocated string representing the parent directory.

### gnome_vfs_uri_extract_short_name ()

    gchar *             gnome_vfs_uri_extract_short_name    (const GnomeVFSURI *uri);

Retrieve base file name for `uri`, ignoring any trailing path separators. This matches the XPG definition of basename, but not g_basename. This is often useful when you want the name of something that's pointed to by a uri, and don't care whether the uri has a directory or file form. If `uri` points to the root of a domain, returns the host name. If there's no host name, returns `GNOME_VFS_URI_PATH_STR`.

See also: `gnome_vfs_uri_extract_short_path_name()`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to the newly allocated string representing the unescaped short form of the name.

### gnome_vfs_uri_extract_short_path_name ()

    gchar *             gnome_vfs_uri_extract_short_path_name
                                                            (const GnomeVFSURI *uri);

Retrieve base file name for `uri`, ignoring any trailing path separators. This matches the XPG definition of basename, but not g_basename. This is often useful when you want the name of something that's pointed to by a uri, and don't care whether the uri has a directory or file form. If `uri` points to the root (including the root of any domain), returns `GNOME_VFS_URI_PATH_STR`.

See also: `gnome_vfs_uri_extract_short_name()`.

`uri` : | a GnomeVFSURI.
Returns : | a pointer to the newly allocated string representing the escaped short form of the name.

### gnome_vfs_uri_hequal ()

    gint                gnome_vfs_uri_hequal                (gconstpointer a,
                                                             gconstpointer b);

Function intended for use as a hash table "are these two items the same" comparison. Useful for creating a hash table of uris.

`a` : | a pointer to a GnomeVFSURI.
`b` : | a pointer to a GnomeVFSURI.
Returns : | `TRUE` if the uris are the same.

### gnome_vfs_uri_hash ()

    guint               gnome_vfs_uri_hash                  (gconstpointer p);

Creates an integer value from a GnomeVFSURI, appropriate for using as the key to a hash table entry.

`p` : | a pointer to a GnomeVFSURI.
Returns : | a hash key corresponding to `p`.

### gnome_vfs_uri_list_parse ()

    GList *             gnome_vfs_uri_list_parse            (const gchar *uri_list);

Extracts a list of GnomeVFSURI objects from a standard text/uri-list, such as one you would get on a drop operation. Use `gnome_vfs_uri_list_free()` when you are done with the list.

`uri_list` : | string consists of GnomeVFSURIs and/or paths seperated by newline character.
Returns : | a GList of GnomeVFSURIs.

### gnome_vfs_uri_list_ref ()

    GList *             gnome_vfs_uri_list_ref              (GList *list);

Increments the reference count of the items in `list` by one.

`list` : | list of GnomeVFSURI elements.
Returns : | `list`.

### gnome_vfs_uri_list_unref ()

    GList *             gnome_vfs_uri_list_unref            (GList *list);

Decrements the reference count of the items in `list` by one. Note that the list is *not freed* even if each member of the list is freed.

`list` : | list of GnomeVFSURI elements.
Returns : | `list`.

### gnome_vfs_uri_list_copy ()

    GList *             gnome_vfs_uri_list_copy             (GList *list);

Creates a duplicate of `list`, and references each member of that list.

`list` : | list of GnomeVFSURI elements.
Returns : | a newly referenced duplicate of `list`.

### gnome_vfs_uri_list_free ()

    void                gnome_vfs_uri_list_free             (GList *list);

Decrements the reference count of each member of `list` by one, and frees the list itself.

`list` : | list of GnomeVFSURI elements.

### gnome_vfs_uri_make_full_from_relative ()

    char *              gnome_vfs_uri_make_full_from_relative
                                                            (const char *base_uri,
                                                             const char *relative_uri);

Returns a full uri given a full base uri, and a secondary uri which may be relative.

`base_uri` : | a string representing the base uri.
`relative_uri` : | a uri fragment/reference to be appended to `base_uri`.
Returns : | a newly allocated string containing the uri (`NULL` for some bad errors).