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