diff options
Diffstat (limited to 'src/webenginequick/doc/src/webengine_download_request.qdoc')
| -rw-r--r-- | src/webenginequick/doc/src/webengine_download_request.qdoc | 278 |
1 files changed, 278 insertions, 0 deletions
diff --git a/src/webenginequick/doc/src/webengine_download_request.qdoc b/src/webenginequick/doc/src/webengine_download_request.qdoc new file mode 100644 index 000000000..96d84e0a3 --- /dev/null +++ b/src/webenginequick/doc/src/webengine_download_request.qdoc @@ -0,0 +1,278 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \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 WebEngineDownloadRequest::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 +*/ |