rb-file-helpers

rb-file-helpers — An assortment of file and URI helper functions

Functions

Description

This is a variety of functions for dealing with files and URIs, including locating installed files, finding user cache and config directories, and dealing with file naming restrictions for various filesystems.

Functions

rb_file ()

const char *
rb_file (const char *filename);

Searches for an installed file, returning the full path name if found, NULL otherwise.

Parameters

filename

name of file to search for

 

Returns

Full file name, if found. Must not be freed.


rb_user_data_dir ()

const char *
rb_user_data_dir (void);

This will create the rhythmbox user data directory, using the XDG Base Directory specification. If none of the XDG environment variables are set, this will be ~/.local/share/rhythmbox.

Returns

string holding the path to the rhythmbox user data directory, or NULL if the directory does not exist and cannot be created.


rb_user_cache_dir ()

const char *
rb_user_cache_dir (void);

This will create the rhythmbox user cache directory, using the XDG Base Directory specification. If none of the XDG environment variables are set, this will be ~/.cache/rhythmbox.

Returns

string holding the path to the rhythmbox user cache directory, or NULL if the directory does not exist and could not be created.


rb_music_dir ()

const char *
rb_music_dir (void);

Returns the default directory for the user's music library. This will usually be the 'Music' directory under the home directory.

Returns

user's music directory. must not be freed.


rb_find_user_data_file ()

char *
rb_find_user_data_file (const char *name);

Determines the full path to use for user-specific files, such as rhythmdb.xml, within the user data directory (see rb_user_data_dir ).

Parameters

name

name of file to find

 

Returns

allocated string containing the location of the file to use, even if an error occurred.


rb_find_user_cache_file ()

char *
rb_find_user_cache_file (const char *name);

Determines the full path to use for user-specific cached files within the user cache directory.

Parameters

name

name of file to find

 

Returns

allocated string containing the location of the file to use, even if an error occurred.


rb_file_helpers_init ()

void
rb_file_helpers_init (void);

Sets up file search paths for rb_file . Must be called on startup.


rb_file_helpers_shutdown ()

void
rb_file_helpers_shutdown (void);

Frees various data allocated by file helper functions. Should be called on shutdown.


rb_uri_resolve_symlink ()

char *
rb_uri_resolve_symlink (const char *uri,
                        GError **error);

Attempts to resolve symlinks in uri and return a canonical URI for the file it identifies.

Parameters

uri

the URI to process

 

error

returns error information

 

Returns

resolved URI, or NULL on error


rb_uri_is_directory ()

gboolean
rb_uri_is_directory (const char *uri);

Checks if uri identifies a directory.

Parameters

uri

the URI to check

 

Returns

TRUE if uri is a directory


rb_uri_exists ()

gboolean
rb_uri_exists (const char *uri);

Checks if a URI identifies a resource that exists

Parameters

uri

a URI to check

 

Returns

TRUE if uri exists


rb_uri_is_readable ()

gboolean
rb_uri_is_readable (const char *uri);

Checks if the user can read the resource identified by uri

Parameters

uri

a URI to check

 

Returns

TRUE if uri is readable


rb_uri_is_writable ()

gboolean
rb_uri_is_writable (const char *uri);

Checks if the user can write to the resource identified by uri

Parameters

uri

a URI to check

 

Returns

TRUE if uri is writable


rb_uri_is_local ()

gboolean
rb_uri_is_local (const char *uri);

Checks if uri identifies a local resource. Currently this just checks that it uses the 'file' URI scheme.

Parameters

uri

a URI to check

 

Returns

TRUE if uri is local


rb_uri_is_hidden ()

gboolean
rb_uri_is_hidden (const char *uri);

Checks if uri is hidden, according to the Unix filename convention. If the filename component of uri begins with a dot, the file is considered hidden.

Parameters

uri

a URI to check

 

Returns

TRUE if uri is hidden


rb_uri_could_be_podcast ()

gboolean
rb_uri_could_be_podcast (const char *uri,
                         gboolean *is_opml);

Checks if uri identifies a resource that is probably a podcast (RSS or Atom feed). This does not perform any IO, it just guesses based on the URI itself.

Parameters

uri

a URI to check

 

is_opml

returns whether the URI identifies an OPML document

 

Returns

TRUE if uri may be a podcast


rb_uri_make_hidden ()

char *
rb_uri_make_hidden (const char *uri);

Constructs a URI that is similar to uri but which identifies a hidden file. This can be used for temporary files that should not be visible to the user while they are in use.

Parameters

uri

a URI to construct a hidden version of

 

Returns

hidden URI, must be freed by the caller.


rb_uri_handle_recursively ()

void
rb_uri_handle_recursively (const char *uri,
                           GCancellable *cancel,
                           RBUriRecurseFunc func,
                           gpointer user_data);

Calls func for each file found under the directory identified by uri . If uri identifies a file, calls func for that instead.

Parameters

uri

URI to visit

 

cancel

an optional GCancellable to allow cancellation

 

func

Callback function.

[scope call]

user_data

Data for callback function

 

rb_uri_handle_recursively_async ()

void
rb_uri_handle_recursively_async (const char *uri,
                                 GCancellable *cancel,
                                 RBUriRecurseFunc func,
                                 gpointer user_data,
                                 GDestroyNotify data_destroy);

