![]() |
![]() |
![]() |
GnomeVFS - Filesystem Abstraction library | ![]() |
---|
GnomeVFSURIGnomeVFSURI — Functions for manipulating URIs |
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 { /* 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
.
base : |
The 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 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 .
|
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
.
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 .
|
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
.
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?
|
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 .
|
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.
|
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 : |
|
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 >> |