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

<GDURLRequestConnectionDelegate> Protocol Reference

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

#import <GDURLRequestConnectionDelegate.h>

List of all members.

Public Member Functions


Detailed Description

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

The callbacks in this protocol enable the application to:

Implement this protocol if any of the following is required by the application:

But note that this protocol doesn't enable routing to an application server that is behind the enterprise firewall and that hasn't been configured in the enterprise management console.

Call the GDSetRequestConnectionDelegate: 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 object to represent the request to which the callback invocation relates. For details of how to access its attributes, see the NSURLRequest class reference on the apple.com developer website.

See also:
System administration tasks for application developers.

Member Function Documentation

- (BOOL) GDRequest: (NSURLRequest *)  request
willConnectVia: (NSString **)  route 
[optional]

This callback is invoked when a request is about to be sent or a connection is about to be established. A specifier for the routing that is going to be used for the connection is passed as a parameter.

The specifier is passed as the location of a pointer to NSString, i.e. a pointer to a pointer. The function that is invoked can check the routing specified by comparing the pointed-to value with the BlackBerry Dynamics URL Connection Management Constants.

The function that is invoked can specify a different route by overwriting the pointer with the address of an NSString of its own. The value of the NSString must be the same as one of the connection management constants.

The function that is invoked can also block the connection from being established by doing either of the following:

  • Overwriting the pointer with nil.
  • Returning NO.
Parameters:
requestNSURLRequest representing the request that will be sent.
routelocation of a pointer to NSString specifying the routing of the request. The value will be one of the BlackBerry Dynamics URL Connection Management Constants.
Returns:
YES to allow the request to be sent, via the original or changed route.
NO to block the request.
- (void) GDRequest: (NSURLRequest *)  request
didConnectVia: (NSString *)  route 
[optional]

This callback is invoked after a URL request has been sent or a new connection was established. A specifier for the routing that was used for the request is passed as a parameter.

Parameters:
requestNSURLRequest representing the request that was sent.
routeNSString specifying the route of the connection. The value will be one of the BlackBerry Dynamics URL Connection Management Constants.
- (void) GDRequest: (NSURLRequest *)  request
willSendRequestForAuthenticationChallenge: (NSURLAuthenticationChallenge *)  challenge 
[optional]

This callback is invoked during SSL/TLS connection negotiation and when HTTP resource authentication is required, once for each authentication challenge. There are six types of challenge, all of which could occur during loading of a document:

  • An NSURLAuthenticationMethodServerTrust challenge occurs when a host certificate is received and requires verification. Note that verification isn't required from the application code if the BlackBerry Dynamics runtime was able to verify the host certificate itself. In that case, this callback isn't invoked.
  • An NSURLAuthenticationMethodClientCertificate challenge occurs when the host requests a client certificate for mutual certificate authentication.
  • An NSURLAuthenticationMethodNegotiate challenge occurs when access to the requested resource requires Kerberos or NTLM authentication.
  • An NSURLAuthenticationMethodNTLM challenge occurs when access to the requested resource requires NTLM authentication.
  • An NSURLAuthenticationMethodHTTPDigest challenge occurs when access to the requested resource requires HTTP Digest authentication.
  • An NSURLAuthenticationMethodHTTPBasic challenge occurs when access to the requested resource requires HTTP Basic authentication.

The type of the authentication challenge can be determined from the challenge parameter. See the NSURLAuthenticationChallenge class reference on the apple.com developer website.

The function that is invoked can respond to the challenge by calling the NSURLAuthenticationChallengeSender methods on the object in the challenge parameter. For details of the programming interface, see the NSURLAuthenticationChallengeSender protocol reference on the apple.com developer website. The NSURLAuthenticationChallengeSender methods must be used within one second of the invocation or no response will be assumed.

The handling of a challenge can include the creation of a credential object, which could utilize the NSURLCredential(GDNET) category programming interface.

If host certificate verification is required and the application doesn't respond, then the connection won't be established. If a client certificate is requested and the application doesn't respond, then the connection might or might not be established, depending only on the configuration of the host server. If an HTTP resource requires authentication and the application doesn't respond, the request will eventually fail with a time out.

Parameters:
requestNSURLRequest representing the request that will be sent if SSL/TLS negotiation succeeds.
challengeNSURLAuthenticationChallenge object that:

  • Contains the challenge details.
  • Implements the NSURLAuthenticationChallengeSender protocol.

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