MateVFSURI

MateVFSURI — A uniform resource identifier.

Synopsis

                    MateVFSURI;
                    MateVFSToplevelURI;
enum                MateVFSURIHideOptions;
#define             MATE_VFS_URI_MAGIC_CHR
#define             MATE_VFS_URI_MAGIC_STR
#define             MATE_VFS_URI_PATH_CHR
#define             MATE_VFS_URI_PATH_STR
MateVFSURI *        mate_vfs_uri_new                    (const gchar *text_uri);
MateVFSURI *        mate_vfs_uri_resolve_relative       (const MateVFSURI *base,
                                                         const gchar *relative_reference);
MateVFSURI *        mate_vfs_uri_resolve_symbolic_link  (const MateVFSURI *base,
                                                         const gchar *relative_reference);
MateVFSURI *        mate_vfs_uri_ref                    (MateVFSURI *uri);
void                mate_vfs_uri_unref                  (MateVFSURI *uri);
MateVFSURI *        mate_vfs_uri_append_string          (const MateVFSURI *uri,
                                                         const char *uri_fragment);
MateVFSURI *        mate_vfs_uri_append_path            (const MateVFSURI *uri,
                                                         const char *path);
MateVFSURI *        mate_vfs_uri_append_file_name       (const MateVFSURI *uri,
                                                         const gchar *filename);
gchar *             mate_vfs_uri_to_string              (const MateVFSURI *uri,
                                                         MateVFSURIHideOptions hide_options);
MateVFSURI *        mate_vfs_uri_dup                    (const MateVFSURI *uri);
gboolean            mate_vfs_uri_is_local               (const MateVFSURI *uri);
gboolean            mate_vfs_uri_has_parent             (const MateVFSURI *uri);
MateVFSURI *        mate_vfs_uri_get_parent             (const MateVFSURI *uri);
MateVFSToplevelURI * mate_vfs_uri_get_toplevel          (const MateVFSURI *uri);
const gchar *       mate_vfs_uri_get_host_name          (const MateVFSURI *uri);
const gchar *       mate_vfs_uri_get_scheme             (const MateVFSURI *uri);
guint               mate_vfs_uri_get_host_port          (const MateVFSURI *uri);
const gchar *       mate_vfs_uri_get_user_name          (const MateVFSURI *uri);
const gchar *       mate_vfs_uri_get_password           (const MateVFSURI *uri);
void                mate_vfs_uri_set_host_name          (MateVFSURI *uri,
                                                         const gchar *host_name);
void                mate_vfs_uri_set_host_port          (MateVFSURI *uri,
                                                         guint host_port);
void                mate_vfs_uri_set_user_name          (MateVFSURI *uri,
                                                         const gchar *user_name);
void                mate_vfs_uri_set_password           (MateVFSURI *uri,
                                                         const gchar *password);
gboolean            mate_vfs_uri_equal                  (const MateVFSURI *a,
                                                         const MateVFSURI *b);
gboolean            mate_vfs_uri_is_parent              (const MateVFSURI *possible_parent,
                                                         const MateVFSURI *possible_child,
                                                         gboolean recursive);
const gchar *       mate_vfs_uri_get_path               (const MateVFSURI *uri);
const gchar *       mate_vfs_uri_get_fragment_identifier
                                                        (const MateVFSURI *uri);
gchar *             mate_vfs_uri_extract_dirname        (const MateVFSURI *uri);
gchar *             mate_vfs_uri_extract_short_name     (const MateVFSURI *uri);
gchar *             mate_vfs_uri_extract_short_path_name
                                                        (const MateVFSURI *uri);
gint                mate_vfs_uri_hequal                 (gconstpointer a,
                                                         gconstpointer b);
guint               mate_vfs_uri_hash                   (gconstpointer p);
GList *             mate_vfs_uri_list_parse             (const gchar *uri_list);
GList *             mate_vfs_uri_list_ref               (GList *list);
GList *             mate_vfs_uri_list_unref             (GList *list);
GList *             mate_vfs_uri_list_copy              (GList *list);
void                mate_vfs_uri_list_free              (GList *list);
char *              mate_vfs_uri_make_full_from_relative
                                                        (const char *base_uri,
                                                         const char *relative_uri);

