Brief Intro to URL Handling of Foundation Framework (Examples: Downloading from a URL)

URL Handling

The URL handling classes are used for interacting with URLs and communicating with resources using standard Internet protocols (ftp, http, https, local files). The classes provide the following functionality:

• URL loading
• Cache management
• Authentication and credentials management
• Cookie management
• Protocol support

These classes also support proxy servers and SOCKET Secure (SOCKS) gateways per the user’s system preferences.

URL Loading

NSURL objects are used to manage URLs and the resources they refer to. The class includes methods for creating and initializing NSURL objects, querying a URL, and accessing the components of a URL (e.g., host, port, etc.). NSURL also provides methods for working with bookmark data. Abookmark is a persistent reference to the location of a file. It is a valuable tool for locating files because it can be used to re-create a URL to a file, even if the file is moved or renamed. The following code fragment demonstrates the use of the NSURL APIs to create an NSURLobject and access its components.

NSURL *url = [NSURL URLWithString:@"http://www.apress.com:80
"];
NSLog(@"URL: scheme %@, host %@, port %@", url.scheme, url.host, url.port);

The classes NSURLRequest and NSMutableURLRequest are used to represent a URL load request. NSURLRequest is independent of the network protocol and URL scheme. The class includes methods to create and initialize a URL request, and to retrieve request properties.NSMutableURLRequest is a subclass of NSURLRequest that provides methods that enable you to change a URL and its component parts. The following statement creates a mutable URL request, and then uses thesetHTTPMethod: method to set the HTTP request method value.

NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:
                            [NSURL URLWithString:@"http://www.apress.com:80
"]];
[req setHTTPMethod:@"GET"];

NSURLResponse and NSHTTPURLResponse classes are used to represent the response returned by a URL request. An NSURLConnection object is created by either an object that performs a synchronous load of a URL request (sendSynchronousRequest:returningResponse:error:) or objects that conform to the NSURLConnectionDataDelegate protocol. The NSHTTPURLResponse class is a subclass of NSURLResponse that provides methods for accessing HTTP-specific information returned by a URL request.

The NSURLConnection and NSURLDownload classes are used to download the contents of a resource identified by a URL. NSURLConnectionsupports synchronous and asynchronous resource loading, starting and stopping a connection, and managing a delegate object used to control various aspects of a URL connection (i.e., cache management, authentication and credentials, protocol support, and cookie management). For asynchronous loading, a delegate object must be set. This object must conform to the NSURLConnectionDelegate protocol and thus implement, at a minimum, the following methods:

• connection:didReceiveData: (to retrieve data loaded)
• connection:didFailWithError: (to handle connection errors
• connection:didFinishLoading: (to perform processing after a connection has finished loading data)

Listing 11-13 demonstrates use of various URL loading APIs to synchronously load the data from a URL.

Listing 11-13.  Using NSURLConnection to Synchronously Load the Contents of a URL

NSURL *url = [NSURL URLWithString:@"http://www.apress.com/index.html
"];
NSURLRequest *request = [NSURLRequest requestWithURL:url];
NSURLResponse *response;
NSError *aerror;
NSData *data = [NSURLConnection sendSynchronousRequest:request
                                     returningResponse:&response
                                                 error:&aerror];
NSLog(@"Expected content length = %lld; loaded %lu bytes",
      [response expectedContentLength], [data length]);

As shown in Listing 11-13, the code creates an NSURL instance and then a corresponding NSURLRequest. It then creates a connection and loads the data using the NSURLConnectionsendSynchronousRequest:returningResponse:error: method. The result is returned in an NSData object.

The NSURLDownload class is used to asynchronously download the contents of a URL to a file. It includes methods to initialize a download (set request and delegate), set the destination path, resume a partial download, and cancel loading the request. The class also provides support for decoding files stored in the MacBinary, BinHex, and gzip formats. The delegate object must conform to theNSURLDownloadDelegate protocol and thus implement, at a minimum, the following methods:

• download:didFailWithError: (to handle connection errors)
• downloadDidFinish: (to perform processing after a connection has finished loading data)

The NSURLDownload class is available for use on the OS X platform only (i.e., this class is not available for the iOS platform).

Cache Management

The cache management classes (NSURLCache and NSCachedURLResponse) provide a cache memory for responses to URL requests. The NSURLCacheclass provides a general-purpose cache for URLs, whereas theNSCachedURLResponse encapsulates a URL response (NSURLResponseobject) and the data loaded from the URL (an NSData object). AnNSURLConnection delegate object implements theconnection:willCacheResponse: method, providing aNSCachedURLResponse object initialized with an NSURLCache, to manage caching. How this works is best illustrated by an example; so now you’ll create a program that uses the URL loading classes to download a resource. Let’s begin!

Downloading a Resource with the URL Loading APIs

In Xcode, create a new project by selecting New  Project . . . from the Xcode File menu. In the New Project Assistant pane create a command-line application. In the Project Options window, specifyNetConnector for the Product Name, choose Foundation for the Project Type, and select ARC memory management by selecting the Use Automatic Reference Counting check box. Specify the location in your file system where you want the project to be created (if necessary selectNew Folder and enter the name and location for the folder), uncheck the Source Control check box, and then click the Create button.

Now you’re going to create a class that downloads a URL resource using the URL loading APIs. Select New  File . . . from the Xcode File menu, select the Objective-C class template, and name the classNetConnector. Select the NetConnector folder for the files location and the NetConnector project as the target, and then click the Createbutton. Next, in the Xcode project navigator pane, select the resulting header file named NetConnector.h and update the interface, as shown in Listing 11-14.

Listing 11-14.  NetConnector Interface

#import <Foundation/Foundation.h>
#define HTTP_SCHEME       @"http"
#define CACHE_MEMORY_SIZE (4 * 1024 * 1024)

@interface NetConnector : NSObject <NSURLConnectionDelegate>

@property (readonly) BOOL finishedLoading;

- (id) initWithRequest:(NSURLRequest *)request;
- (void) reloadRequest;

@end

The NetConnector interface adopts the NSURLConnectionDelegateprotocol, thereby enabling it to asynchronously load data from anNSURLConnection instance. The property finishedLoading is used to indicate when the NSURLConnection instance is finished loading data. The initWithRequest: method initializes a NetConnector object and loads a URL using the input NSURLRequest. The reloadRequest method is used to reload the input NSURLRequest. Now select theNetConnector.m file and update the implementation, as shown inListing 11-15.

Listing 11-15.  NetConnector Implementation

#import "NetConnector.h"

// Extension to declare provide properties
@interface NetConnector()

@property NSURLRequest *request;
@property BOOL finishedLoading;
@property NSURLConnection *connector;
@property NSMutableData *receivedData;

@end

@implementation NetConnector

- (id) initWithRequest:(NSURLRequest *)request
{
  if ((self = [super init]))
  {
    _request = request;
    // Create URL cache with appropriate in-memory storage
    NSURLCache *URLCache = [[NSURLCache alloc] init];
    [URLCache setMemoryCapacity:CACHE_MEMORY_SIZE];
    [NSURLCache setSharedURLCache:URLCache];
    // Create connection and begin downloading data from resource
    _connector = [NSURLConnection connectionWithRequest:request delegate:self];
  }
  return self;
}

- (void) reloadRequest
{
  self.finishedLoading = NO;
  self.connector = [NSURLConnection connectionWithRequest:self.request
                                                 delegate:self];
}

#pragma mark -
#pragma mark Delegate methods

- (void)connection:(NSURLConnection *)connection
didReceiveResponse:(NSURLResponse *)response
{
  if (self.receivedData != nil)
  {
    [self.receivedData setLength:0];
  }
}

- (NSCachedURLResponse *)connection:(NSURLConnection *)connection
                  willCacheResponse:(NSCachedURLResponse *)cachedResponse
{
  NSURLResponse *response = [cachedResponse response];
  NSURL *url = [response URL];
  if ([[url scheme] isEqualTo:HTTP_SCHEME])
  {
    NSLog(@"Downloaded data, caching response");
    return cachedResponse;
  }
  else
  {
    NSLog(@"Downloaded data, not caching response");
    return nil;
  }
}

- (void)connection:(NSURLConnection*)connection didReceiveData:(NSData*)data
{
   if (self.receivedData != nil)
   {
     [self.receivedData appendData:data];
   }
   else
   {
     self.receivedData = [[NSMutableData alloc] initWithData:data];
   }
}

- (void)connectionDidFinishLoading:(NSURLConnection *)connection
{
  NSUInteger length = [self.receivedData length];
  NSLog(@"Downloaded %lu bytes from request %@", length, self.request);
  // Loaded data, set flag to exit run loop
  self.finishedLoading = YES;
}

- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error
{
  NSLog(@"Error loading request %@", [error localizedDescription]);
  self.finishedLoading = YES;
}

@end

OK, so I know that this is a lot of code, but don’t worry, you’ll take it one step at a time!. The file begins with a category extension that declares private properties used within the NetConnector implementation. The implementation defines both the methods declared by the interface and methods declared by the NSURLConnectionDelegate protocol. TheinitWithRequest: method assigns the input NSURLRequest to the private NetConnector request property, creates and initializes anNSURLCache instance for caching responses, and ends by creating anNSURLConnection object and starting the download of the URL. The following statements from Listing 11-15 create the cache, configure it with in-memory storage, and then set it to be the shared cache used with the connection.

NSURLCache *URLCache = [[NSURLCache alloc] init];
[URLCache setMemoryCapacity:CACHE_MEMORY_SIZE];
[NSURLCache setSharedURLCache:URLCache];

The reloadRequest method reloads the URL. It first resets thefinishedLoading flag, and then creates a new NSURLConnection object with the saved request and downloads the URL.

The remaining methods implemented here areNSURLConnectionDelegate protocol methods. Theconnection:didReceiveResponse: message is sent when a connection is able to send a response to the request. As shown in Listing 11-15, this method sets the receivedData object to a length of zero, thereby discarding data received from previous requests.

The connection:willCacheResponse: message is sent before a connection stores the response in the cache. This enables the method implementation to modify the response or prevent it from being cached. As shown in Listing 11-15, the method performs conditional logic that enables/disables caching of the response based on whether or not the scheme for the URL is http.

The connection:didReceiveData: message is sent as the data is received from the resource. This method may be called multiple times during a single request if the data is received incrementally. As shown inListing 11-15, the method appends the received data to thereceivedData object.

The connectionDidFinishLoading: message is sent when a connection has finished loading the data successfully. The method implementation here just logs a message to the output pane, indicating that the connection has finished loading the resource, and then sets thefinishedLoading flag used to exit the run loop.

Finally, the connection:didFailWithError: message is sent when a connection fails to load a request successfully. Here you just log a message to the output pane, indicating the error that occurred, and set the finishedLoading flag.

OK, now that you have implemented the NetConnector class, let’s use this to load a URL. In the Xcode project navigator, select the main.m file and update the main() function, as shown in Listing 11-16.

Listing 11-16.  NetConnector main( ) Function

#import <Foundation/Foundation.h>
#import "NetConnector.h"

#define INDEX_URL       @"http://www.wikipedia.com/index.html
"

int main(int argc, const char * argv[])
{
  @autoreleasepool
  {
    // Retrieve the current run loop
    NSRunLoop *loop = [NSRunLoop currentRunLoop];

    // Create the request with specified cache policy, then begin downloading!
    NSURLRequest *request = [NSURLRequest
                             requestWithURL:[NSURL URLWithString:INDEX_URL]
                                cachePolicy:NSURLRequestReturnCacheDataElseLoad
                            timeoutInterval:5];
    NetConnector *netConnect = [[NetConnector alloc] initWithRequest:request];
    // Loop until finished loading the resource (Note the empty statement!)
    while (!netConnect.finishedLoading &&
           [loop runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]);

    // Log the amount of memory being used by the cache
    NSLog(@"Cache memory usage = %lu bytes", [[NSURLCache sharedURLCache]
                                              currentMemoryUsage]);

    // Reload data from request, this time it will be retrieved from the cache!
    [netConnect reloadRequest];
    while (!netConnect.finishedLoading &&
           [loop runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]);
    // Zero out cache
    [[NSURLCache sharedURLCache] removeAllCachedResponses];
  }
  return 0;
}

The main() function begins by retrieving the current run loop, required for asynchronous URL loading with NSURLConnection objects. Next, anNSURLRequest instance is created using the convenience constructorrequestWithURL:cachePolicy:timeoutInterval:. This constructor enables you to select the cache policy for the request. The policyNSURLRequestReturnCacheDataElseLoad specifies that a cache value should be used (even if out of date) if available; otherwise, the data should be loaded from the resource. Note that if a URL does not support caching, the data will not be loaded from the cache, even if the policy specifies otherwise. A NetConnector instance is then created using the request and its NSURLConnection object begins downloading the resource. The next statement is a loop used to keep the application running until the connection has finished loading the resource.

while (!netConnect.finishedLoading &&
       [loop runMode:NSDefaultRunLoopMode beforeDate:[NSDate distantFuture]]);

Looks familiar, doesn’t it? This loop is identical to the one used for the Bonjour service browser program that you implemented earlier in this chapter. It runs the loop, receiving events from its input sources and executing any corresponding delegate methods, until the connection has finished loading the resource. The next statement logs the cache memory usage to the output pane, enabling us to view cache utilization. Then you reload the request. As shown in Listing 11-16, the next set of statements reloads the URL. As the data is already stored in the cache and the cache policy specifies that a cache value should be used, it is immediately retrieved without being loaded from the URL. Finally, the in-memory cache is zeroed out, thereby freeing this memory. Now when you compile and run the NetConnector program, you should observe the messages in the output pane, as shown in Figure 11-2

Figure 11-2. NetConnector program output

.

As shown in the output pane, the response is cached after the data is downloaded. The total amount of data is then logged to the console, along with the URL of the request. Next, the cache memory utilization is output. This is identical to the data downloaded. The request is then reloaded. Because the response is already in the cache, it is retrieved from there (notice that the delegate methodconnection:willCacheResponse: is not invoked). OK, that was pretty involved, wasn’t it? Well, you now have a pretty good handle on the use of the URL loading APIs to asynchronously download a URL. Once you’re ready, let’s move on and look into handling authentication challenges when trying to load a resource.

Authentication and Credentials Management

The authentication and credentials classes ( NSURLProtectionSpace,NSURLCredentialStorage, NSURLCredential,NSURLAuthenticationChallenge, andNSURLAuthenticationChallengeSender ) provide support for authenticating users requesting access to protected URLs. A resource that requires authentication requests credentials from a client attempting to load the resource. The Foundation FrameworkNSURLAuthenticationChallenge class encapsulates a challenge from a server that requires authentication from the client. NSURLCredentialrepresents an authentication credential returned by a user in response to an authentication challenge. The delegate protocols for NSURLConnectionand NSURLDownload instances are sent messages when a connection request issues an authentication challenge. The corresponding methods should be implemented to return the appropriate credential.

For the NSURLConnectionDelegate protocol, the messageconnection:willSendRequestForAuthenticationChallenge: should be implemented to return the appropriate credential. An example implementation of this method for the NetConnector program is shown inListing 11-17.

Listing 11-17.  Handling Authentication Challenges

- (void)connection:(NSURLConnection *)connection
willSendRequestForAuthenticationChallenge:(NSURLAuthenticationChallenge *)challenge
{
  NSURLCredential *credential =
    [NSURLCredential credentialWithUser:@"TestUser"
                               password:@"TestPassword"
                            persistence:NSURLCredentialPersistenceForSession];
  [[challenge sender] useCredential:credential
         forAuthenticationChallenge:challenge];
}

As shown in Listing 11-17, the method creates a credential with a user name of TestUser and a password of TestPassword;. TheuseCredential:forAuthenticationChallenge: message uses this credential to respond to an authentication challenge for the connection.

Cookie Management

The Foundation Framework classes NSHTTPCookie andNSHTTPCookieStorage facilitate the creation and management of HTTP cookies, which are used to provide persistent storage of data across URL requests. An NSHTTPCookie instance represents a cookie, andNSHTTPCookieStorage is a singleton object used to manage cookies. For OS X applications, cookies are shared and kept in sync across processes.Session cookies are local to a single process and not shared between programs. The NSHTTPCookie class provides methods to create cookies, convert cookies to request headers, and retrieve cookie properties. TheNSHTTPCookieStorage class provides methods for retrieving the shared cookie storage instance, managing the cookie accept policy, and managing (i.e., adding, removing, retrieving) cookies.

Protocol Support

The Foundation Framework classes NSURLProtocol andNSURLProtocolClient enable the creation of custom protocols for loading data from a URL. NSURLProtocol is an abstract class that provides the basic structure to perform protocol-specific URL loading. It includes methods for creating NSURLProtocol objects, registering/unregistering protocol classes, request management, retrieving protocol attributes, and starting/stopping downloads.NSURLProtocolClient is a protocol used by NSURLProtocol subclasses to communicate with the URL loading system.