WebKitDownload

WebKitDownload — Object used to communicate with the application when downloading

Synopsis

struct              WebKitDownload;
WebKitURIRequest *  webkit_download_get_request         (WebKitDownload *download);
const gchar *       webkit_download_get_destination     (WebKitDownload *download);
void                webkit_download_set_destination     (WebKitDownload *download,
                                                         const gchar *uri);
WebKitURIResponse * webkit_download_get_response        (WebKitDownload *download);
void                webkit_download_cancel              (WebKitDownload *download);
gdouble             webkit_download_get_estimated_progress
                                                        (WebKitDownload *download);
gdouble             webkit_download_get_elapsed_time    (WebKitDownload *download);
guint64             webkit_download_get_received_data_length
                                                        (WebKitDownload *download);
WebKitWebView *     webkit_download_get_web_view        (WebKitDownload *download);

Object Hierarchy

  GObject
   +----WebKitDownload

Properties

  "destination"              gchar*                : Read
  "estimated-progress"       gdouble               : Read
  "response"                 WebKitURIResponse*    : Read

Signals

  "created-destination"                            : Run Last
  "decide-destination"                             : Run Last
  "failed"                                         : Run Last
  "finished"                                       : Run Last
  "received-data"                                  : Run Last

Description

WebKitDownload carries information about a download request and response, including a WebKitURIRequest and a WebKitURIResponse objects. The application may use this object to control the download process, or to simply figure out what is to be downloaded, and handle the download process itself.

Details

struct WebKitDownload

struct WebKitDownload;


webkit_download_get_request ()

WebKitURIRequest *  webkit_download_get_request         (WebKitDownload *download);

Retrieves the WebKitURIRequest object that backs the download process.

download :

a WebKitDownload

Returns :

the WebKitURIRequest of download. [transfer none]

webkit_download_get_destination ()

const gchar *       webkit_download_get_destination     (WebKitDownload *download);

Obtains the URI to which the downloaded file will be written. You can connect to "created-destination" to make sure this method returns a valid destination.

download :

a WebKitDownload

Returns :

the destination URI or NULL

webkit_download_set_destination ()

void                webkit_download_set_destination     (WebKitDownload *download,
                                                         const gchar *uri);

Sets the URI to which the downloaded file will be written. This method should be called before the download transfer starts or it will not have any effect on the ongoing download operation. To set the destination using the filename suggested by the server connect to "decide-destination" signal and call webkit_download_set_destination(). If you want to set a fixed destination URI that doesn't depend on the suggested filename you can connect to notify::response signal and call webkit_download_set_destination(). If "decide-destination" signal is not handled and destination URI is not set when the download tranfer starts, the file will be saved with the filename suggested by the server in G_USER_DIRECTORY_DOWNLOAD directory.

download :

a WebKitDownload

uri :

the destination URI

webkit_download_get_response ()

WebKitURIResponse * webkit_download_get_response        (WebKitDownload *download);

Retrieves the WebKitURIResponse object that backs the download process. This method returns NULL if called before the response is received from the server. You can connect to notify::response signal to be notified when the response is received.

download :

a WebKitDownload

Returns :

the WebKitURIResponse, or NULL if the response hasn't been received yet. [transfer none]

webkit_download_cancel ()

void                webkit_download_cancel              (WebKitDownload *download);

Cancels the download. When the ongoing download operation is effectively cancelled the signal "failed" is emitted with WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER error.

download :

a WebKitDownload

webkit_download_get_estimated_progress ()

gdouble             webkit_download_get_estimated_progress
                                                        (WebKitDownload *download);

Gets the value of the "estimated-progress" property. You can monitor the estimated progress of the download operation by connecting to the notify::estimated-progress signal of download.

download :

a WebKitDownload

Returns :

an estimate of the of the percent complete for a download as a range from 0.0 to 1.0.

webkit_download_get_elapsed_time ()

gdouble             webkit_download_get_elapsed_time    (WebKitDownload *download);

Gets the elapsed time in seconds, including any fractional part. If the download finished, had an error or was cancelled this is the time between its start and the event.

download :

a WebKitDownload

Returns :

seconds since the download was started

webkit_download_get_received_data_length ()

guint64             webkit_download_get_received_data_length
                                                        (WebKitDownload *download);

Gets the length of the data already downloaded for download in bytes.

download :

a WebKitDownload

Returns :

the amount of bytes already downloaded.

webkit_download_get_web_view ()

WebKitWebView *     webkit_download_get_web_view        (WebKitDownload *download);

Get the WebKitWebView that initiated the download.

download :

a WebKitDownload

Returns :

the WebKitWebView that initiated download, or NULL if download was not initiated by a WebKitWebView. [transfer none]

Property Details

The "destination" property

  "destination"              gchar*                : Read

The local URI to where the download will be saved.

Default value: NULL


The "estimated-progress" property

  "estimated-progress"       gdouble               : Read

An estimate of the percent completion for the download operation. This value will range from 0.0 to 1.0. The value is an estimate based on the total number of bytes expected to be received for a download. If you need a more accurate progress information you can connect to "received-data" signal to track the progress.

Allowed values: [0,1]

Default value: 1


The "response" property

  "response"                 WebKitURIResponse*    : Read

The WebKitURIResponse associated with this download.

Signal Details

The "created-destination" signal

gboolean            user_function                      (WebKitDownload *download,
                                                        gchar          *destination,
                                                        gpointer        user_data)        : Run Last

This signal is emitted after "decide-destination" and before "received-data" to notify that destination file has been created successfully at destination.

download :

the WebKitDownload

destination :

the destination URI

user_data :

user data set when the signal handler was connected.

The "decide-destination" signal

gboolean            user_function                      (WebKitDownload *download,
                                                        gchar          *suggested_filename,
                                                        gpointer        user_data)               : Run Last

This signal is emitted after response is received to decide a destination URI for the download. If this signal is not handled the file will be downloaded to G_USER_DIRECTORY_DOWNLOAD directory using suggested_filename.

download :

the WebKitDownload

suggested_filename :

the filename suggested for the download

user_data :

user data set when the signal handler was connected.

Returns :

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

The "failed" signal

void                user_function                      (WebKitDownload *download,
                                                        gpointer        error,
                                                        gpointer        user_data)      : Run Last

This signal is emitted when an error occurs during the download operation. The given error, of the domain WEBKIT_DOWNLOAD_ERROR, contains further details of the failure. If the download is cancelled with webkit_download_cancel(), this signal is emitted with error WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER. The download operation finishes after an error and "finished" signal is emitted after this one.

download :

the WebKitDownload

error :

the GError that was triggered

user_data :

user data set when the signal handler was connected.

The "finished" signal

void                user_function                      (WebKitDownload *download,
                                                        gpointer        user_data)      : Run Last

This signal is emitted when download finishes successfully or due to an error. In case of errors "failed" signal is emitted before this one.

download :

the WebKitDownload

user_data :

user data set when the signal handler was connected.

The "received-data" signal

void                user_function                      (WebKitDownload *download,
                                                        guint64         data_length,
                                                        gpointer        user_data)        : Run Last

This signal is emitted after response is received, every time new data has been written to the destination. It's useful to know the progress of the download operation.

download :

the WebKitDownload

data_length :

the length of data received in bytes

user_data :

user data set when the signal handler was connected.