rb-file-helpers

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

## Synopsis

    const char *        rb_file                             (const char *filename);
    const char *        rb_user_data_dir                    (void);
    const char *        rb_user_cache_dir                   (void);
    const char *        rb_music_dir                        (void);
    char *              rb_find_user_data_file              (const char *name);
    char *              rb_find_user_cache_file             (const char *name);
    void                rb_file_helpers_init                (gboolean uninstalled);
    void                rb_file_helpers_shutdown            (void);
    char *              rb_uri_resolve_symlink              (const char *uri,
                                                             GError **error);
    gboolean            rb_uri_is_directory                 (const char *uri);
    gboolean            rb_uri_exists                       (const char *uri);
    gboolean            rb_uri_is_readable                  (const char *uri);
    gboolean            rb_uri_is_writable                  (const char *uri);
    gboolean            rb_uri_is_local                     (const char *uri);
    gboolean            rb_uri_is_hidden                    (const char *uri);
    gboolean            rb_uri_could_be_podcast             (const char *uri,
                                                             gboolean *is_opml);
    char *              rb_uri_make_hidden                  (const char *uri);
    void                rb_uri_handle_recursively           (const char *uri,
                                                             GCancellable *cancel,
                                                             RBUriRecurseFunc func,
                                                             gpointer user_data);
    void                rb_uri_handle_recursively_async     (const char *uri,
                                                             GCancellable *cancel,
                                                             RBUriRecurseFunc func,
                                                             gpointer user_data,
                                                             GDestroyNotify data_destroy);
    gboolean            rb_uri_mkstemp                      (const char *prefix,
                                                             char **uri_ret,
                                                             GOutputStream **stream,
                                                             GError **error);
    char *              rb_canonicalise_uri                 (const char *uri);
    char *              rb_uri_append_path                  (const char *uri,
                                                             const char *path);
    char *              rb_uri_append_uri                   (const char *uri,
                                                             const char *fragment);
    char *              rb_uri_get_dir_name                 (const char *uri);
    char *              rb_uri_get_short_path_name          (const char *uri);
    gboolean            rb_check_dir_has_space              (GFile *dir,
                                                             guint64 bytes_needed);
    gboolean            rb_check_dir_has_space_uri          (const char *uri,
                                                             guint64 bytes_needed);
    char *              rb_uri_get_mount_point              (const char *uri);
    gboolean            rb_uri_create_parent_dirs           (const char *uri,
                                                             GError **error);
    GFile *             rb_file_find_extant_parent          (GFile *file);
    char *              rb_uri_get_filesystem_type          (const char *uri,
                                                             char **mount_point);
    void                rb_sanitize_path_for_msdos_filesystem
                                                            (char *path);
    char *              rb_sanitize_uri_for_filesystem      (const char *uri);
    gboolean            (*RBUriRecurseFunc)                 (GFile *file,
                                                             gboolean dir,
                                                             gpointer data);

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

## Details

### rb_file ()

    const char *        rb_file                             (const char *filename);

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

`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`).

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

`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                (gboolean uninstalled);

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

`uninstalled` : | if `TRUE`, search in source and build directories as well as installed locations

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

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

`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

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

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

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

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

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

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

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

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

Directory recursion happens on a separate thread, but the callbacks are called on the main thread.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`path` : | a path to sanitize (modified in place)

### rb_sanitize_uri_for_filesystem ()

    char *              rb_sanitize_uri_for_filesystem      (const char *uri);

Removes characters from `uri` that are not allowed by the filesystem on which it would be stored. At present, this only supports MS DOS filesystems.

`uri` : | a URI to sanitize
Returns : | sanitized copy of `uri`, must be freed by caller.

### RBUriRecurseFunc ()

    gboolean            (*RBUriRecurseFunc)                 (GFile *file,
                                                             gboolean dir,
                                                             gpointer data);