WebKitGTK+ Reference Manual: WebKitDownload

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

## Functions

void | webkit_download_cancel ()
guint64 | webkit_download_get_current_size ()
const gchar * | webkit_download_get_destination_uri ()
gdouble | webkit_download_get_elapsed_time ()
WebKitNetworkRequest * | webkit_download_get_network_request ()
WebKitNetworkResponse * | webkit_download_get_network_response ()
gdouble | webkit_download_get_progress ()
WebKitDownloadStatus | webkit_download_get_status ()
const gchar * | webkit_download_get_suggested_filename ()
guint64 | webkit_download_get_total_size ()
const gchar * | webkit_download_get_uri ()
WebKitDownload * | webkit_download_new ()
void | webkit_download_set_destination_uri ()
void | webkit_download_start ()

## Properties

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

## Signals

gboolean | error | Run Last

## Types and Values

enum | WebKitDownloadError
enum | WebKitDownloadStatus
| WebKitDownload

## Object Hierarchy

        GObject
        ╰── WebKitDownload

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

## Functions

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

#### Parameters

download | the WebKitDownload |

Since 1.1.2

### webkit_download_get_current_size ()

    guint64
    webkit_download_get_current_size (WebKitDownload *download);

Current already downloaded size.

#### Parameters

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

download | the WebKitDownload |

Since 1.1.2

## Types and Values

### enum WebKitDownloadError

Enum values used to denote the various download errors.

#### Members

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

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

#### Members

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;

## Property Details

### The `“current-size”` property

      “current-size”             guint64

The length of the data already downloaded

Flags: Read

Default value: 0

Since 1.1.2

### The `“destination-uri”` property

      “destination-uri”          gchar *

The URI of the save location for this download.

Flags: Read / Write

Default value: ""

Since 1.1.2

### The `“network-request”` property

      “network-request”          WebKitNetworkRequest *

The WebKitNetworkRequest instance associated with the download.

Flags: Read / Write / Construct Only

Since 1.1.2

### The `“network-response”` property

      “network-response”         WebKitNetworkResponse *

The WebKitNetworkResponse instance associated with the download.

Flags: Read / Write / Construct Only

Since 1.1.16

### The `“progress”` property

      “progress”                 gdouble

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.

Flags: Read

Allowed values: [0,1]

Default value: 1

Since 1.1.2

### The `“status”` property

      “status”                   WebKitDownloadStatus

Determines the current status of the download.

Flags: Read

Default value: WEBKIT_DOWNLOAD_STATUS_CREATED

Since 1.1.2

### The `“suggested-filename”` property

      “suggested-filename”       gchar *

The file name suggested as default when saving

Flags: Read

Default value: ""

Since 1.1.2

### The `“total-size”` property

      “total-size”               guint64

The total size of the file

Flags: Read

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)

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

#### Parameters

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

Flags: Run Last

Since 1.1.2