• BlackBerry Dynamics
  • Runtime library for iOS applications
  • 7.1.0.193
<GDURLRequestConnectionDelegate> Protocol Reference

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

#import <GDURLRequestConnectionDelegate.h>

Inherits <NSObject>.

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:

  • Respond to a certificate authentication challenge.
  • Block a connection.
  • Specify whether a connection will be routed direct to the Internet or via the BlackBerry Dynamics proxy infrastructure.
  • Confirm that a connection was made, and confirm its routing.

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

  • Custom verification of electronic certificates for Secure Socket Layer or Transport Layer Security (SSL/TLS) connections.
  • Mutual authentication of electronic certificates for SSL/TLS connections.
  • Finer control over routing and filtering than is offered by the BlackBerry Dynamics management console client connection configuration.

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.

Instance Methods

(BOOL) - GDRequest:willConnectVia:
 Invoked before a request is sent. More...
 
(void) - GDRequest:didConnectVia:
 Invoked after a request has been sent. More...
 
(void) - GDRequest:willSendRequestForAuthenticationChallenge:
 Invoked when authentication is requested. More...
 

Method Documentation

◆ GDRequest:willConnectVia:

- (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.

◆ GDRequest:didConnectVia:

- (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.

◆ GDRequest:willSendRequestForAuthenticationChallenge:

- (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: