Next: , Previous: GnomeVFSResult, Up: Top


3 GnomeVFSURI

A uniform resource identifier.

3.1 Overview

A <gnome-vfsuri> 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.

3.2 Usage

— Class: <gnome-vfsuri>

Opaque pointer.

This class defines no direct slots.

— Function: gnome-vfs-uri-new (text_uri mchars) ⇒  (ret <gnome-vfsuri>)

Create a new uri from text-uri. Unsupported and unsafe methods are not allowed and will result in ‘#f’ 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.
ret
The new uri.
— Function: gnome-vfs-uri-resolve-relative (self <gnome-vfsuri>) (relative_reference mchars) ⇒  (ret <gnome-vfsuri>)

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 <gnome-vfsuri> 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 '/'.

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.
ret
A <gnome-vfsuri> referring to relative-reference, or ‘#f’ if relative-reference was malformed.
— Function: gnome-vfs-uri-resolve-symbolic-link (self <gnome-vfsuri>) (relative_reference mchars) ⇒  (ret <gnome-vfsuri>)

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

ret
A new <gnome-vfsuri> referring to symbolic-link.

Since 2.16

— Function: gnome-vfs-uri-append-string (self <gnome-vfsuri>) (uri_fragment mchars) ⇒  (ret <gnome-vfsuri>)

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 <gnome-vfsuri>.
uri-fragment
a piece of a uri (ie a fully escaped partial path).
ret
The new uri obtained by combining uri and uri-fragment.
— Function: gnome-vfs-uri-append-path (self <gnome-vfsuri>) (path mchars) ⇒  (ret <gnome-vfsuri>)

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 <gnome-vfsuri>.
path
a non-escaped file path.
ret
The new uri obtained by combining uri and path.
— Function: gnome-vfs-uri-append-file-name (self <gnome-vfsuri>) (filename mchars) ⇒  (ret <gnome-vfsuri>)

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 <gnome-vfsuri>.
filename
any "regular" file name (can include #, /, etc) in the file system encoding. This is not an escaped URI.
ret
The new uri obtained by combining uri and path.
— Function: gnome-vfs-uri-to-string (self <gnome-vfsuri>) (hide_options <gnome-vfsuri-hide-options>) ⇒  (ret mchars)

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 <gnome-vfsuri>.
hide-options
bitmask specifying what uri elements (e.g. password, user name etc.) should not be represented in the returned string.
ret
a malloc'd printable string representing uri.
— Function: gnome-vfs-uri-dup (self <gnome-vfsuri>) ⇒  (ret <gnome-vfsuri>)

Duplicate uri.

uri
a <gnome-vfsuri>.
ret
a pointer to a new uri that is exactly the same as uri.
— Function: gnome-vfs-uri-is-local (self <gnome-vfsuri>) ⇒  (ret bool)

Check if uri is a local URI. Note that the return value of this function entirely depends on the <gnome-vfs-method> 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 <gnome-vfsuri>.
ret
#t’ if uri refers to a local entity, ‘#f’ otherwise.
— Function: gnome-vfs-uri-has-parent (self <gnome-vfsuri>) ⇒  (ret bool)

Check if uri has a parent or not.

uri
a <gnome-vfsuri>.
ret
#t’ if uri has a parent, ‘#f’ otherwise.
— Function: gnome-vfs-uri-get-parent (self <gnome-vfsuri>) ⇒  (ret <gnome-vfsuri>)

Retrieve uri's parent uri.

uri
a <gnome-vfsuri>.
ret
a pointer to uri's parent uri.
— Function: gnome-vfs-uri-get-host-name (self <gnome-vfsuri>) ⇒  (ret mchars)

Retrieve the host name for uri.

uri
a <gnome-vfsuri>.
ret
a string representing the host name.
— Function: gnome-vfs-uri-get-scheme (self <gnome-vfsuri>) ⇒  (ret mchars)

Retrieve the scheme used for uri.

uri
a <gnome-vfsuri>.
ret
a string representing the scheme.
— Function: gnome-vfs-uri-get-host-port (self <gnome-vfsuri>) ⇒  (ret unsigned-int)

Retrieve the host port number in uri.

uri
a <gnome-vfsuri>.
ret
The host port number used by uri. If the value is zero, the default port value for the specified toplevel access method is used.
— Function: gnome-vfs-uri-get-user-name (self <gnome-vfsuri>) ⇒  (ret mchars)

Retrieve the user name in uri.

uri
a <gnome-vfsuri>.
ret
a string representing the user name in uri.
— Function: gnome-vfs-uri-get-password (self <gnome-vfsuri>) ⇒  (ret mchars)

Retrieve the password for uri.

uri
a <gnome-vfsuri>.
ret
The password for uri.
— Function: gnome-vfs-uri-set-host-name (self <gnome-vfsuri>) (host_name mchars)

Set host-name as the host name accessed by uri.

uri
a <gnome-vfsuri>.
host-name
a string representing a host name.
— Function: gnome-vfs-uri-set-host-port (self <gnome-vfsuri>) (host_port unsigned-int)

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 <gnome-vfsuri>.
host-port
a TCP/IP port number.
— Function: gnome-vfs-uri-set-user-name (self <gnome-vfsuri>) (user_name mchars)

Set user-name as the user name for uri.

uri
a <gnome-vfsuri>.
user-name
a string representing a user name on the host accessed by uri.
— Function: gnome-vfs-uri-set-password (self <gnome-vfsuri>) (password mchars)

Set password as the password for uri.

uri
a <gnome-vfsuri>.
password
a password string.
— Function: gnome-vfs-uri-equal (self <gnome-vfsuri>) (<gnome-vfsuri>) ⇒  (ret bool)

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 <gnome-vfsuri>.
b
a <gnome-vfsuri>.
ret
#t’ if a and b are equal, ‘#f’ otherwise.
— Function: gnome-vfs-uri-is-parent (self <gnome-vfsuri>) (possible_child <gnome-vfsuri>) (recursive bool) ⇒  (ret bool)

Check if possible-child is contained by possible-parent. If recursive is ‘#f’, just try the immediate parent directory, else search up through the hierarchy.

possible-parent
a <gnome-vfsuri>.
possible-child
a <gnome-vfsuri>.
recursive
a flag to turn recursive check on.
ret
#t’ if possible-child is contained in possible-parent.
— Function: gnome-vfs-uri-get-path (self <gnome-vfsuri>) ⇒  (ret mchars)

Retrieve full path name for uri.

uri
a <gnome-vfsuri>.
ret
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.
— Function: gnome-vfs-uri-extract-dirname (self <gnome-vfsuri>) ⇒  (ret mchars)

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 <gnome-vfsuri>.
ret
a pointer to the newly allocated string representing the parent directory.
— Function: gnome-vfs-uri-extract-short-name (self <gnome-vfsuri>) ⇒  (ret mchars)

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 <gnome-vfsuri>.
ret
a pointer to the newly allocated string representing the unescaped short form of the name.
— Function: gnome-vfs-uri-list-parse (uri_list mchars) ⇒  (ret glist-of)

Extracts a list of <gnome-vfsuri> 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 <gnome-vfsur-is> and/or paths seperated by newline character.
ret
a <g-list> of <gnome-vfsur-is>.