WebKitDownload

WebKitDownload — Object used to communicate with the application when downloading.

Synopsis

enum                WebKitDownloadError;
enum                WebKitDownloadStatus;
                    WebKitDownload;
void                webkit_download_cancel              (WebKitDownload *download);
guint64             webkit_download_get_current_size    (WebKitDownload *download);
const gchar *       webkit_download_get_destination_uri (WebKitDownload *download);
gdouble             webkit_download_get_elapsed_time    (WebKitDownload *download);
WebKitNetworkRequest * webkit_download_get_network_request
                                                        (WebKitDownload *download);
WebKitNetworkResponse * webkit_download_get_network_response
                                                        (WebKitDownload *download);
gdouble             webkit_download_get_progress        (WebKitDownload *download);
WebKitDownloadStatus webkit_download_get_status         (WebKitDownload *download);
const gchar *       webkit_download_get_suggested_filename
                                                        (WebKitDownload *download);
guint64             webkit_download_get_total_size      (WebKitDownload *download);
const gchar *       webkit_download_get_uri             (WebKitDownload *download);
WebKitDownload *    webkit_download_new                 (WebKitNetworkRequest *request);
void                webkit_download_set_destination_uri (WebKitDownload *download,
                                                         const gchar *destination_uri);
void                webkit_download_start               (WebKitDownload *download);

Object Hierarchy

  GObject
   +----WebKitDownload

Properties

  "current-size"             guint64               : Read
  "destination-uri"          gchar*                : Read / Write
  "network-request"          WebKitNetworkRequest*  : Read / Write / Construct Only
  "network-response"         WebKitNetworkResponse*  : Read / Write / Construct Only
  "progress"                 gdouble               : Read
  "status"                   WebKitDownloadStatus  : Read
  "suggested-filename"       gchar*                : Read
  "total-size"               guint64               : Read

Signals

  "error"                                          : Run Last

Description

WebKitDownload carries information about a download request, including a WebKitNetworkRequest object. The application may use this object to control the download process, or to simply figure out what is to be downloaded, and do it itself.

Details

enum WebKitDownloadError

typedef enum {
    WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER,
    WEBKIT_DOWNLOAD_ERROR_DESTINATION,
    WEBKIT_DOWNLOAD_ERROR_NETWORK
} WebKitDownloadError;

Enum values used to denote the various download errors.

WEBKIT_DOWNLOAD_ERROR_CANCELLED_BY_USER

The download failed due to user cancellation.

WEBKIT_DOWNLOAD_ERROR_DESTINATION

The download failed due to disk write failure.

WEBKIT_DOWNLOAD_ERROR_NETWORK

The download failed due to a network error.

enum WebKitDownloadStatus

typedef enum {
    WEBKIT_DOWNLOAD_STATUS_ERROR = -1,
    WEBKIT_DOWNLOAD_STATUS_CREATED = 0,
    WEBKIT_DOWNLOAD_STATUS_STARTED,
    WEBKIT_DOWNLOAD_STATUS_CANCELLED,
    WEBKIT_DOWNLOAD_STATUS_FINISHED
} WebKitDownloadStatus;

Enum values used to denote the various states of a download.

WEBKIT_DOWNLOAD_STATUS_ERROR

The download failed because of an error other than user cancellation.

WEBKIT_DOWNLOAD_STATUS_CREATED

The download has not started yet.

WEBKIT_DOWNLOAD_STATUS_STARTED

The download has started, but has not completed yet.

WEBKIT_DOWNLOAD_STATUS_CANCELLED

The user canceled the download.

WEBKIT_DOWNLOAD_STATUS_FINISHED

The download completed successfully.

WebKitDownload

typedef struct _WebKitDownload WebKitDownload;


webkit_download_cancel ()

void                webkit_download_cancel              (WebKitDownload *download);

Cancels the download. Calling this will not free the WebKitDownload object, so you still need to call g_object_unref() on it, if you are the owner of a reference. Notice that cancelling the download provokes the emission of the WebKitDownload::error signal, reporting that the download was cancelled.

download :

the WebKitDownload

Since 1.1.2


webkit_download_get_current_size ()

guint64             webkit_download_get_current_size    (WebKitDownload *download);

Current already downloaded size.

download :

the WebKitDownload

Returns :

the already downloaded size

Since 1.1.2


webkit_download_get_destination_uri ()

const gchar *       webkit_download_get_destination_uri (WebKitDownload *download);

Obtains the URI to which the downloaded file will be written. This must have been set by the application before calling webkit_download_start(), and may be NULL.

download :

the WebKitDownload

Returns :

the destination URI or NULL

Since 1.1.2


webkit_download_get_elapsed_time ()

gdouble             webkit_download_get_elapsed_time    (WebKitDownload *download);

Elapsed time for the download in seconds, including any fractional part. If the download is 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, as a gdouble

Since 1.1.2


webkit_download_get_network_request ()

