8.8 URI Structures


8.8 URI Structures

As described earlier, the GnomeVFS API has many functions that operate on GnomeVFSURI structures; some don't have corresponding functions that operate on URI strings. GnomeVFSURI structures contain hierarchical address information, and, therefore, you will find that they are much easier to manipulate than URI strings.

To create a URI structure from a URI string, call

 GnomeVFSURI *  uri  ; gchar *  uri_string  ;  uri  = gnome_vfs_uri_new(  uri_string  ); 

Other URI structure allocation- related functions include the following:

  • GnomeVFSURI *gnome_vfs_uri_ref(GnomeVFSURI * uri )

    Returns a new reference to uri .

  • void gnome_vfs_uri_unref(GnomeVFSURI * uri )

    Removes a reference to uri . When the reference count in uri goes to 0, this function deallocates uri .

  • GnomeVFSURI *gnome_vfs_uri_dup(GnomeVFSURI * uri )

    Returns a duplicate of uri .

  • gboolean gnome_vfs_uri_dup(GnomeVFSURI * uri1 , GnomeVFSURI * uri2 )

    Returns TRUE if uri1 and uri2 are the same.

8.8.1 Building URI Paths

Use these functions to create URI paths:

  • GnomeVFSURI *gnome_vfs_uri_append_string(GnomeVFSURI * uri , const gchar * str )

    Appends str to the end of URI , returning a new URI structure; inserts a new path separator if necessary.

  • GnomeVFSURI *gnome_vfs_uri_append_path(GnomeVFSURI * uri , const gchar * path )

    Appends path to the end of URI , returning a new URI structure; inserts a new path separator if necessary. This function translates any special characters in path .

  • GnomeVFSURI *gnome_vfs_uri_append_file_name(GnomeVFSURI * uri , const gchar * filename )

    Appends filename to the end of URI , returning a new URI structure; inserts a new path separator if necessary. This function translates any special characters in filename , including # and / .

Note  

The reason for separate functions for pathnames and filenames is that GnomeVFS cannot otherwise determine when it should translate path separators (# in particular) for strings, multiple paths, or filenames.

8.8.2 Extracting Path Information from a URI

These functions extract various pieces of the path:

  • gchar *gnome_vfs_uri_to_string(GnomeVFSURI * uri , GnomeVFSURIHideOptions hide_options )

    Returns a newly allocated string corresponding to uri ; hide_options is a bitwise OR of any of these constants:

    • GNOME_VFS_URI_HIDE_NONE

    • GNOME_VFS_URI_HIDE_TOPLEVEL_METHOD : Does not include the first access method in the URI (at the very start, before the colon ).

    • GNOME_VFS_URI_HIDE_HOST_NAME

    • GNOME_VFS_URI_HIDE_HOST_PORT

    • GNOME_VFS_URI_HIDE_USER_NAME

    • GNOME_VFS_URI_HIDE_PASSWORD

    • GNOME_VFS_URI_HIDE_FRAGMENT_IDENTIFIER : Hides any access method specified with # .

  • gboolean gnome_vfs_uri_exists(const GnomeVFSURI * uri )

    Returns TRUE if uri exists.

  • gboolean gnome_vfs_uri_is_local(const GnomeVFSURI * uri )

    Returns TRUE if uri is on a local file system.

  • gboolean gnome_vfs_uri_has_parent(const GnomeVFSURI * uri )

    Returns TRUE if uri has a parent URI (that is, if / does not appear in its namespace).

  • GnomeVFSURI *gnome_vfs_uri_get_parent(const GnomeVFSURI * uri )

    Returns the parent URI of uri .

  • gboolean gnome_vfs_uri_is_parent(const GnomeVFSURI * parent , const GnomeVFSURI * uri , gboolean recursive )

    Returns TRUE if parent is the parent of uri . If recursive is TRUE , this function recursively searches the directory hierarchy above uri .

  • const gchar *gnome_vfs_uri_get_path(const GnomeVFSURI * uri )

    Returns the full path of uri as a string. Do not deallocate or alter this string; it is a part of uri .

  • const gchar *gnome_vfs_uri_get_fragment_identifier(const GnomeVFSURI * uri )

    Returns a fragment identifier in uri (for example, #section ).

  • const gchar *gnome_vfs_uri_get_scheme(const GnomeVFSURI * uri )

    Returns an access scheme in uri (for example, gzip ).

  • gchar *gnome_vfs_uri_extract_dirname(const GnomeVFSURI * uri )

    Returns a newly allocated string containing the directory name in uri . The string terminates with a path separator.

  • gchar *gnome_vfs_uri_extract_short_name(const GnomeVFSURI * uri )

    Returns a newly allocated string containing the path filename in uri (with no access method). The result can be a local pathname, a filename with no path, a hostname, or a single path separator (for the root).

  • gchar *gnome_vfs_uri_extract_short_path_name(const GnomeVFSURI * uri )

    Same as the preceding function, but never returns a hostname; in that case, it returns a single path separator.

8.8.3 Accessing URI Connection Information

These functions extract parameters relevant to the connection used to access remote URIs:

  • const gchar *gnome_vfs_uri_get_host_name(const GnomeVFSURI * uri )

    Returns the hostname in uri . Do not deallocate or alter this string.

  • void gnome_vfs_uri_set_host_name(const GnomeVFSURI * uri , const gchar * hostname )

    Sets the hostname in uri to hostname .

  • guint gnome_vfs_uri_get_host_port(const GnomeVFSURI * uri )

    Returns the port in uri .

  • void gnome_vfs_uri_set_host_port(const GnomeVFSURI * uri , guint port )

    Sets the port uri to port .

  • const gchar *gnome_vfs_uri_get_user_name(const GnomeVFSURI * uri )

    Returns the username in uri .

  • void gnome_vfs_uri_set_user_name(const GnomeVFSURI * uri , const gchar * user_name )

    Sets the username in uri to user_name .

  • const gchar *gnome_vfs_uri_get_password(const GnomeVFSURI * uri )

    Returns the password in uri .

  • void gnome_vfs_uri_set_password(const GnomeVFSURI * uri , const gchar * password )

    Sets the password in uri to password .

8.8.4 URI Lists

There are several functions that manipulate lists of URIs:

  • GList *gnome_vfs_uri_list_ref(GList * uri_list )

    Increments the reference counts in every URI in uri_list ; returns the list pointer.

  • GList *gnome_vfs_uri_list_unref(GList * uri_list )

    Decrements the reference counts in every URI in uri_list ; returns the list.

  • GList *gnome_vfs_uri_list_copy(GList * uri_list )

    Completely copies uri_list and returns the copy.

  • GList *gnome_vfs_uri_list_free(GList * uri_list )

    Completely deallocates uri_list .




The Official GNOME 2 Developers Guide
The Official GNOME 2 Developers Guide
ISBN: 1593270305
EAN: 2147483647
Year: 2004
Pages: 108

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net