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 Functions Index

virtual ~WebResourceRequestFilter ()
boolfilterResourceData (WebResourceRequest *request, QByteArray &data)=0
boolfilterResourceDone (WebResourceRequest *request)=0
boolfilterResourceError (int status, const QUrl &url, const QString &message)=0
boolfilterResourceHeader (WebResourceRequest *request, QString &key, QString &value)=0
boolfilterResourceOpened (WebResourceRequest *request, int &status, QString &message)=0
FilterActionfilterResourceRequest (WebResourceRequest *request, RequestPurpose purpose)=0

Public Types

FilterAction

The action the WebPage should take for a Resource request.

Since:

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.

RequestPurpose

The purpose of the Resource Request.

Since:

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.

SharedWorker
FileDownload

An explicit file download to be saved to the device file system.

StyleSheet
Script
Font
Image
Object
Media

Public Functions

virtual~WebResourceRequestFilter ()

Destructor.

bool filterResourceData (

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.

Return:

true to preventDefault and discard this data completely.

Since:

BlackBerry 10.0.0

bool filterResourceDone (

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.

Return:

true to preventDefault and prevent the resource from closing.

Since:

BlackBerry 10.0.0

bool filterResourceError (

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.

Return:

true to preventDefault, thus handling the error.

Since:

BlackBerry 10.0.0

bool filterResourceHeader (

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.

Return:

true to preventDefault and discard this header completely.

Since:

BlackBerry 10.0.0

bool filterResourceOpened (

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.

Return:

true to preventDefault and abandon the request.

Since:

BlackBerry 10.0.0

FilterAction filterResourceRequest (

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.

Return:

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.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus