## Epiphany File Helpers

Epiphany File Helpers — miscellaneous file related utility functions

## Synopsis

    enum                EphyMimePermission;
    const char *        ephy_file                           (const char *filename);
    void                ephy_file_add_recent_item           (const char *uri,
                                                             const char *mime_type);
    gboolean            ephy_file_browse_to                 (GFile *file,
                                                             guint32 user_time);
    EphyMimePermission  ephy_file_check_mime                (const char *mime_type);
    void                ephy_file_delete_directory          (const char *path);
    void                ephy_file_delete_on_exit            (GFile *file);
    void                ephy_file_delete_uri                (const char *uri);
    char *              ephy_file_desktop_dir               (void);
    char *              ephy_file_downloads_dir             (void);
    GSList *            ephy_file_find                      (const char *path,
                                                             const char *fname,
                                                             gint maxdepth);
    char *              ephy_file_get_downloads_dir         (void);
    gboolean            ephy_file_helpers_init              (const char *profile_dir,
                                                             gboolean private_profile,
                                                             gboolean keep_temp_dir,
                                                             GError **error);
    void                ephy_file_helpers_shutdown          (void);
    gboolean            ephy_file_launch_application        (GAppInfo *app,
                                                             GList *files,
                                                             guint32 user_time,
                                                             GtkWidget *widget);
    gboolean            ephy_file_launch_desktop_file       (const char *filename,
                                                             const char *parameter,
                                                             guint32 user_time,
                                                             GtkWidget *widget);
    gboolean            ephy_file_launch_handler            (const char *mime_type,
                                                             GFile *file,
                                                             guint32 user_time);
    gboolean            ephy_file_switch_temp_file          (GFile *file_dest,
                                                             GFile *file_temp);
    const char *        ephy_file_tmp_dir                   (void);
    char *              ephy_file_tmp_filename              (const char *base,
                                                             const char *extension);

## Description

File related functions, including functions to launch, browse or move files atomically.

## Details

### enum EphyMimePermission

    typedef enum
    {
    	EPHY_MIME_PERMISSION_SAFE = 1,
    	EPHY_MIME_PERMISSION_UNSAFE = 2,
    	EPHY_MIME_PERMISSION_UNKNOWN = 3
    } EphyMimePermission;

### ephy_file ()

    const char *        ephy_file                           (const char *filename);

Looks for `filename` in Epiphany's directories and relevant paths.

`filename` : | the name of the Epiphany file requested
Returns : | the full path to the requested file

### ephy_file_add_recent_item ()

    void                ephy_file_add_recent_item           (const char *uri,
                                                             const char *mime_type);

Adds `uri` to the default GtkRecentManager, with `mime_type` as its type.

`uri` : | an URI
`mime_type` : | the mime type corresponding to `uri`

### ephy_file_browse_to ()

    gboolean            ephy_file_browse_to                 (GFile *file,
                                                             guint32 user_time);

Launches the default application for browsing directories, with `file`'s parent directory as its target. Passes `user_time` to `ephy_file_launch_handler()` to prevent focus stealing.

`file` : | a GFile
`user_time` : | user_time to prevent focus stealing
Returns : | `TRUE` if the launch succeeded

### ephy_file_check_mime ()

    EphyMimePermission  ephy_file_check_mime                (const char *mime_type);

Checks `mime_type` against our safe/unsafe database of types, returns an EphyMimePermission.

`mime_type` : | a mime type
Returns : | an EphyMimePermission

### ephy_file_delete_directory ()

    void                ephy_file_delete_directory          (const char *path);

Remove `path` and its contents. Like calling rm -rf `path`.

`path` : | the path to remove

### ephy_file_delete_on_exit ()

    void                ephy_file_delete_on_exit            (GFile *file);

Schedules `file` to be deleted when Epiphany exits. This function currently does nothing.

`file` : | a GFile

### ephy_file_delete_uri ()

    void                ephy_file_delete_uri                (const char *uri);

Remove the given URI.

`uri` : | URI of the file to be deleted

### ephy_file_desktop_dir ()

    char *              ephy_file_desktop_dir               (void);

Gets the XDG desktop dir path or a default homedir/Desktop alternative.

Returns : | a newly-allocated string containing the desktop dir path.

### ephy_file_downloads_dir ()

    char *              ephy_file_downloads_dir             (void);

