Epiphany File Helpers 3 EPIPHANY Library
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;

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

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

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

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

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

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

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

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

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

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

### 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_get_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_init

### ephy_file_helpers_shutdown ()

    void                ephy_file_helpers_shutdown          (void);

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

ephy_file_helpers_shutdown

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

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

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

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

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

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

ephy_file_tmp_filename