gnome-vfs-utils

## gnome-vfs-utils gnome-vfs-utils — various utilities functions to manipulate uris |

## Synopsis

    enum        GnomeVFSMakeURIDirs;
    char*       gnome_vfs_format_file_size_for_display
                                                (GnomeVFSFileSize size);
    char*       gnome_vfs_format_uri_for_display
                                                (const char *uri);
    GnomeVFSResult gnome_vfs_url_show           (const char *url);
    GnomeVFSResult gnome_vfs_url_show_with_env  (const char *url,
                                                 char **envp);
    char*       gnome_vfs_escape_string         (const char *string);
    char*       gnome_vfs_escape_path_string    (const char *path);
    char*       gnome_vfs_escape_host_and_path_string
                                                (const char *path);
    char*       gnome_vfs_escape_slashes        (const char *string);
    char*       gnome_vfs_escape_set            (const char *string,
                                                 const char *match_set);
    char*       gnome_vfs_unescape_string       (const char *escaped_string,
                                                 const char *illegal_characters);
    char*       gnome_vfs_make_uri_canonical    (const char *uri);
    char*       gnome_vfs_make_uri_canonical_strip_fragment
                                                (const char *uri);
    char*       gnome_vfs_make_path_name_canonical
                                                (const char *path);
    char*       gnome_vfs_make_uri_from_input   (const char *location);
    char*       gnome_vfs_make_uri_from_input_with_dirs
                                                (const char *location,
                                                 GnomeVFSMakeURIDirs dirs);
    char*       gnome_vfs_make_uri_from_shell_arg
                                                (const char *uri);
    char*       gnome_vfs_make_uri_full_from_relative
                                                (const char *base_uri,
                                                 const char *relative_uri);
    char*       gnome_vfs_expand_initial_tilde  (const char *path);
    char*       gnome_vfs_unescape_string_for_display
                                                (const char *escaped);
    char*       gnome_vfs_get_local_path_from_uri
                                                (const char *uri);
    char*       gnome_vfs_get_uri_from_local_path
                                                (const char *local_full_path);
    gboolean    gnome_vfs_is_executable_command_string
                                                (const char *command_string);
    void        gnome_vfs_list_deep_free        (GList *list);
    GnomeVFSResult gnome_vfs_get_volume_free_space
                                                (const GnomeVFSURI *vfs_uri,
                                                 GnomeVFSFileSize *size);
    char*       gnome_vfs_icon_path_from_filename
                                                (const char *filename);
    gboolean    gnome_vfs_is_primary_thread     (void);
    char*       gnome_vfs_get_uri_scheme        (const char *uri);
    gboolean    gnome_vfs_uris_match            (const char *uri_1,
                                                 const char *uri_2);
    #define     GNOME_VFS_ASSERT_PRIMARY_THREAD
    #define     GNOME_VFS_ASSERT_SECONDARY_THREAD
    GnomeVFSResult gnome_vfs_read_entire_file   (const char *uri,
                                                 int *file_size,
                                                 char **file_contents);

## Description

## Details

### enum GnomeVFSMakeURIDirs

    typedef enum {
    	GNOME_VFS_MAKE_URI_DIR_NONE = 0,
    	GNOME_VFS_MAKE_URI_DIR_HOMEDIR = 1 << 0,
    	GNOME_VFS_MAKE_URI_DIR_CURRENT = 1 << 1
    } GnomeVFSMakeURIDirs;

Flags that can be passed to `gnome_vfs_make_uri_from_input_with_dirs()`. If the given input might be a relative path it checks for existence of the file in the directory specified by this flag. If both flags are passed the current directory is checked first.

`GNOME_VFS_MAKE_URI_DIR_NONE` | Don't check any directory
`GNOME_VFS_MAKE_URI_DIR_HOMEDIR` | Check the home directory
`GNOME_VFS_MAKE_URI_DIR_CURRENT` | Check the current direcotry

### gnome_vfs_format_file_size_for_display ()

    char*       gnome_vfs_format_file_size_for_display
                                                (GnomeVFSFileSize size);