Gets the basename for Epiphany's Downloads dir. This depends on the current locale. For the full path to the downloads directory see `ephy_file_get_downloads_dir()`.

Returns : | a newly-allocated string containing the downloads dir basename.

### ephy_file_find ()

    GSList *            ephy_file_find                      (const char *path,
                                                             const char *fname,
                                                             gint maxdepth);

Searchs for `fname` in `path` with a maximum depth of `maxdepth`.

`path` : | path to search for `fname`
`fname` : | filename to search for
`maxdepth` : | maximum directory depth when searching `path`
Returns : | a GSList of matches

### ephy_file_get_downloads_dir ()

    char *              ephy_file_get_downloads_dir         (void);

Gets the full path to the downloads dir. This uses `ephy_file_downloads_dir()` internally and hence is locale dependant. Note that this can return `NULL` if not even the user homedir path can be found.

Returns : | a newly-allocated string containing the path to the downloads dir.

### ephy_file_helpers_init ()

    gboolean            ephy_file_helpers_init              (const char *profile_dir,
                                                             gboolean private_profile,
                                                             gboolean keep_temp_dir,
                                                             GError **error);

Initializes Epiphany file helper functions, sets `profile_dir` as Epiphany's profile dir and whether the running session will be private.

`profile_dir` : | directory to use as Epiphany's profile
`private_profile` : | `TRUE` if we should use a private profile
`keep_temp_dir` : | `TRUE` to omit deleting the temp dir on exit
`error` : | an optional GError
Returns : | `FALSE` if the profile dir couldn't be created or accesed

### ephy_file_helpers_shutdown ()

    void                ephy_file_helpers_shutdown          (void);

Cleans file helpers information, corresponds to `ephy_file_helpers_init()`.

### ephy_file_launch_application ()

    gboolean            ephy_file_launch_application        (GAppInfo *app,
                                                             GList *files,
                                                             guint32 user_time,
                                                             GtkWidget *widget);

Launches `app` to open `files`. If `widget` is set the screen and display from it will be used to launch the application, otherwise the defaults will be used.

`app` : | the application to launch
`files` : | files to pass to `app`
`user_time` : | user time to prevent focus stealing
`widget` : | a relevant widget from where to get the GdkScreen and GdkDisplay
Returns : | `TRUE` if `g_app_info_launch()` succeeded

### ephy_file_launch_desktop_file ()

    gboolean            ephy_file_launch_desktop_file       (const char *filename,
                                                             const char *parameter,
                                                             guint32 user_time,
                                                             GtkWidget *widget);

Calls `ephy_file_launch_application()` for the application described by the .desktop file `filename`. Can pass `parameter` as optional file arguments.

`filename` : | the path to the .desktop file
`parameter` : | path to a parameter file to pass to the application
`user_time` : | user time to prevent focus stealing
`widget` : | an optional widget for `ephy_file_launch_application()`
Returns : | `TRUE` if the application launch was successful

### ephy_file_launch_handler ()

    gboolean            ephy_file_launch_handler            (const char *mime_type,
                                                             GFile *file,
                                                             guint32 user_time);

Launches `file` with its default handler application, if `mime_type` is `NULL` then `file` will be queried for its type.

`mime_type` : | the mime type of `file` or `NULL`
`file` : | a GFile to pass as argument
`user_time` : | user time to prevent focus stealing
Returns : | `TRUE` on success

### ephy_file_switch_temp_file ()

    gboolean            ephy_file_switch_temp_file          (GFile *file_dest,
                                                             GFile *file_temp);

Moves `file_temp` to `file_dest` atomically, doing a backup and restoring it if something fails.

`file_dest` : | destination file
`file_temp` : | file to move to `file`
Returns : | `TRUE` if the switch was successful

### ephy_file_tmp_dir ()

    const char *        ephy_file_tmp_dir                   (void);

Returns the name of the temp dir for the running Epiphany instance.

Returns : | the name of the temp dir, this string belongs to Epiphany.

### ephy_file_tmp_filename ()

    char *              ephy_file_tmp_filename              (const char *base,
                                                             const char *extension);

Creates a temp file with `mkstemp()` using `base` as the name with an optional `extension`.

`base` : | the base name of the temp file to create
`extension` : | an optional extension for `base` or `NULL`
Returns : | a newly-allocated string containing the name of the created temp file or `NULL`.