GnomeVFSURI

## GnomeVFSURI GnomeVFSURI — Functions for manipulating URIs |

## Synopsis

                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_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

## Details

### GnomeVFSToplevelURI

    typedef struct {
    	/* Base object.  */
    	GnomeVFSURI uri;

    	/* Server location information.  */
    	gchar *host_name;
    	guint host_port;

    	/* Authorization information. (unescaped) */
    	gchar *user_name;
    	gchar *password;

    	/* The parent URN, if it exists */
    	gchar *urn;

    	/* Reserved to avoid future breaks in ABI compatibility */
    	void *reserved1;
    	void *reserved2;
    } GnomeVFSToplevelURI;

### 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.

`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.

`text_uri` : | A 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 follows RFC 2396. For details, see section 5.2 of http://www.ietf.org/rfc/rfc2396.txt .

In short, if the `base` URI ends in '/', `relative_reference` is appended to `base`, otherwise it replaces the part of `base` after the last '/'.

`base` : | The base URI.
`relative_reference` : | A string representing a possibly relative URI reference
Returns : | The new URI.

### 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 `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.

`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 `path`.

### 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.

`uri` : | A GnomeVFSURI.
`filename` : | any "regular" file name (can include #, /, etc)
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`.

`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 malloced 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 (native) file system.

`uri` : | A GnomeVFSURI.
Returns : | `FALSE` if `uri` is not a local file system, `TRUE` 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`.

`a` : | A GnomeVFSURI.
`b` : | A GnomeVFSURI.
Returns : | `TRUE` if `a` and `b` are equal, `FALSE` otherwise. 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?

### 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_child`.

### 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 name store in `uri`, so the 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` : |
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).