GnomeVFS - Filesystem Abstraction library | ||||
---|---|---|---|---|
Top | Description |
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);
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_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.
|
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 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 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 to be shown. |
|
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 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).
|
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).
|
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 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 to be escaped. |
|
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.
|
an escaped uri, path, or other string. |
|
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.
|
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.
|
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.
|
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.
|
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.
|
a relative or absolute path. |
|
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.
|
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.
|
path to use as the base for the full 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.
|
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.
|
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 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.
|
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.
|
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 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
.
|
a GnomeVFSURI. |
|
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);
|
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
.
|
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.
|
stringified uri to compare with 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.
|
A pointer to a pointer to a GnomeVFSHandle object |
|
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 of the file to read. |
|
after reading the file, contains the size of the file read. |
|
contains the file_size bytes, the contents of the file at uri .
|
Returns : |
an integer representing the result of the operation. |
Since 2.2