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

NSMutableURLRequest(GDNET) Class Reference

NSMutableURLRequest category with additional features. More...

#import <NSMutableURLRequest+GDNET.h>

List of all members.

Public Member Functions


Detailed Description

This class is a category of the Foundation NSMutableURLRequest class that can be used when the BlackBerry Dynamics proxy infrastructure is in use via the URL Loading System (see GDURLLoadingSystem). This class provides additional features to the default request class.

The additional features enable enhanced control over authentication by applications that use the UIWebView class.

This documentation includes only additional operations that are not part of the default NSMutableURLRequest API.

See also:
NSMutableURLRequest class reference on the apple.com developer website.
UIWebView class reference on the apple.com developer website.
WebKit Objective-C Programming Guide on the apple.com developer website.

Authentication error-handling

Authentication errors may be encountered when this class is in use. For example, the combination of user name and password may be rejected by the server that receives the HTTP request.

When an authentication error is encountered, a call to UIWebViewDelegate::didFailLoadWithError:(NSError *)error will be made. The code used to indicate that the failure condition is an authentication error is NSURLErrorUserAuthenticationRequired.

The NSError object that is passed will have an associated NSDictionary object, which can be accessed via the NSError::userInfo accessor. In the NSDictionary, with the key GDURLAuthenticationParameters, there will be an NSArray containing the authentication objects associated with the request.

The structure of the authentication parameters NSArray will be as follows.

 { (NSURLProtectionSpace*) protectionSpace, (NSURLCredential*) credential, nil }

Note that credential may be nil.

The following example shows how to access the array and credentials.

 - (void)webView:(UIWebView *)webView didFailLoadWithError:(NSError *)error {

   if( NSURLErrorUserAuthenticationRequired == [error code] ) {
       NSDictionary* dict = [error userInfo];
       NSArray* credentialArray = [dict objectForKey:GDURLAuthenticationParameters];
       if(credentialArray){
           NSURLProtectionSpace* protSpace = nil;
           NSURLCredential* cred = nil;
           if([credentialArray count] > 0){
               protSpace = [credentialArray objectAtIndex:0];
               // we may also have a credential
               if([credentialArray count] > 1){
                   cred = [credentialArray objectAtIndex:1];
               }
           }
           // Do something with the credentials here
       }
   }

   // Handling for other error conditions goes here
 }

Member Function Documentation

- (BOOL) failOnAuthorizationChallenge

Call this function to force a failure in the URL request's associated UIWebView object when an authentication challenge is received.

Calling this function sets the following behavior. When the associated URL request receives an HTTP 401 "Unauthorized" response, or an HTTP 407 "Proxy Authentication Required" response, the UIWebView will fail with UIWebViewDelegate::didFailLoadWithError.

The application should handle the failure by taking appropriate action, such as resubmitting the request with authorization credentials.

By default, UIWebView does not fail when either of these statuses is received in the related request.

This function can only be used when the BlackBerry Dynamics proxy infrastructure is in use via the URL Loading System, and a UIWebView control is in use.

- (BOOL) setAuthorizationCredentials: (NSURLCredential *)  credentials
withProtectionSpace: (NSURLProtectionSpace *)  space 

Call this function to set the authorization credentials that will be sent if the response to the URL request contains an authentication challenge. This function can be used with requests that are associated with a UIWebView object.

Authorization credentials would usually be sent in response to receiving NSURLConnectionDelegate didReceiveAuthenticationChallenge.

Server and proxy credentials can both be set, in separate calls to the function.

This function can only be used when the BlackBerry Dynamics proxy infrastructure is in use via the URL Loading System, and a UIWebView control is in use.

Parameters:
credentialsNSURLCredential containing the username and password.
spaceNSURLProtectionSpace containing the following:
Hostname or address,
Port number,
Authentication method,
Proxy indicator.
- (BOOL) undoPriorTrustDecision

Call this function to cancel the persistence of a server trust credential. Persistence must have been set via the NSURLCredential(GDNET) gdPersistence property, so that the credential is being managed by the BlackBerry Dynamics runtime.

Credentials managed by the BlackBerry Dynamics runtime are stored persistently in the BlackBerry Dynamics secure store on the mobile device. The URL of the NSMutableURLRequest object on which this method is called will be used by the runtime to identify the server certificate.

Returns:
YES if a persistent server trust credential was found and cancelled.
NO otherwise.
See also:
The class reference of the NSURLCredential(GDNET) category for the programming interface and implications of setting persistence.

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