Formats the file size passed in `bytes` in a way that is easy for the user to read. Gives the size in bytes, kilobytes, megabytes or gigabytes, choosing whatever is appropriate.

`size` : |
Returns : | a newly allocated string with the size ready to be shown.

### gnome_vfs_format_uri_for_display ()

    char*       gnome_vfs_format_uri_for_display
                                                (const char *uri);

Filter, modify, unescape and change URIs to make them appropriate to display to users. The conversion is done such that the roundtrip to UTF-8 is reversible.

Rules: file: URI's without fragments should appear as local paths file: URI's with fragments should appear as file: URI's All other URI's appear as expected

`uri`: a URI

`uri` : |
Returns : | a newly allocated UTF-8 string

Since 2.2

### gnome_vfs_url_show ()

    GnomeVFSResult gnome_vfs_url_show           (const char *url);

Launches the default application or component associated with the given url.

`url` : |
Returns : | GNOME_VFS_OK if the default action was launched, GNOME_VFS_ERROR_BAD_PARAMETERS for an invalid or non-existant url, GNOME_VFS_ERROR_NOT_SUPPORTED if no default action is associated with the URL. Also error codes from gnome_vfs_mime_action_launch and gnome_vfs_url_show_using_handler for other errors.

Since 2.4

### gnome_vfs_url_show_with_env ()

    GnomeVFSResult gnome_vfs_url_show_with_env  (const char *url,
                                                 char **envp);

Like gnome_vfs_url_show except that the default action will be launched with the given environment.

`url` : |
`envp` : |
Returns : | GNOME_VFS_OK if the default action was launched.

Since 2.4

### gnome_vfs_escape_string ()

    char*       gnome_vfs_escape_string         (const char *string);

Escapes `string`, replacing any and all special characters with equivalent escape sequences.

`string` : | string to be escaped
Returns : | a newly allocated string equivalent to `string` but with all special characters escaped

### gnome_vfs_escape_path_string ()

    char*       gnome_vfs_escape_path_string    (const char *path);

Escapes `path`, replacing only special characters that would not be found in paths (so '/', '&', '=', and '?' will not be escaped by this function).

`path` : | string to be escaped
Returns : | a newly allocated string equivalent to `path` but with non-path characters escaped

### gnome_vfs_escape_host_and_path_string ()

    char*       gnome_vfs_escape_host_and_path_string
                                                (const char *path);

Escapes `path`, replacing only special characters that would not be found in paths or host name (so '/', '&', '=', ':', '@' and '?' will not be escaped by this function).

`path` : | string to be escaped
Returns : | a newly allocated string equivalent to `path` but with non-path/host characters escaped

### gnome_vfs_escape_slashes ()

    char*       gnome_vfs_escape_slashes        (const char *string);

Escapes only '/' and '%' characters in `string`, replacing them with their escape sequence equivalents.

`string` : | string to be escaped
Returns : | a newly allocated string equivalent to `string`, but with no unescaped '/' or '%' characters

### gnome_vfs_escape_set ()

    char*       gnome_vfs_escape_set            (const char *string,
                                                 const char *match_set);

Escapes all characters in `string` which are listed in `match_set`.

`string` : | string to be escaped
`match_set` : | a string containing all characters to be escaped in `string`.
Returns : | a newly allocated and escaped string.

### gnome_vfs_unescape_string ()

    char*       gnome_vfs_unescape_string       (const char *escaped_string,
                                                 const char *illegal_characters);

Decodes escaped characters (i.e. PERCENTxx sequences) in `escaped_string`. Characters are encoded in PERCENTxy form, where xy is the ASCII hex code for character 16x+y.

`escaped_string` : | an escaped URI, path, or other string
`illegal_characters` : | a string containing a sequence of characters considered "illegal" to be escaped, '\0' is automatically in this list.
Returns : | a newly allocated string with the unescaped equivalents, or `NULL` if `escaped_string` contained an escaped encoding of one of the characters in `illegal_characters`.

### gnome_vfs_make_uri_canonical ()

    char*       gnome_vfs_make_uri_canonical    (const char *uri);

