manpagez: man pages & more
html files: gnome-vfs
Home | html | info | man

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_open_fd                   (GnomeVFSHandle **handle,
                                                         int filedes);
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 so that it is easy for the user to read. Gives the size in bytes, kilobytes, megabytes or gigabytes, choosing whatever is appropriate.

size :

a GnomeVFSFileSize (a guint64 value).

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 uri to make it appropriate for display to users. The conversion is done such that the roundtrip to UTF-8 is reversible.

Rules: file: uri without fragments should appear as local paths. file: uri with fragments should appear as file:uri. All other uri appear as expected.

uri :

uri to be displayed.

Returns :

a newly allocated string which represents uri and can be displayed.

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 :

url to be shown.

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_NO_DEFAULT if no default action is associated with the url. Also error codes from gnome_vfs_mime_action_launch() or gnome_vfs_mime_action_launch_with_env().

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 :

url to be shown.

envp :

environment data.

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_NO_DEFAULT if no default action is associated with the url. Also error codes from gnome_vfs_mime_application_launch_with_env() or gnome_vfs_mime_action_launch_with_env().

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 string equivalent to string but with characters in match_string escaped.

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);

Standardizes the format of the uri, so that it can be used later in other functions that expect a canonical uri.

uri :

an absolute or relative stringified 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);

Returns a canonicalized uri. If uri contains a fragment (anything after a '#') strips off that and then makes the uri canonical.

uri :

a GnomeVFSURI.

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 UTF-8 in the entry showing the string.

location :

a possibly mangled "uri", in UTF-8.

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 uri 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 uri.

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 :

path to make the uri from.

Returns :

a newly allocated string representing 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. This function is deprecated, please use gnome_vfs_uri_make_full_from_relative() from gnome-vfs-uri.h .

Returns a string representing the full uri given a full base_uri and a secondary uri which may be relative.

base_uri :

path to use as the base for the full uri.

relative_uri :

full or relative path to be appended to the base_uri.

Returns :

a newly allocated string containing 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().

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.

escaped :

a string encoded with escaped sequences.

Returns :

a pointer to a g_malloc'd string with all characters replacing their escaped hex values.

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, such as a path provided by gtk_file_chooser_get_filename(). The resulting URI may be provided, for instance, to gnome_vfs_uri_new().

On Windows local_full_path should be in the UTF-8 encoding, and can start with a drive letter, but doesn't have to.

local_full_path :

a full local filesystem path (i.e. not relative).

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 :

a string representing a command ie "xterm -bg white".

Returns :

TRUE if command_string started with an executable file, and is in $PATH, 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 :

a GnomeVFSURI.

size :

a GnomeVFSFileSize.

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 :

path to a file. Could be relative or absolute path.

Returns :

Returns the icon path for the filename. Example: gnome_vfs_icon_path_from_filename ("nautilus/nautilus-desktop.png") will return a string forming the full path of the file nautilus-desktop.png ie $PREFIX/share/pixmaps/nautilus/nautilus-desktop.png.

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 doesn't 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_open_fd ()

GnomeVFSResult      gnome_vfs_open_fd                   (GnomeVFSHandle **handle,
                                                         int filedes);

Converts an open unix file descript into a GnomeVFSHandle that can be used with the normal GnomeVFS file operations. When the handle is closed the file descriptor will also be closed.

handle :

A pointer to a pointer to a GnomeVFSHandle object

filedes :

a UNIX file descriptor

Returns :

GNOME_VFS_OK if the open was ok, a suitable error otherwise. Since 2.2

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 null-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

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.