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,
                                                             GError **error);
    char *              rb_find_user_cache_file             (const char *name,
                                                             GError **error);
    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);
    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,
                                                             GError **error);

Determines the full path to use for user-specific files, such as rhythmdb.xml. This first checks in the user data directory (see `rb_user_data_dir`). If the file does not exist in the user data directory, it then checks the old .gnome2 directory, moving the file to the user data directory if found there. If an error occurs while moving the file, this will be reported through `error` and the .gnome2 path will be returned.

`name` : | name of file to find
`error` : | returns error information
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,
                                                             GError **error);

Determines the full path to use for user-specific cached files. This first checks in the user cache directory (see `rb_user_cache_dir`). If the file does not exist in the user cache directory, it then checks the old .gnome2 directory, moving the file to the user cache directory if found there. If an error occurs while moving the file, this will be reported through `error` and the .gnome2 path will be returned.

`name` : | name of file to find
`error` : | returns error information
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
`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

### rb_uri_get_filesystem_type ()

    char *              rb_uri_get_filesystem_type          (const char *uri);

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

`uri` : | URI to get filesystem type for
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);

`file` : |
`dir` : |
`data` : |
Returns : |