Standarizes the format of the uri being passed, so that it can be used later in other functions that expect a canonical URI.

`uri` : | and absolute or relative URI, it might have scheme.
Returns : | a newly allocated string that contains the canonical representation of `uri`.

Since 2.2

### gnome_vfs_make_uri_canonical_strip_fragment ()

    char*       gnome_vfs_make_uri_canonical_strip_fragment
                                                (const char *uri);

If the `uri` passed contains a fragment (anything after a '#') strips if, then makes the URI canonical.

`uri` : |
Returns : | a newly allocated string containing a canonical URI.

Since 2.2

### gnome_vfs_make_path_name_canonical ()

    char*       gnome_vfs_make_path_name_canonical
                                                (const char *path);

Calls _gnome_vfs_canonicalize_pathname, allocating storage for the result and providing for a cleaner memory management.

`path` : | a file path, relative or absolute
Returns : | a canonical version of `path`

### gnome_vfs_make_uri_from_input ()

    char*       gnome_vfs_make_uri_from_input   (const char *location);

Takes a user input path/URI and makes a valid URI out of it.

This function is the reverse of gnome_vfs_format_uri_for_display but it also handles the fact that the user could have typed arbitrary UTF8 in the entry showing the string.

`location` : | a possibly mangled "uri", in UTF8
Returns : | a newly allocated uri.

Since 2.2

### gnome_vfs_make_uri_from_input_with_dirs ()

    char*       gnome_vfs_make_uri_from_input_with_dirs
                                                (const char *location,
                                                 GnomeVFSMakeURIDirs dirs);

Determines a fully qualified URL from a relative or absolute input path. Basically calls gnome_vfs_make_uri_from_input except it specifically tries to support paths relative to the specified directories (can be homedir and/or current directory). See GnomeVFSMakeURIDirs for more information.

`location` : | a relative or absolute path
`dirs` : | directory to use as a base directory if `location` is a relative path.
Returns : | a newly allocated string containing the fully qualified URL

Since 2.4

### gnome_vfs_make_uri_from_shell_arg ()

    char*       gnome_vfs_make_uri_from_shell_arg
                                                (const char *uri);

Similar to gnome_vfs_make_uri_from_input, except that:

1) guesses relative paths instead of http domains 2) doesn't bother stripping leading/trailing white space 3) doesn't bother with ~ expansion--that's done by the shell

`uri` : | a possibly mangled "uri"
Returns : | a newly allocated uri

Since 2.2

### gnome_vfs_make_uri_full_from_relative ()

    char*       gnome_vfs_make_uri_full_from_relative
                                                (const char *base_uri,
                                                 const char *relative_uri);

### Warning

`gnome_vfs_make_uri_full_from_relative` is deprecated and should not be used in newly-written code.

Returns a full URI given a full base URI, and a secondary URI which may be relative.

This function is deprecated, please use gnome_vfs_uri_make_full_from_relative from gnome-vfs-uri.h

`base_uri` : | uri to use as the base for the full uri
`relative_uri` : | full or relative path to append to the base uri
Returns : | the URI (NULL for some bad errors).

Since 2.2

### gnome_vfs_expand_initial_tilde ()

    char*       gnome_vfs_expand_initial_tilde  (const char *path);

If `path` starts with a ~, representing the user's home directory, expand it to the actual path location.

`path` : | a local file path which may start with a '~'
Returns : | a newly allocated string with the initial tilde (if there was one) converted to an actual path

### gnome_vfs_unescape_string_for_display ()

    char*       gnome_vfs_unescape_string_for_display
                                                (const char *escaped);

Similar to gnome_vfs_unescape_string, but it returns something semi-intelligable to a user even upon receiving traumatic input such as `00` or URIs in bad form.

See also: gnome_vfs_unescape_string.

`escaped` : | The string encoded with escaped sequences
Returns : | A pointer to a g_malloc'd string with all characters replacing their escaped hex values WARNING: You should never use this function on a whole URI! It unescapes reserved characters, and can result in a mangled URI that can not be re-entered. For example, it unescapes "#" "&" and "?", which have special meanings in URI strings.

