WebResourceRequestFilter
Since: BlackBerry 10.0.0
#include <bb/cascades/WebResourceRequestFilter>
A class that exposes control over the networking layer of a WebPage.
This interface is designed to be implemented and provided by a consumer seeking advanced control over resource requests coming from the WebPage.
If an implementation of the class is instantiated and provided via WebPage::setNetworkResourceRequestFilter(WebResourceRequestFilter*), all resource requests can be intercepted in the following sequence:
1. filterResourceRequest() (and then if FilterAction is set to Filter, the following:) 2. filterResourceOpened() 3. filterResourceHeader() (once per HTTP Header) 4. filterResourceData() 5. filterResourceDone()
Overview
Public Types Index
enum FilterAction | |
enum RequestPurposeUnknown, MainFrame, Subframe, Subresource, XmlHttpRequest, Worker, SharedWorker, FileDownload, StyleSheet, Script, Font, Image, Object, Media |
Public Functions Index
| virtual | ~WebResourceRequestFilter () |
| bool | filterResourceData (WebResourceRequest *request, QByteArray &data)=0 |
| bool | filterResourceDone (WebResourceRequest *request)=0 |
| bool | filterResourceError (int status, const QUrl &url, const QString &message)=0 |
| bool | filterResourceHeader (WebResourceRequest *request, QString &key, QString &value)=0 |
| bool | filterResourceOpened (WebResourceRequest *request, int &status, QString &message)=0 |
| FilterAction | filterResourceRequest (WebResourceRequest *request, RequestPurpose purpose)=0 |
Public Types
BlackBerry 10.0.0
- Accept
Treat this request normally.
- Deny
Abandon the request completely.
- Substitute
This implementation of WebResourceRequestFilter will perform the request.
- Filter
This implementation of WebResourceRequestFilter would like callbacks throughout the request.
The purpose of the Resource Request.
BlackBerry 10.0.0
- Unknown
Nothing is known about the purpose.
- MainFrame
- Subframe
- Subresource
An unknown subresource. Known subresources are below.
- XmlHttpRequest
AJAX.
- Worker
HTML5 JavaScript worker communication.
- FileDownload
An explicit file download to be saved to the device file system.
- StyleSheet
- Script
- Font
- Image
- Object
- Media
Public Functions
virtual
Destructor.
bool
Allows the implementation to actually modify the incoming data.
Called for a given request when the FilterAction was set to Filter.
| Parameters | |
|---|---|
| request |
An object representing this request. |
| data |
If modified, a deep copy will be made behind the scenes, so this method is only heavy if it is used to modify the data. |
true to preventDefault and discard this data completely.
BlackBerry 10.0.0
bool
Allows the implementation to intercept the resource closed notification.
Called for a given request when the FilterAction was set to Filter.
| Parameters | |
|---|---|
| request |
An object representing this request. |
true to preventDefault and prevent the resource from closing.
BlackBerry 10.0.0
bool
Allows the implementation to intercept a network error and opt to prevent showing the user the error.
Called before filterResourceOpened if the network returned an error.
| Parameters | |
|---|---|
| status |
The error code of the request. |
| url |
The originally requested URL. |
| message |
The error message provided. |
true to preventDefault, thus handling the error.
BlackBerry 10.0.0
bool
Allows the implementation to adjust each HTTP header.
Called for a given request when the FilterAction was set to Filter.
| Parameters | |
|---|---|
| request |
An identifier for this request. |
| key |
The key part of an HTTP header. It can be modified here. |
| value |
The value part of an HTTP header. It can be modified here. |
true to preventDefault and discard this header completely.
BlackBerry 10.0.0
bool
Allows the implementation to adjust the status and message for the request.
Called for a given request when the FilterAction was set to Filter.
| Parameters | |
|---|---|
| request |
An object representing this request. |
| status |
The HTTP status code. It can be modified here. |
| message |
The HTTP status message. It can be modified here. |
true to preventDefault and abandon the request.
BlackBerry 10.0.0
FilterAction
Suggests how this WebResourceRequestFilter would like this request to proceed.
The life cycle of the provided WebResourceRequest object depends on the action taken. Accept and Deny actions will result in the request being deleted immediately after the filterResourceRequest() returns, unless the application developer has called setParent() on the request. In that case, ownership is transferred to the application.
In the Substitute case, an application developer should use setParent() to take ownership of the request, and then call the following methods after the filterResourceRequest returns to provide the data for the request.
1. request->notifyOpen() 2. request->notifyHeaderReceived() // 0 or more times 3. request->notifyDataReceived() // 0 or more times 4. request->notifyDone() 5. request->deleteLater() // Recommended method of cleanup.
In the Filter case, the request's lifetime will continue until the filterNotifyDone() method returns, at which point it will be deleted if setParent has not been called.
In the Substitute and Filter cases the request and the WebPage can be independently deleted. It is safe to call deleteLater() on the request when it is no longer needed as an optimization. This includes destroying a request after, for example, a particular notifyHeaderReceived occurs when the application no longer needs any more callbacks for this request.
| Parameters | |
|---|---|
| request |
An object representing this request. |
| purpose |
A hint as to the purpose of this request. |
FilterAction indicating how this request should be handled. Accept - Treat the request normally. No further calls will be made for this request. Deny - Cancel this request. Whatever resource will not be loaded. Substitute - Call methods on the WebResourceRequest object to inject headers and data Filter - Call back to this WebResourceRequestFilter and allow the implementation to tweak the request on the fly. The following four methods will be called.
BlackBerry 10.0.0