Description

A MateVFSURI 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

MateVFSURI

typedef struct {
	guint ref_count;

	gchar *text;
	gchar *fragment_id;

	gchar *method_string;
	struct MateVFSMethod *method;

	struct MateVFSURI *parent;
} MateVFSURI;

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 MateVFSMethod can be used for multiple method strings.

struct MateVFSMethod *method;

The MateVFSMethod associated with this resource.

struct MateVFSURI *parent;

Pointer to the parent element, or NULL for MateVFSURI that have no enclosing MateVFSURI. The process of encapsulating one URI in another one is called URI chaining.

MateVFSToplevelURI

typedef struct {
	MateVFSURI uri;

	gchar *host_name;
	guint host_port;

	gchar *user_name;
	gchar *password;

	gchar *urn;
} MateVFSToplevelURI;

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

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

MateVFSURI 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 MateVFSURIHideOptions

typedef enum {
	MATE_VFS_URI_HIDE_NONE = 0,
	MATE_VFS_URI_HIDE_USER_NAME = 1 << 0,
	MATE_VFS_URI_HIDE_PASSWORD = 1 << 1,
	MATE_VFS_URI_HIDE_HOST_NAME = 1 << 2,
	MATE_VFS_URI_HIDE_HOST_PORT = 1 << 3,
	MATE_VFS_URI_HIDE_TOPLEVEL_METHOD = 1 << 4,
	MATE_VFS_URI_HIDE_FRAGMENT_IDENTIFIER = 1 << 8
} MateVFSURIHideOptions;

Packed boolean bitfield controlling hiding of various elements of a MateVFSURI when it is converted to a string using mate_vfs_uri_to_string().

MATE_VFS_URI_HIDE_NONE

don't hide anything

MATE_VFS_URI_HIDE_USER_NAME

hide the user name

MATE_VFS_URI_HIDE_PASSWORD

hide the password

MATE_VFS_URI_HIDE_HOST_NAME

hide the host name

MATE_VFS_URI_HIDE_HOST_PORT

hide the port

MATE_VFS_URI_HIDE_TOPLEVEL_METHOD

hide the method (e.g. http, file)

MATE_VFS_URI_HIDE_FRAGMENT_IDENTIFIER

hide the fragment identifier

MATE_VFS_URI_MAGIC_CHR

#define MATE_VFS_URI_MAGIC_CHR '#'

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


MATE_VFS_URI_MAGIC_STR

#define MATE_VFS_URI_MAGIC_STR "#"

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


MATE_VFS_URI_PATH_CHR

#define MATE_VFS_URI_PATH_CHR '/'

Defines the path seperator character.


MATE_VFS_URI_PATH_STR

#define MATE_VFS_URI_PATH_STR "/"

Defines the path seperator string.


mate_vfs_uri_new ()

MateVFSURI *        mate_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 mate_vfs_get_uri_from_local_path(), mate_vfs_make_uri_from_input(), or gtk_file_chooser_get_uri().

text_uri :

an escaped string representing a uri.

Returns :

The new uri.

mate_vfs_uri_resolve_relative ()