WebKitNetworkRequest * webkit_download_get_network_request
                                                        (WebKitDownload *download);

Retrieves the WebKitNetworkRequest object that backs the download process.

download :

the WebKitDownload

Returns :

the WebKitNetworkRequest instance. [transfer none]

Since 1.1.2


webkit_download_get_network_response ()

WebKitNetworkResponse * webkit_download_get_network_response
                                                        (WebKitDownload *download);

Retrieves the WebKitNetworkResponse object that backs the download process.

download :

the WebKitDownload

Returns :

the WebKitNetworkResponse instance. [transfer none]

Since 1.1.16


webkit_download_get_progress ()

gdouble             webkit_download_get_progress        (WebKitDownload *download);

Determines the current progress of the download.

download :

a WebKitDownload

Returns :

a gdouble ranging from 0.0 to 1.0.

Since 1.1.2


webkit_download_get_status ()

WebKitDownloadStatus webkit_download_get_status         (WebKitDownload *download);

Obtains the current status of the download, as a WebKitDownloadStatus.

download :

the WebKitDownload

Returns :

the current WebKitDownloadStatus

Since 1.1.2


webkit_download_get_suggested_filename ()

const gchar *       webkit_download_get_suggested_filename
                                                        (WebKitDownload *download);

Retrieves the filename that was suggested by the server, or the one derived by WebKit from the URI.

download :

the WebKitDownload

Returns :

the suggested filename

Since 1.1.2


webkit_download_get_total_size ()

guint64             webkit_download_get_total_size      (WebKitDownload *download);

Returns the expected total size of the download. This is expected because the server may provide incorrect or missing Content-Length. Notice that this may grow over time, as it will be always the same as current_size in the cases where current size surpasses it.

download :

the WebKitDownload

Returns :

the expected total size of the downloaded file

Since 1.1.2


webkit_download_get_uri ()

const gchar *       webkit_download_get_uri             (WebKitDownload *download);

Convenience method to retrieve the URI from the WebKitNetworkRequest which is being downloaded.

download :

the WebKitDownload

Returns :

the URI

Since 1.1.2


webkit_download_new ()

WebKitDownload *    webkit_download_new                 (WebKitNetworkRequest *request);

Creates a new WebKitDownload object for the given WebKitNetworkRequest object.

request :

a WebKitNetworkRequest

Returns :

the new WebKitDownload

Since 1.1.2


webkit_download_set_destination_uri ()

void                webkit_download_set_destination_uri (WebKitDownload *download,
                                                         const gchar *destination_uri);

Defines the URI that should be used to save the downloaded file to.

download :

the WebKitDownload

destination_uri :

the destination URI

Since 1.1.2


webkit_download_start ()

void                webkit_download_start               (WebKitDownload *download);

Initiates the download. Notice that you must have set the destination-uri property before calling this method.

download :

the WebKitDownload

Since 1.1.2

Property Details

The "current-size" property

  "current-size"             guint64               : Read

The length of the data already downloaded

Default value: 0

Since 1.1.2


The "destination-uri" property

  "destination-uri"          gchar*                : Read / Write

The URI of the save location for this download.

Default value: ""

Since 1.1.2


The "network-request" property

  "network-request"          WebKitNetworkRequest*  : Read / Write / Construct Only

The WebKitNetworkRequest instance associated with the download.

Since 1.1.2


The "network-response" property

  "network-response"         WebKitNetworkResponse*  : Read / Write / Construct Only

The WebKitNetworkResponse instance associated with the download.

Since 1.1.16


The "progress" property

  "progress"                 gdouble               : Read

Determines the current progress of the download. Notice that, although the progress changes are reported as soon as possible, the emission of the notify signal for this property is throttled, for the benefit of download managers. If you care about every update, use WebKitDownload:current-size.

Allowed values: [0,1]

Default value: 1

Since 1.1.2


The "status" property

  "status"                   WebKitDownloadStatus  : Read

Determines the current status of the download.

Default value: WEBKIT_DOWNLOAD_STATUS_CREATED

Since 1.1.2


The "suggested-filename" property

  "suggested-filename"       gchar*                : Read

The file name suggested as default when saving

Default value: ""

Since 1.1.2


The "total-size" property

  "total-size"               guint64               : Read

The total size of the file

Default value: 0

Since 1.1.2

Signal Details

The "error" signal

gboolean            user_function                      (WebKitDownload *download,
                                                        gint            error_code,
                                                        gint            error_detail,
                                                        gchar          *reason,
                                                        gpointer        user_data)         : Run Last

Emitted when download is interrupted either by user action or by network errors, error_detail will take any value of WebKitDownloadError.

download :

the object on which the signal is emitted

error_code :

the corresponding error code

error_detail :

detailed error code for the error, see WebKitDownloadError

reason :

a string describing the error

user_data :

user data set when the signal handler was connected.

Since 1.1.2