rb-file-helpers: Rhythmbox Development Reference Manual

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

## Functions

const char * | rb_file ()
const char * | rb_user_data_dir ()
const char * | rb_user_cache_dir ()
const char * | rb_music_dir ()
char * | rb_find_user_data_file ()
char * | rb_find_user_cache_file ()
void | rb_file_helpers_init ()
void | rb_file_helpers_shutdown ()
char * | rb_uri_resolve_symlink ()
gboolean | rb_uri_is_directory ()
gboolean | rb_uri_exists ()
gboolean | rb_uri_is_readable ()
gboolean | rb_uri_is_writable ()
gboolean | rb_uri_is_local ()
gboolean | rb_uri_is_hidden ()
gboolean | rb_uri_could_be_podcast ()
char * | rb_uri_make_hidden ()
void | rb_uri_handle_recursively ()
void | rb_uri_handle_recursively_async ()
gboolean | rb_uri_mkstemp ()
char * | rb_canonicalise_uri ()
char * | rb_uri_append_path ()
char * | rb_uri_append_uri ()
char * | rb_uri_get_dir_name ()
char * | rb_uri_get_short_path_name ()
gboolean | rb_check_dir_has_space ()
gboolean | rb_check_dir_has_space_uri ()
char * | rb_uri_get_mount_point ()
gboolean | rb_uri_create_parent_dirs ()
GFile * | rb_file_find_extant_parent ()
char * | rb_uri_get_filesystem_type ()
void | rb_sanitize_path_for_msdos_filesystem ()
char * | rb_sanitize_uri_for_filesystem ()
gboolean | (*RBUriRecurseFunc) ()

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

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

#### Parameters

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.

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