WebKit2.Download

g GObject.Object GObject.Object WebKit2.Download WebKit2.Download GObject.Object->WebKit2.Download

Subclasses:

None

Methods

Inherited:

GObject.Object (37)

Structs:

GObject.ObjectClass (5)

cancel ()

get_allow_overwrite ()

get_destination ()

get_elapsed_time ()

get_estimated_progress ()

get_received_data_length ()

get_request ()

get_response ()

get_web_view ()

set_allow_overwrite (allowed)

set_destination (destination)

Virtual Methods

Inherited:

GObject.Object (7)

do_decide_destination (suggested_filename)

Properties

Name

Type

Flags

Short Description

allow-overwrite

bool

r/w

destination

str

r

estimated-progress

float

r

response

WebKit2.URIResponse

r

Signals

Inherited:

GObject.Object (1)

Name

Short Description

created-destination

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

decide-destination

This signal is emitted after response is received to decide a destination for the download using WebKit2.Download.set_destination().

failed

This signal is emitted when an error occurs during the download operation.

finished

This signal is emitted when download finishes successfully or due to an error.

received-data

This signal is emitted after response is received, every time new data has been written to the destination.

Fields

Inherited:

GObject.Object (1)

Name

Type

Access

Description

parent

GObject.Object

r

Class Details

class WebKit2.Download(**kwargs)
Bases:

GObject.Object

Abstract:

No

Structure:

WebKit2.DownloadClass

Object used to communicate with the application when downloading.

WebKit2.Download carries information about a download request and response, including a WebKit2.URIRequest and a WebKit2.URIResponse 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.

cancel()

Cancels the download.

When the ongoing download operation is effectively cancelled the signal WebKit2.Download ::failed is emitted with WebKit2.DownloadError.CANCELLED_BY_USER error.

get_allow_overwrite()
Returns:

the current value of the WebKit2.Download :allow-overwrite property

Return type:

bool

Returns the current value of the WebKit2.Download :allow-overwrite property.

Returns the current value of the WebKit2.Download :allow-overwrite property, which determines whether the download will overwrite an existing file on disk, or if it will fail if the destination already exists.

New in version 2.6.

get_destination()
Returns:

the destination or None

Return type:

str or None

Obtains the destination to which the downloaded file will be written.

You can connect to WebKit2.Download ::created-destination to make sure this method returns a valid destination.

get_elapsed_time()
Returns:

seconds since the download was started

Return type:

float

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.

get_estimated_progress()
Returns:

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

Return type:

float

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

get_received_data_length()
Returns:

the amount of bytes already downloaded.

Return type:

int

Gets the length of the data already downloaded for self.

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

get_request()
Returns:

the WebKit2.URIRequest of self

Return type:

WebKit2.URIRequest

Retrieves the WebKit2.URIRequest object that backs the download process.

get_response()
Returns:

the WebKit2.URIResponse, or None if the response hasn’t been received yet.

Return type:

WebKit2.URIResponse

Retrieves the WebKit2.URIResponse object that backs the download process.

Retrieves the WebKit2.URIResponse object that backs the download process. This method returns None 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.

get_web_view()
Returns:

the WebKit2.WebView that initiated self, or None if self was not initiated by a WebKit2.WebView.

Return type:

WebKit2.WebView

Get the WebKit2.WebView that initiated the download.

set_allow_overwrite(allowed)
Parameters:

allowed (bool) – the new value for the WebKit2.Download :allow-overwrite property

Sets the WebKit2.Download :allow-overwrite property.

Sets the WebKit2.Download :allow-overwrite property, which determines whether the download may overwrite an existing file on disk, or if it will fail if the destination already exists.

New in version 2.6.

set_destination(destination)
Parameters:

destination (str) – the destination

Sets the destination 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 WebKit2.Download ::decide-destination signal and call WebKit2.Download.set_destination(). If you want to set a fixed destination that doesn’t depend on the suggested filename you can connect to notify::response signal and call WebKit2.Download.set_destination().

If WebKit2.Download ::decide-destination signal is not handled and destination is not set when the download transfer starts, the file will be saved with the filename suggested by the server in GLib.UserDirectory.DIRECTORY_DOWNLOAD directory.

do_decide_destination(suggested_filename) virtual
Parameters:

suggested_filename (str) –

Return type:

bool

Signal Details

WebKit2.Download.signals.created_destination(download, destination)
Signal Name:

created-destination

Flags:

RUN_LAST

Parameters:
  • download (WebKit2.Download) – The object which received the signal

  • destination (str) – the destination

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

WebKit2.Download.signals.decide_destination(download, suggested_filename)
Signal Name:

decide-destination

Flags:

RUN_LAST

Parameters:
  • download (WebKit2.Download) – The object which received the signal

  • suggested_filename (str) – the filename suggested for the download

Returns:

True to stop other handlers from being invoked for the event, or False to propagate the event further.

Return type:

bool

This signal is emitted after response is received to decide a destination for the download using WebKit2.Download.set_destination(). If this signal is not handled, the file will be downloaded to GLib.UserDirectory.DIRECTORY_DOWNLOAD directory using suggested_filename.

Since 2.40, you may handle this signal asynchronously by returning True without calling WebKit2.Download.set_destination(). This indicates intent to eventually call WebKit2.Download.set_destination(). In this case, the download will not proceed until the destination is set or cancelled with WebKit2.Download.cancel().

WebKit2.Download.signals.failed(download, error)
Signal Name:

failed

Flags:

RUN_LAST

Parameters:

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 WebKit2.Download.cancel(), this signal is emitted with error WebKit2.DownloadError.CANCELLED_BY_USER. The download operation finishes after an error and WebKit2.Download ::finished signal is emitted after this one.

WebKit2.Download.signals.finished(download)
Signal Name:

finished

Flags:

RUN_LAST

Parameters:

download (WebKit2.Download) – The object which received the signal

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

WebKit2.Download.signals.received_data(download, data_length)
Signal Name:

received-data

Flags:

RUN_LAST

Parameters:
  • download (WebKit2.Download) – The object which received the signal

  • data_length (int) – the length of data received in bytes

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.

Property Details

WebKit2.Download.props.allow_overwrite
Name:

allow-overwrite

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE

Whether or not the download is allowed to overwrite an existing file on disk. If this property is False and the destination already exists, the download will fail.

New in version 2.6.

WebKit2.Download.props.destination
Name:

destination

Type:

str

Default Value:

None

Flags:

READABLE

The local path to where the download will be saved.

WebKit2.Download.props.estimated_progress
Name:

estimated-progress

Type:

float

Default Value:

1.0

Flags:

READABLE

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 WebKit2.Download ::received-data signal to track the progress.

WebKit2.Download.props.response
Name:

response

Type:

WebKit2.URIResponse

Default Value:

None

Flags:

READABLE

The WebKit2.URIResponse associated with this download.