blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions

<GDURLRequestDataDelegate> Protocol Reference

Delegate for managing the URL requests associated with a UIWebView control. More...

#import <GDURLRequestDataDelegate.h>

List of all members.

Public Member Functions


Detailed Description

URL requests issued by a UIWebView control can be managed by creating a class that implements this protocol.

This protocol enables a number of monitoring and control actions, including:

  • Cancellation of a URL request before it is sent.
  • Replacement of a URL request with a modified request.
  • Monitoring of the receipt of headers and data in response to a URL request.

This protocol is similar to the native NSURLConnectionDataDelegate and UIWebViewDelegate protocols. The functional differences are:

  • Callback functions are only invoked if the BlackBerry Dynamics proxy infrastructure is in use via the URL Loading System, i.e. only if the GDURLLoadingSystem is handling HTTP.
  • The delegate for URL request handling is attached to the user interface control, not to an individual request. Any URL request issued from the user interface that is handled by the GDURLLoadingSystem triggers invocation of the callback functions. Note that only HTTP and HTTPS requests are handled by the GDURLLoadingSystem.
  • The range of monitoring and control actions is different.

Call the GDSetRequestDataDelegate: function in the UIWebView(GDNET) category to set the delegate for a particular UIWebView instance. The delegate callbacks will be executed on the same thread in which the delegate was set.

The callbacks in this protocol utilize an NSURLRequest or NSMutableURLRequest object to represent the request to which the callback invocation relates.

See also:
NSURLRequest class reference on the apple.com developer website.
NSMutableURLRequest class reference on the apple.com developer website.
NSURLConnectionDataDelegate protocol reference on the apple.com developer website.
UIWebViewDelegate protocol reference on the apple.com developer website.

Member Function Documentation

- (BOOL) GDWillSendRequest: (NSURLRequest **)  request [optional]

This callback is invoked when a URL request is about to be sent. The location of a pointer to the request, i.e. a pointer to a pointer, is passed as a parameter.

The function that is invoked can replace the request by overwriting the pointer with the address of a request of its own. The replacement request will then be sent instead of the original request.

The function that is invoked can also cancel the request by doing either of the following:

  • Overwriting the pointer with nil.
  • Returning NO.
Parameters:
requestlocation of a pointer to an NSURLRequest that contains the request.
Returns:
YES to send the request, original or replacement.
NO to cancel the request.
- (void) GDRequest: (NSURLRequest *)  request
didReceiveResponse: (NSURLResponse *)  response 
[optional]

This callback is invoked when the initial part of a response has been received.

The details that have been received are made available in an NSURLResponse object. For details of what information is available and how to access it, see the NSURLRequest class reference on the apple.com developer website.

The details passed to this callback may include an expected content length of the response data. This will be the transport content length, and may be different to the length of the data received by subsequent GDRequest:didReceiveData: invocations if compression has been used.

This callback will be invoked once for every request that receives a response.

Parameters:
requestNSURLRequest representing the request for which the initial part of the response has been received.
responseNSURLResponse representing the response.
- (void) GDRequest: (NSURLRequest *)  request
didReceiveData: (NSData *)  data 
[optional]

This callback is invoked whenever response data is received.

The received data is made available in an NSData object. For details of how to read it, see the NSData class reference on the apple.com developer website.

The response data may have been uncompressed after transport and its final length may be different to the expected length when GDRequest:didReceiveResponse: was invoked.

The response data for a single request may be received in multiple chunks, in which case this callback will be invoked multiple times. This callback won't be invoked for responses that include no data.

Parameters:
requestNSURLRequest representing the request for which response data has been received.
dataNSData containing the received data.
- (void) GDRequest: (NSURLRequest *)  request
didFailWithError: (NSError *)  error 
[optional]

This callback is invoked when a URL request sent by the associated UIWebView instance fails to send, or receives an incomplete response.

Invocation of this callback notifies the application that page loading has stopped and cannot be resumed. The application would have to reload the page from the start, after the error condition had been resolved.

Details of the error condition are made available in an NSError object. For details of how to access its attributes, see the NSError class reference on the apple.com developer website.

Implementing this callback has the same effect as implementing the GDRequest:shouldContinueAfterFailWithError: callback as a function that always returns NO.

Parameters:
requestNSURLRequest representing the request that has failed.
errorNSError object describing the error condition.
- (BOOL) GDRequest: (NSMutableURLRequest *)  request
shouldContinueAfterFailWithError: (NSError *)  error 
[optional]

This callback is invoked when a URL request sent by the associated UIWebView instance fails to send, or receives an incomplete response. The function that is invoked can select to continue loading the page, possibly with a modified request, or can select to stop loading the page.

Details of the error condition are made available in an NSError object. For details of how to access its attributes, see the NSError class reference on the apple.com developer website.

The function that is invoked should determine whether the error can be resolved. Resolution of the error can include modifying the request, which is made available as an NSMutableURLRequest object.

If the invoked function determines that the error can be resolved, then the function should return YES. If the error cannot be resolved, then the function should return NO instead.

If the callback returns YES, then the request, which could have been modified, is tried again. The loading of other resources associated with the same page continues without disruption.

If the callback returns NO, the request will not be retried. Any pending requests associated with the same page will be cancelled and the loading of resources will stop.

If this callback is implemented then the GDRequest:didFailWithError: callback is never invoked.

Parameters:
requestNSMutableURLRequest object that contains the request that is failing. The object can be modified by the callback.
errorNSError object describing the error condition.
Returns:
YES to send the request again and continue loading the page.
NO to stop loading the page.
- (void) GDRequestDidFinishLoading: (NSURLRequest *)  request [optional]

This callback is invoked when a URL request from the associated UIWebView instance completes without errors.

This callback will be invoked once for every request that completes without errors, including requests whose responses have no data.

Parameters:
requestNSURLRequest representing the request that has completed.

The documentation for this protocol was generated from the following file: