WebKitDownload: WebKit2GTK+ Reference Manual

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

## Functions

WebKitURIRequest * | webkit_download_get_request ()
const gchar * | webkit_download_get_destination ()
void | webkit_download_set_destination ()
WebKitURIResponse * | webkit_download_get_response ()
void | webkit_download_cancel ()
gdouble | webkit_download_get_estimated_progress ()
gdouble | webkit_download_get_elapsed_time ()
guint64 | webkit_download_get_received_data_length ()
WebKitWebView * | webkit_download_get_web_view ()
gboolean | webkit_download_get_allow_overwrite ()
void | webkit_download_set_allow_overwrite ()

## Properties

gboolean | allow-overwrite | Read / Write
gchar * | destination | Read
gdouble | estimated-progress | Read
WebKitURIResponse * | response | Read

## Signals

void | created-destination | Run Last
gboolean | decide-destination | Run Last
void | failed | Run Last
void | finished | Run Last
void | received-data | Run Last

## Types and Values

struct | WebKitDownload

## Object Hierarchy

        GObject
        ╰── WebKitDownload

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

## Functions

### webkit_download_get_request ()

    WebKitURIRequest *
    webkit_download_get_request (WebKitDownload *download);

Retrieves the WebKitURIRequest object that backs the download process.

#### Parameters

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.

#### Parameters

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 transfer starts, the file will be saved with the filename suggested by the server in `G_USER_DIRECTORY_DOWNLOAD` directory.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

download | a WebKitDownload |

#### Returns

the WebKitWebView that initiated `download` , or `NULL` if `download` was not initiated by a WebKitWebView.

[transfer none]

### webkit_download_get_allow_overwrite ()

    gboolean
    webkit_download_get_allow_overwrite (WebKitDownload *download);

Returns the current value of the “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.

#### Parameters

download | a WebKitDownload |

#### Returns

the current value of the “allow-overwrite” property

Since: 2.6

### webkit_download_set_allow_overwrite ()

    void
    webkit_download_set_allow_overwrite (WebKitDownload *download,
                                         gboolean allowed);

Sets the “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.

#### Parameters

download | a WebKitDownload |
allowed | the new value for the “allow-overwrite” property |

Since: 2.6

## Types and Values

### struct WebKitDownload

    struct WebKitDownload;

## Property Details

### The `“allow-overwrite”` property

      “allow-overwrite”          gboolean

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.

Flags: Read / Write

Default value: FALSE

Since: 2.6

### The `“destination”` property

      “destination”              gchar *

The local URI to where the download will be saved.

Flags: Read

Default value: NULL

### The `“estimated-progress”` property

      “estimated-progress”       gdouble

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.

Flags: Read

Allowed values: [0,1]

Default value: 1

### The `“response”` property

      “response”                 WebKitURIResponse *

The WebKitURIResponse associated with this download.

Flags: Read

## Signal Details

### The `“created-destination”` signal

    void
    user_function (WebKitDownload *download,
                   gchar          *destination,
                   gpointer        user_data)

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

#### Parameters

download | the WebKitDownload |
destination | the destination URI |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“decide-destination”` signal

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

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

#### Parameters

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.

Flags: Run Last

### The `“failed”` signal

    void
    user_function (WebKitDownload *download,
                   GError         *error,
                   gpointer        user_data)

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.

#### Parameters

download | the WebKitDownload |
error | the GError that was triggered |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“finished”` signal

    void
    user_function (WebKitDownload *download,
                   gpointer        user_data)

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

#### Parameters

download | the WebKitDownload |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“received-data”` signal

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

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.

#### Parameters

download | the WebKitDownload |
data_length | the length of data received in bytes |
user_data | user data set when the signal handler was connected. |

Flags: Run Last