EphyEmbedPersist 3 EPIPHANY Library
EphyEmbedPersist A class to download files

## Synopsis

    void                ephy_embed_persist_set_dest         (EphyEmbedPersist *persist,
                                                             const char *value);
    void                ephy_embed_persist_set_embed        (EphyEmbedPersist *persist,
                                                             EphyEmbed *value);
    void                ephy_embed_persist_set_fc_title     (EphyEmbedPersist *persist,
                                                             const char *value);
    void                ephy_embed_persist_set_fc_parent    (EphyEmbedPersist *persist,
                                                             GtkWindow *value);
    void                ephy_embed_persist_set_flags        (EphyEmbedPersist *persist,
                                                             EphyEmbedPersistFlags value);
    void                ephy_embed_persist_set_max_size     (EphyEmbedPersist *persist,
                                                             gint64 value);
    void                ephy_embed_persist_set_persist_key  (EphyEmbedPersist *persist,
                                                             const char *value);
    void                ephy_embed_persist_set_source       (EphyEmbedPersist *persist,
                                                             const char *value);
    const char *        ephy_embed_persist_get_dest         (EphyEmbedPersist *persist);
    EphyEmbed *         ephy_embed_persist_get_embed        (EphyEmbedPersist *persist);
    const char *        ephy_embed_persist_get_fc_title     (EphyEmbedPersist *persist);
    GtkWindow *         ephy_embed_persist_get_fc_parent    (EphyEmbedPersist *persist);
    EphyEmbedPersistFlags  ephy_embed_persist_get_flags     (EphyEmbedPersist *persist);
    gint64              ephy_embed_persist_get_max_size     (EphyEmbedPersist *persist);
    const char *        ephy_embed_persist_get_persist_key  (EphyEmbedPersist *persist);
    const char *        ephy_embed_persist_get_source       (EphyEmbedPersist *persist);
    gboolean            ephy_embed_persist_save             (EphyEmbedPersist *persist);
    void                ephy_embed_persist_cancel           (EphyEmbedPersist *persist);
    char *              ephy_embed_persist_to_string        (EphyEmbedPersist *persist);

## Description

An EphyEmbedPersist is a relatively simple way to save a web page or file to disk. It is an abstract class, implemented by MozillaEmbedPersist.

To create an EphyEmbedPersist, use `ephy_embed_factory_new_object()`. Next, call `ephy_embed_persist_set_flags()` and `ephy_embed_persist_set_embed()`. Depending on the flags, you may also want to call `ephy_embed_persist_set_dest()` or `ephy_embed_persist_set_source()`. Finally, call `ephy_embed_persist_save()` to save the file.

Saving the current web page to disk

    #include <epiphany/ephy-embed-persist.h>
    #include <epiphany/ephy-embed.h>
    static void
    save_source_completed_cb (EphyEmbedPersist *persist,
    			  gpointer dummy)
    {
    	g_print ("Download to %s complete.\n",
    		 ephy_embed_persist_get_dest (persist));
    }
    void
    save_page (EphyEmbed *embed,
    	   const char *filename)
    {
    	EphyEmbedPersist *persist;
    	persist = EPHY_EMBED_PERSIST
    		(ephy_embed_factory_new_object ("EphyEmbedPersist"));
    	ephy_embed_persist_set_embed (persist, embed);
    	ephy_embed_persist_set_flags (persist, EMBED_PERSIST_NO_VIEW |
    					       EMBED_PERSIST_COPY_PAGE);
    	ephy_embed_persist_set_dest (persist, filename);
    	g_signal_connect (persist, "completed",
    			  G_CALLBACK (save_source_completed_cb), NULL);
    	ephy_embed_persist_save (persist);
    	g_object_unref (persist);
    }

## Details

### ephy_embed_persist_set_dest ()

    void                ephy_embed_persist_set_dest         (EphyEmbedPersist *persist,
                                                             const char *value);

Sets the path to which persist should save data.

persist :

  an EphyEmbedPersist

value :

  the path to which persist should save data

ephy_embed_persist_set_dest

### ephy_embed_persist_set_embed ()

    void                ephy_embed_persist_set_embed        (EphyEmbedPersist *persist,
                                                             EphyEmbed *value);

Sets the EphyEmbed from which persist will download data.

An EphyEmbed is absolutely required to download if persist's EphyEmbedPersistFlags include `EPHY_EMBED_PERSIST_COPY_PAGE`. Regardless, an EphyEmbed should be set for every EphyEmbedPersist, since it determines request information such as the referring page.

persist :

  an EphyEmbedPersist

value :

  a parent EphyEmbed

ephy_embed_persist_set_embed

### ephy_embed_persist_set_fc_title ()

    void                ephy_embed_persist_set_fc_title     (EphyEmbedPersist *persist,
                                                             const char *value);

Sets the title of the filechooser window. The filechooser will only be displayed if `EPHY_EMBED_PERSIST_ASK_DESTINATION` has been set with `ephy_embed_persist_set_flags()`.

persist :

  an EphyEmbedPersist

value :

  the title to be displayed by the filechooser

ephy_embed_persist_set_fc_title

### ephy_embed_persist_set_fc_parent ()

    void                ephy_embed_persist_set_fc_parent    (EphyEmbedPersist *persist,
                                                             GtkWindow *value);

Sets the EphyWindow which should be persist's filechooser's parent. The filechooser will only be displayed if `EPHY_EMBED_PERSIST_ASK_DESTINATION` has been set with `ephy_embed_persist_set_flags()`.

persist :

  an EphyEmbedPersist

value :

  the EphyWindow which should be the filechooser's parent

ephy_embed_persist_set_fc_parent