### gnome_vfs_get_local_path_from_uri ()

    char*       gnome_vfs_get_local_path_from_uri
                                                (const char *uri);

Create a local path for a file:/// URI. Do not use with URIs of other methods.

`uri` : | URI to convert to a local path
Returns : | a newly allocated string containing the local path NULL is returned on error or if the uri isn't a file: URI without a fragment identifier (or chained URI).

### gnome_vfs_get_uri_from_local_path ()

    char*       gnome_vfs_get_uri_from_local_path
                                                (const char *local_full_path);

Returns a file:/// URI for the local path `local_full_path`.

`local_full_path` : | a full local filesystem path (i.e. not relative). On Windows this should be in the UTF-8 encoding, and can start with a drive letter, but doesn't have to.
Returns : | a newly allocated string containing the URI corresponding to `local_full_path` (NULL for some bad errors).

### gnome_vfs_is_executable_command_string ()

    gboolean    gnome_vfs_is_executable_command_string
                                                (const char *command_string);

Checks if `command_string` starts with the full path of an executable file or an executable in $PATH.

`command_string` : |
Returns : | TRUE if command_string started with and executable file, FALSE otherwise.

### gnome_vfs_list_deep_free ()

    void        gnome_vfs_list_deep_free        (GList *list);

Free `list`, and call `g_free()` on all data members.

`list` : | list to be freed

### gnome_vfs_get_volume_free_space ()

    GnomeVFSResult gnome_vfs_get_volume_free_space
                                                (const GnomeVFSURI *vfs_uri,
                                                 GnomeVFSFileSize *size);

Stores the amount of free space in bytes on `vfs`-uri's volume in `size`.

`vfs_uri` : |
`size` : |
Returns : | GNOME_VFS_OK on success, otherwise an GNOME_VFS_ERROR_* code

### gnome_vfs_icon_path_from_filename ()

    char*       gnome_vfs_icon_path_from_filename
                                                (const char *filename);

`filename` : |
Returns : |

### gnome_vfs_is_primary_thread ()

    gboolean    gnome_vfs_is_primary_thread     (void);

Check if the current thread is the thread with the main glib event loop.

Returns : | `TRUE` if the current thread is the thread with the main glib event loop

### gnome_vfs_get_uri_scheme ()

    char*       gnome_vfs_get_uri_scheme        (const char *uri);

Retrieve the scheme used in `uri`

`uri` : | a stringified URI
Returns : | A newly allocated string containing the scheme, NULL if `uri` it doesn't seem to contain a scheme

Since 2.2

### gnome_vfs_uris_match ()

    gboolean    gnome_vfs_uris_match            (const char *uri_1,
                                                 const char *uri_2);

Compare two URIs.

`uri_1` : | stringified URI to compare with `uri_2`.
`uri_2` : | stringified URI to compare with `uri_1`.
Returns : | TRUE if they are the same, FALSE otherwise.

Since 2.2

### GNOME_VFS_ASSERT_PRIMARY_THREAD

    #define GNOME_VFS_ASSERT_PRIMARY_THREAD g_assert (gnome_vfs_is_primary_thread())

Asserts that the current thread is the thread with the main glib event loop

### GNOME_VFS_ASSERT_SECONDARY_THREAD

    #define GNOME_VFS_ASSERT_SECONDARY_THREAD g_assert (!gnome_vfs_is_primary_thread())

Asserts that the current thread is NOT the thread with the main glib event loop

### gnome_vfs_read_entire_file ()

    GnomeVFSResult gnome_vfs_read_entire_file   (const char *uri,
                                                 int *file_size,
                                                 char **file_contents);

Reads an entire file into memory for convenience. Beware accidentally loading large files into memory with this function.

Since version 2.10 the string stored in `file_contents` will be nul-terminated, so for text files you can use result as a normal string.

`uri` : | URI of the file to read
`file_size` : | after reading the file, contains the size of the file read
`file_contents` : | contains the file_size bytes, the contents of the file at `uri`.
Returns : | An integer representing the result of the operation

Since 2.2