EphyEmbedPersist

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

Example 3. 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_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_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_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_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_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_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_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_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_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_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_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_flags ()

    EphyEmbedPersistFlags ephy_embed_persist_get_flags
                                                (EphyEmbedPersist *persist);

Returns `persist`'s EphyEmbedPersistFlags.

`persist` : | an EphyEmbedPersist
Returns : | `persist`'s EphyEmbedPersistFlags

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