### ephy_embed_persist_set_flags ()

    void                ephy_embed_persist_set_flags        (EphyEmbedPersist *persist,
                                                             EphyEmbedPersistFlags value);

Sets the flags to be used for persist's download.

persist :

  an EphyEmbedPersist

value :

  the desired EphyEmbedPersistFlags

ephy_embed_persist_set_flags

### ephy_embed_persist_set_max_size ()

    void                ephy_embed_persist_set_max_size     (EphyEmbedPersist *persist,
                                                             gint64 value);

Sets the maximum size of persist's download.

If the requested file is discovered to be larger than value, the download will be aborted. Note that persist will have to actually begin downloading before it can abort, since it doesn't know the filesize before the download starts.

persist :

  an EphyEmbedPersist

value :

  maximum size of requested download, in bytes

ephy_embed_persist_set_max_size

### ephy_embed_persist_set_persist_key ()

    void                ephy_embed_persist_set_persist_key  (EphyEmbedPersist *persist,
                                                             const char *value);

Sets the GConf key from which persist will determine the default download directory.

persist :

  an EphyEmbedPersist

value :

  a GConf key

ephy_embed_persist_set_persist_key

### ephy_embed_persist_set_source ()

    void                ephy_embed_persist_set_source       (EphyEmbedPersist *persist,
                                                             const char *value);

Sets the URL from which persist should download. This should be used in conjunction with `ephy_embed_persist_set_embed()`.

persist :

  an EphyEmbedPersist

value :

  the URL from which persist should download

ephy_embed_persist_set_source

### ephy_embed_persist_get_dest ()

    const char *        ephy_embed_persist_get_dest         (EphyEmbedPersist *persist);

Returns the destination filename to which persist will save its download.

persist :

  an EphyEmbedPersist

Returns :

  persist's destination filename

ephy_embed_persist_get_dest

### ephy_embed_persist_get_embed ()

    EphyEmbed *         ephy_embed_persist_get_embed        (EphyEmbedPersist *persist);

Returns the EphyEmbed from which persist will download.

persist :

  an EphyEmbedPersist

Returns :

  the EphyEmbed from which persist will download

ephy_embed_persist_get_embed

### ephy_embed_persist_get_fc_title ()

    const char *        ephy_embed_persist_get_fc_title     (EphyEmbedPersist *persist);

Returns the title to be displayed in persist's filechooser.

persist :

  an EphyEmbedPersist

Returns :

  the title to be displayed in persist's filechooser

ephy_embed_persist_get_fc_title

### ephy_embed_persist_get_fc_parent ()

    GtkWindow *         ephy_embed_persist_get_fc_parent    (EphyEmbedPersist *persist);

Returns the EphyWindow which should serve as a parent for persist's filechooser.

persist :

  an EphyEmbedPersist

Returns :

  the EphyWindow parent for persist's filechooser

ephy_embed_persist_get_fc_parent

### ephy_embed_persist_get_flags ()

    EphyEmbedPersistFlags  ephy_embed_persist_get_flags     (EphyEmbedPersist *persist);

Returns persist's EphyEmbedPersistFlags.

persist :

  an EphyEmbedPersist

Returns :

  persist's EphyEmbedPersistFlags

ephy_embed_persist_get_flags

### ephy_embed_persist_get_max_size ()

    gint64              ephy_embed_persist_get_max_size     (EphyEmbedPersist *persist);

Returns the maximum size of persist's requested download, in bytes.

persist :

  an EphyEmbedPersist

Returns :

  the maximum size of persist's requested download, in bytes

ephy_embed_persist_get_max_size

### ephy_embed_persist_get_persist_key ()

    const char *        ephy_embed_persist_get_persist_key  (EphyEmbedPersist *persist);

Returns the GConf key which determines Epiphany's default download directory.

persist :

  an EphyEmbedPersist

Returns :

  the GConf key to the default download directory

ephy_embed_persist_get_persist_key

### ephy_embed_persist_get_source ()

    const char *        ephy_embed_persist_get_source       (EphyEmbedPersist *persist);

Returns the source URL of the file to download.

persist :

  an EphyEmbedPersist

Returns :

  a source URL

ephy_embed_persist_get_source

### ephy_embed_persist_save ()

    gboolean            ephy_embed_persist_save             (EphyEmbedPersist *persist);

Begins saving the file specified in persist.

If persist's EphyEmbedPersistFlags include `EPHY_EMBED_PERSIST_ASK_DESTINATION`, a filechooser dialog will be shown first.

The file will continue to download in the background until either the ::completed or the ::cancelled signals are emitted by persist.

persist :

  an EphyEmbedPersist

Returns :

  `TRUE` if the download began successfully

ephy_embed_persist_save

### ephy_embed_persist_cancel ()

    void                ephy_embed_persist_cancel           (EphyEmbedPersist *persist);

Cancels persist's download. This will not delete the partially downloaded file.

persist :

  an EphyEmbedPersist

ephy_embed_persist_cancel

### ephy_embed_persist_to_string ()

    char *              ephy_embed_persist_to_string        (EphyEmbedPersist *persist);

Returns the download specified by persist as a string instead of downloading it to a file.

The download is synchronous. An EphyEmbed must be specified with `ephy_embed_persist_set_embed()`. The function implicitly assumes that persist's EphyEmbedPersistFlags include `EPHY_EMBED_PERSIST_COPY_PAGE`. If persist's EphyEmbed has not finished downloading, this function will only return the portion of data which has already been downloaded.

The document will be modified: it will only include absolute links and it will be encoded as UTF-8.

persist :

  an EphyEmbedPersist

Returns :

  The contents of persist's EphyEmbed's web page

ephy_embed_persist_to_string