1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
|
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\qmltype WebEngineDownloadRequest
\instantiates QWebEngineDownloadRequest
\inqmlmodule QtWebEngine
\brief Provides information about a download.
WebEngineDownloadRequest models a download throughout its life cycle, starting
with a pending download request and finishing with a completed download. It
can be used, for example, to get information about new downloads, to monitor
progress, and to pause, resume, and cancel downloads.
Downloads are usually triggered by user interaction on a web page. It is the
WebEngineProfile's responsibility to notify the application of new download
requests, which it does by emitting the
\l{WebEngineProfile::downloadRequested}{downloadRequested} signal together
with a newly created WebEngineDownloadRequest. The application can then examine
this item and decide whether to accept it or not. A signal handler must
explicitly call accept() on the item for \QWE to actually start
downloading and writing data to disk. If no signal handler calls accept(),
then the download request will be automatically rejected and nothing will be
written to disk.
\note Some properties, like the \l path under which the file will be saved,
can only be changed before calling accept().
\section2 Object Life Cycle
All items are guaranteed to be valid during the emission of the
\l{WebEngineProfile::downloadRequested}{downloadRequested} signal. If
accept() is \e not called by any signal handler, then the item will be
deleted \e immediately after signal emission. This means that the
application \b{must not} keep references to rejected download items.
\section2 Web Page Downloads
In addition to normal file downloads, which consist simply of retrieving
some raw bytes from the network and writing them to disk, \QWE also
supports saving complete web pages, which involves parsing the page's HTML,
downloading any dependent resources, and potentially packaging everything
into a special file format (\l savePageFormat). To check if a download is
for a file or a web page, use \l isSavePageDownload.
\sa WebEngineProfile, WebEngineProfile::downloadRequested,
WebEngineProfile::downloadFinished
*/
/*!
\qmlmethod void WebEngineDownloadRequest::accept()
Accepts the download request, which will start the download.
If the item is in the \c DownloadRequested state, then it will transition
into the \c DownloadInProgress state and the downloading will begin. If the
item is in any other state, then nothing will happen.
\sa state
*/
/*!
\qmlmethod void WebEngineDownloadRequest::cancel()
Cancels the download.
If the item is in the \c DownloadInProgress state, then it will transition
into the \c DownloadCancelled state, the downloading will stop, and
partially downloaded files will be deleted from disk.
If the item is in the \c DownloadCompleted state, then nothing will happen.
If the item is in any other state, then it will transition into the \c
DownloadCancelled state without further effect.
\sa state
*/
/*!
\qmlmethod void WebEngineDownloadRequest::pause()
Pauses the download.
Has no effect if the state is not \c DownloadInProgress. Does not change the
state.
\sa resume, isPaused
*/
/*!
\qmlmethod void WebEngineDownloadRequest::resume()
Resumes the download if it was paused or interrupted.
Has no effect if the state is not \c DownloadInProgress or \c
DownloadInterrupted. Does not change the state.
\sa pause, isPaused
*/
/*!
\qmlproperty int WebEngineDownloadRequest::id
Holds the download item's ID.
*/
/*!
\qmlproperty enumeration WebEngineDownloadRequest::state
Describes the state of the download:
\value WebEngineDownloadRequest.DownloadRequested
Download has been requested, but it has not been accepted yet.
\value WebEngineDownloadRequest.DownloadInProgress
Download is in progress.
\value WebEngineDownloadRequest.DownloadCompleted
Download completed successfully.
\value WebEngineDownloadRequest.DownloadCancelled
Download was cancelled by the user.
\value WebEngineDownloadRequest.DownloadInterrupted
Download has been interrupted (by the server or because of lost connectivity).
*/
/*!
\qmlproperty int WebEngineDownloadRequest::totalBytes
Holds the total amount of data to download in bytes.
\c -1 means the total size is unknown.
*/
/*!
\qmlproperty int WebEngineDownloadRequest::receivedBytes
Holds the amount of data in bytes that has been downloaded so far.
*/
/*!
\qmlproperty url WebEngineDownloadRequest::url
\readonly
Returns the download's origin URL.
*/
/*!
\qmlproperty string WebEngineDownloadRequest::mimeType
Holds the MIME type of the download.
*/
/*!
\qmlproperty string WebEngineDownloadRequest::downloadDirectory
Holds the full target path without file name where data is being downloaded to.
The download directory can only be set in the
\l{WebEngineProfile::downloadRequested}{downloadRequested} handler before
the download is accepted.
\sa WebEngineProfile::downloadRequested(), accept()
*/
/*!
\qmlproperty string WebEngineDownloadRequest::downloadFileName
Holds the name of the file to which data is being downloaded.
The download file name can only be set in the
\l{WebEngineProfile::downloadRequested}{downloadRequested} handler before
the download is accepted.
\sa WebEngineProfile::downloadRequested(), accept()
*/
/*!
\qmlproperty string WebEngineDownloadRequest::suggestedFileName
Returns the suggested file name.
*/
/*!
\qmlproperty enumeration WebEngineDownloadRequest::savePageFormat
Describes the format that is used to save a web page.
\value WebEngineDownloadRequest.UnknownSaveFormat
This is not a request for downloading a complete web page.
\value WebEngineDownloadRequest.SingleHtmlSaveFormat
The page is saved as a single HTML page. Resources such as images
are not saved.
\value WebEngineDownloadRequest.CompleteHtmlSaveFormat
The page is saved as a complete HTML page, for example a directory
containing the single HTML page and the resources.
\value WebEngineDownloadRequest.MimeHtmlSaveFormat
The page is saved as a complete web page in the MIME HTML format.
*/
/*!
\qmlproperty bool WebEngineDownloadItem::isSavePageDownload
\readonly
Whether this is a download request for saving a web page or a file.
\sa savePageFormat
*/
/*!
\qmlproperty enumeration WebEngineDownloadRequest::interruptReason
\readonly
Returns the reason why the download was interrupted:
\value WebEngineDownloadRequest.NoReason Unknown reason or not interrupted.
\value WebEngineDownloadRequest.FileFailed General file operation failure.
\value WebEngineDownloadRequest.FileAccessDenied The file cannot be written locally, due to access restrictions.
\value WebEngineDownloadRequest.FileNoSpace Insufficient space on the target drive.
\value WebEngineDownloadRequest.FileNameTooLong The directory or file name is too long.
\value WebEngineDownloadRequest.FileTooLarge The file size exceeds the file system limitation.
\value WebEngineDownloadRequest.FileVirusInfected The file is infected with a virus.
\value WebEngineDownloadRequest.FileTransientError Temporary problem (for example the file is in use,
out of memory, or too many files are opened at once).
\value WebEngineDownloadRequest.FileBlocked The file was blocked due to local policy.
\value WebEngineDownloadRequest.FileSecurityCheckFailed An attempt to check the safety of the download
failed due to unexpected reasons.
\value WebEngineDownloadRequest.FileTooShort An attempt was made to seek past the end of a file when
opening a file (as part of resuming a previously interrupted download).
\value WebEngineDownloadRequest.FileHashMismatch The partial file did not match the expected hash.
\value WebEngineDownloadRequest.NetworkFailed General network failure.
\value WebEngineDownloadRequest.NetworkTimeout The network operation has timed out.
\value WebEngineDownloadRequest.NetworkDisconnected The network connection has been terminated.
\value WebEngineDownloadRequest.NetworkServerDown The server has gone down.
\value WebEngineDownloadRequest.NetworkInvalidRequest The network request was invalid (for example, the
original or redirected URL is invalid, has an unsupported scheme, or is disallowed by policy).
\value WebEngineDownloadRequest.ServerFailed General server failure.
\value WebEngineDownloadRequest.ServerBadContent The server does not have the requested data.
\value WebEngineDownloadRequest.ServerUnauthorized The server did not authorize access to the resource.
\value WebEngineDownloadRequest.ServerCertProblem A problem with the server certificate occurred.
\value WebEngineDownloadRequest.ServerForbidden Access forbidden by the server.
\value WebEngineDownloadRequest.ServerUnreachable Unexpected server response (might indicate that
the responding server may not be the intended server).
\value WebEngineDownloadRequest.UserCanceled The user canceled the download.
\sa interruptReasonString
*/
/*!
\qmlproperty string WebEngineDownloadRequest::interruptReasonString
Returns a human-readable description of the reason for interrupting the download.
\sa interruptReason
*/
/*!
\qmlproperty bool WebEngineDownloadRequest::isFinished
\readonly
Whether this download is finished (completed, cancelled, or non-resumable interrupted state).
*/
/*!
\qmlproperty bool WebEngineDownloadRequest::isPaused
\readonly
Whether this download is paused.
\sa pause, resume
*/
/*!
\qmlproperty WebEngineView WebEngineDownloadRequest::view
\readonly
Returns the view the download was requested on. If the download was not triggered by content in a view,
\c nullptr is returned.
\sa WebEngineView
*/
|