MateVFSURI *        mate_vfs_uri_resolve_relative       (const MateVFSURI *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 MateVFS 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 MateVFSURI is created from it using mate_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 mate_vfs_uri_append_file_name(), mate_vfs_uri_append_path(), mate_vfs_uri_append_string() or mate_vfs_uri_resolve_symbolic_link().

base :

base uri.

relative_reference :

a string representing a possibly relative uri reference.

Returns :

A MateVFSURI referring to relative_reference, or NULL if relative_reference was malformed.

mate_vfs_uri_resolve_symbolic_link ()

MateVFSURI *        mate_vfs_uri_resolve_symbolic_link  (const MateVFSURI *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.

Returns :

A new MateVFSURI referring to symbolic_link.

Since 2.16


mate_vfs_uri_ref ()

MateVFSURI *        mate_vfs_uri_ref                    (MateVFSURI *uri);

Increment uri's reference count.

uri :

a MateVFSURI.

Returns :

uri.

mate_vfs_uri_unref ()

void                mate_vfs_uri_unref                  (MateVFSURI *uri);

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

uri :

a MateVFSURI.

mate_vfs_uri_append_string ()

MateVFSURI *        mate_vfs_uri_append_string          (const MateVFSURI *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 MateVFSURI.

uri_fragment :

a piece of a uri (ie a fully escaped partial path).

Returns :

The new uri obtained by combining uri and uri_fragment.

mate_vfs_uri_append_path ()

MateVFSURI *        mate_vfs_uri_append_path            (const MateVFSURI *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 MateVFSURI.

path :

a non-escaped file path.

Returns :

The new uri obtained by combining uri and path.

mate_vfs_uri_append_file_name ()

MateVFSURI *        mate_vfs_uri_append_file_name       (const MateVFSURI *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 MateVFSURI.

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.

mate_vfs_uri_to_string ()

gchar *             mate_vfs_uri_to_string              (const MateVFSURI *uri,
                                                         MateVFSURIHideOptions 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 MateVFSURI.

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.

mate_vfs_uri_dup ()

MateVFSURI *        mate_vfs_uri_dup                    (const MateVFSURI *uri);

Duplicate uri.

uri :

a MateVFSURI.

Returns :

a pointer to a new uri that is exactly the same as uri.

mate_vfs_uri_is_local ()

gboolean            mate_vfs_uri_is_local               (const MateVFSURI *uri);

Check if uri is a local URI. Note that the return value of this function entirely depends on the MateVFSMethod 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 MateVFSURI.

Returns :

TRUE if uri refers to a local entity, FALSE otherwise.

mate_vfs_uri_has_parent ()

gboolean            mate_vfs_uri_has_parent             (const MateVFSURI *uri);

Check if uri has a parent or not.

uri :

a MateVFSURI.

Returns :

TRUE if uri has a parent, FALSE otherwise.

mate_vfs_uri_get_parent ()

MateVFSURI *        mate_vfs_uri_get_parent             (const MateVFSURI *uri);

Retrieve uri's parent uri.

uri :

a MateVFSURI.

Returns :

a pointer to uri's parent uri.

mate_vfs_uri_get_toplevel ()

MateVFSToplevelURI * mate_vfs_uri_get_toplevel          (const MateVFSURI *uri);

Retrieve the toplevel uri in uri.

uri :

a MateVFSURI.

Returns :

a pointer to the toplevel uri object.

mate_vfs_uri_get_host_name ()

const gchar *       mate_vfs_uri_get_host_name          (const MateVFSURI *uri);

Retrieve the host name for uri.

uri :

a MateVFSURI.

Returns :

a string representing the host name.

mate_vfs_uri_get_scheme ()

const gchar *       mate_vfs_uri_get_scheme             (const MateVFSURI *uri);

Retrieve the scheme used for uri.

uri :

a MateVFSURI.

Returns :

a string representing the scheme.

mate_vfs_uri_get_host_port ()

guint               mate_vfs_uri_get_host_port          (const MateVFSURI *uri);

Retrieve the host port number in uri.

uri :

a MateVFSURI.

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.

mate_vfs_uri_get_user_name ()

const gchar *       mate_vfs_uri_get_user_name          (const MateVFSURI *uri);

Retrieve the user name in uri.

uri :

a MateVFSURI.

Returns :

a string representing the user name in uri.

mate_vfs_uri_get_password ()

const gchar *       mate_vfs_uri_get_password           (const MateVFSURI *uri);

Retrieve the password for uri.

uri :

a MateVFSURI.

Returns :

The password for uri.

mate_vfs_uri_set_host_name ()

void                mate_vfs_uri_set_host_name          (MateVFSURI *uri,
                                                         const gchar *host_name);

Set host_name as the host name accessed by uri.

uri :

a MateVFSURI.

host_name :

a string representing a host name.

mate_vfs_uri_set_host_port ()

void                mate_vfs_uri_set_host_port          (MateVFSURI *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 MateVFSURI.

host_port :

a TCP/IP port number.

mate_vfs_uri_set_user_name ()

void                mate_vfs_uri_set_user_name          (MateVFSURI *uri,
                                                         const gchar *user_name);

Set user_name as the user name for uri.

uri :

a MateVFSURI.

user_name :

a string representing a user name on the host accessed by uri.

mate_vfs_uri_set_password ()

void                mate_vfs_uri_set_password           (MateVFSURI *uri,
                                                         const gchar *password);

Set password as the password for uri.

uri :

a MateVFSURI.

password :

a password string.

mate_vfs_uri_equal ()

gboolean            mate_vfs_uri_equal                  (const MateVFSURI *a,
                                                         const MateVFSURI *b);

Compare a and b.

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

a :

a MateVFSURI.

b :

a MateVFSURI.

Returns :

TRUE if a and b are equal, FALSE otherwise.

mate_vfs_uri_is_parent ()

gboolean            mate_vfs_uri_is_parent              (const MateVFSURI *possible_parent,
                                                         const MateVFSURI *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 MateVFSURI.

possible_child :

a MateVFSURI.

recursive :

a flag to turn recursive check on.

Returns :

TRUE if possible_child is contained in possible_parent.

mate_vfs_uri_get_path ()

const gchar *       mate_vfs_uri_get_path               (const MateVFSURI *uri);

Retrieve full path name for uri.

uri :

a MateVFSURI.

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.

mate_vfs_uri_get_fragment_identifier ()

const gchar *       mate_vfs_uri_get_fragment_identifier
                                                        (const MateVFSURI *uri);


mate_vfs_uri_extract_dirname ()

gchar *             mate_vfs_uri_extract_dirname        (const MateVFSURI *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 MATE_VFS_URI_PATH_CHR.

uri :

a MateVFSURI.

Returns :

a pointer to the newly allocated string representing the parent directory.

mate_vfs_uri_extract_short_name ()

gchar *             mate_vfs_uri_extract_short_name     (const MateVFSURI *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 MATE_VFS_URI_PATH_STR.

See also: mate_vfs_uri_extract_short_path_name().

uri :

a MateVFSURI.

Returns :

a pointer to the newly allocated string representing the unescaped short form of the name.

mate_vfs_uri_extract_short_path_name ()

gchar *             mate_vfs_uri_extract_short_path_name
                                                        (const MateVFSURI *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 MATE_VFS_URI_PATH_STR.

See also: mate_vfs_uri_extract_short_name().

uri :

a MateVFSURI.

Returns :

a pointer to the newly allocated string representing the escaped short form of the name.

mate_vfs_uri_hequal ()

gint                mate_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 MateVFSURI.

b :

a pointer to a MateVFSURI.

Returns :

TRUE if the uris are the same.

mate_vfs_uri_hash ()

guint               mate_vfs_uri_hash                   (gconstpointer p);

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

p :

a pointer to a MateVFSURI.

Returns :

a hash key corresponding to p.

mate_vfs_uri_list_parse ()

GList *             mate_vfs_uri_list_parse             (const gchar *uri_list);

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

uri_list :

string consists of MateVFSURIs and/or paths seperated by newline character.

Returns :

a GList of MateVFSURIs.

mate_vfs_uri_list_ref ()

GList *             mate_vfs_uri_list_ref               (GList *list);

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

list :

list of MateVFSURI elements.

Returns :

list.

mate_vfs_uri_list_unref ()

GList *             mate_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 MateVFSURI elements.

Returns :

list.

mate_vfs_uri_list_copy ()

GList *             mate_vfs_uri_list_copy              (GList *list);

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

list :

list of MateVFSURI elements.

Returns :

a newly referenced duplicate of list.

mate_vfs_uri_list_free ()

void                mate_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 MateVFSURI elements.

mate_vfs_uri_make_full_from_relative ()

char *              mate_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).