Calls func for each file found under the directory identified by uri , or if uri identifies a file, calls it once with that.

If non-NULL, destroy_data will be called once all files have been processed, or when the operation is cancelled.

Parameters

uri

the URI to visit

 

cancel

a GCancellable to allow cancellation

 

func

callback function

 

user_data

data to pass to callback

 

data_destroy

function to call to free user_data

 

rb_uri_mkstemp ()

gboolean
rb_uri_mkstemp (const char *prefix,
                char **uri_ret,
                GOutputStream **stream,
                GError **error);

Creates a temporary file whose URI begins with prefix , returning the file URI and an output stream for writing to it.

Parameters

prefix

URI prefix

 

uri_ret

returns the temporary file URI

 

stream

returns a GOutputStream for the temporary file

 

error

returns error information

 

Returns

TRUE if successful


rb_canonicalise_uri ()

char *
rb_canonicalise_uri (const char *uri);

Converts uri to canonical URI form, ensuring it doesn't contain any redundant directory fragments or unnecessarily escaped characters. All URIs passed to RhythmDB functions should be canonicalised.

Parameters

uri

URI to canonicalise

 

Returns

canonical URI, must be freed by caller


rb_uri_append_path ()

char *
rb_uri_append_path (const char *uri,
                    const char *path);

Creates a new URI consisting of path appended to uri .

Parameters

uri

the URI to append to

 

path

the path fragment to append

 

Returns

new URI, must be freed by caller


rb_uri_append_uri ()

char *
rb_uri_append_uri (const char *uri,
                   const char *fragment);

Creates a new URI consisting of fragment appended to uri . Generally isn't a good idea.

Parameters

uri

the URI to append to

 

fragment

the URI fragment to append

 

Returns

new URI, must be freed by caller


rb_uri_get_dir_name ()

char *
rb_uri_get_dir_name (const char *uri);

Returns the directory component of uri , that is, everything up to the start of the filename.

Parameters

uri

a URI

 

Returns

new URI for parent of uri , must be freed by caller.


rb_uri_get_short_path_name ()

char *
rb_uri_get_short_path_name (const char *uri);

Returns the filename component of uri , that is, everything after the final slash and before the start of the query string or fragment.

Parameters

uri

a URI

 

Returns

filename component of uri , must be freed by caller


rb_check_dir_has_space ()

gboolean
rb_check_dir_has_space (GFile *dir,
                        guint64 bytes_needed);

Checks that the filesystem holding file has at least bytes_needed bytes available.

Parameters

dir

a GFile to check

 

bytes_needed

number of bytes to check for

 

Returns

TRUE if enough space is available.


rb_check_dir_has_space_uri ()

gboolean
rb_check_dir_has_space_uri (const char *uri,
                            guint64 bytes_needed);

Checks that the filesystem holding uri has at least bytes_needed bytes available.

Parameters

uri

a URI to check

 

bytes_needed

number of bytes to check for

 

Returns

TRUE if enough space is available.


rb_uri_get_mount_point ()

char *
rb_uri_get_mount_point (const char *uri);

Returns the mount point of the filesystem holding uri . If uri is on a normal filesystem mount (such as /, /home, /var, etc.) this will be NULL.

Parameters

uri

a URI

 

Returns

filesystem mount point (must be freed by caller) or NULL.


rb_uri_create_parent_dirs ()

gboolean
rb_uri_create_parent_dirs (const char *uri,
                           GError **error);

Ensures that all parent directories of uri exist so that uri itself can be created directly.

Parameters

uri

a URI for which to create parent directories

 

error

returns error information

 

Returns

TRUE if successful


rb_file_find_extant_parent ()

GFile *
rb_file_find_extant_parent (GFile *file);

Walks up the filesystem hierarchy to find a GFile representing the nearest extant ancestor of the specified file, which may be the file itself if it exists.

Parameters

file

a GFile to find an extant ancestor of

 

Returns

GFile for the nearest extant ancestor.

[transfer full]


rb_uri_get_filesystem_type ()

char *
rb_uri_get_filesystem_type (const char *uri,
                            char **mount_point);

Returns a string describing the type of the filesystem containing uri .

Parameters

uri

URI to get filesystem type for

 

mount_point

optionally returns the mount point for the filesystem as a URI

 

Returns

filesystem type string, must be freed by caller.


rb_sanitize_path_for_msdos_filesystem ()

void
rb_sanitize_path_for_msdos_filesystem (char *path);

Modifies path such that it represents a legal path for MS DOS filesystems. Note that it replaces forward slash characters, so it's only appropriate for use with individual path segments rather than entire paths.

Parameters

path

a path segment to sanitize (modified in place)

 

rb_sanitize_uri_for_filesystem ()

char *
rb_sanitize_uri_for_filesystem (const char *uri,
                                const char *filesystem);

Removes characters from uri that are not allowed by the filesystem on which it would be stored, or a specific type of filesystem if specified. At present, this only supports MS DOS filesystems.

Parameters

uri

a URI to sanitize

 

filesystem

a specific filesystem to sanitize for.

[allow-none]

Returns

sanitized copy of uri , must be freed by caller.


RBUriRecurseFunc ()

gboolean
(*RBUriRecurseFunc) (GFile *file,
                     GFileInfo *info,
                     gpointer data);