![]() |
![]() |
![]() |
GnomeVFS - Filesystem Abstraction library | ![]() |
---|
GnomeVFSURIGnomeVFSURI — Functions for manipulating URIs |
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_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);
typedef struct { /* Reference count. */ guint ref_count; /* Text for the element: eg. some/path/name. */ gchar *text; /* Text for uri fragment: eg, #anchor */ gchar *fragment_id; /* Method string: eg. `gzip', `tar', `http'. This is necessary as one GnomeVFSMethod can be used for different method strings (e.g. extfs handles zip, rar, zoo and several other ones). */ gchar *method_string; /* VFS method to access the element. */ struct GnomeVFSMethod *method; /* Pointer to the parent element, or NULL for toplevel elements. */ struct GnomeVFSURI *parent; /* Reserved to avoid future breaks in ABI compatibility */ void *reserved1; void *reserved2; } GnomeVFSURI;
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;
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 |
#define GNOME_VFS_URI_MAGIC_CHR '#'
The character used to divide location from extra "arguments" passed to the method.
#define GNOME_VFS_URI_MAGIC_STR "#"
The character used to divide location from extra "arguments" passed to the method.
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. |
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 : |
base uri. |
relative_reference : |
a string representing a possibly relative uri reference. |
Returns : | The new uri. |
GnomeVFSURI* gnome_vfs_uri_ref (GnomeVFSURI *uri);
Increment uri
's reference count.
uri : |
a GnomeVFSURI. |
Returns : | uri .
|
void gnome_vfs_uri_unref (GnomeVFSURI *uri);
Decrement uri
's reference count. If the reference count reaches zero,
uri
is destroyed.
uri : |
a GnomeVFSURI. |
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 .
|
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 .
|
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 .
|
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 .
|
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 .
|
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.
|
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.
|
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.
|
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. |
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. |
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. |
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.
|
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 .
|
const gchar* gnome_vfs_uri_get_password (const GnomeVFSURI *uri);
Retrieve the password for uri
.
uri : |
a GnomeVFSURI. |
Returns : | The password for uri .
|
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. |
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. |
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 .
|
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. |
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.
|
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 .
|
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.
|
const gchar* gnome_vfs_uri_get_fragment_identifier (const GnomeVFSURI *uri);
uri : |
|
Returns : |
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. |
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. |
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. |
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.
|
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 .
|
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. |
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 .
|
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 .
|
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 .
|
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. |
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).
|
<< GnomeVFSResult | gnome-vfs-utils >> |