NSURLConnection Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.2 with Safari 1.0 installed.
Available in Mac OS X v10.2.7 and later.
Companion guide
Declared in
NSURLConnection.h
Related sample code

Overview

An NSURLConnection object lets you load the contents of a URL by providing a URL request object. The interface for NSURLConnection is sparse, providing only the controls to start and cancel asynchronous loads of a URL request. You perform most of your configuration on the URL request object itself.

The NSURLConnection class provides convenience class methods to load URL requests both asynchronously using a callback block and synchronously.

For greater control, you can create a URL connection object with a delegate object that conforms to the NSURLConnectionDelegate and NSURLConnectionDataDelegate protocols. The connection calls methods on that delegate to provide you with progress and status as the URL request is loaded asynchronously. The connection also calls delegate methods to let you override the connection’s default behavior (for example, specifying how a particular redirect should be handled). These delegate methods are called on the thread that initiated the asynchronous load operation.

For more information about errors, see the NSURLError.h header, Foundation Constants Reference, and URL Loading System Error Codes in Error Handling Programming Guide.

NSURLConnection Protocols

The NSURLConnection class works in tandem with three formal protocols: NSURLConnectionDelegate, NSURLConnectionDataDelegate, and NSURLConnectionDownloadDelegate. To use these protocols, you write a class that conforms to them and implement any methods that are appropriate, then provide an instance of that class as the delegate when you create a connection object.

The NSURLConnectionDelegate protocol is primarily used for credential handling, but also handles connection completion. Because it handles connection failure during data transfers, all connection delegates must typically implement this protocol.

In addition, unless you’re using Newsstand Kit, your delegate must also conform to the NSURLConnectionDataDelegate protocol, because this protocol provides methods that the NSURLConnection class calls with progress information during an upload, with fragments of the response data during a download, and to provide a new upload body stream if the server’s response necessitates a second connection attempt—for example, if NSURLConnection must retry the request with different credentials.

Finally, if you’re using Newsstand Kit, your delegate can conform to the NSURLConnectionDownloadDelegate protocol. This protocol provides support for continuing interrupted file downloads and receiving a notification whenever a download finishes. This protocol is solely for use with NSURLConnection objects created using Newsstand Kit’s downloadWithDelegate: method.

Tasks

Preflighting a Connection Request

Connection URL Information

Loading Data Synchronously

Loading Data Asynchronously

Stopping a Connection

Scheduling Delegate Method Calls

Class Methods

canHandleRequest:

Returns whether a request can be handled based on a preflight evaluation.

+ (BOOL)canHandleRequest:(NSURLRequest *)request
Parameters
request

The request to evaluate.

Return Value

YES if a preflight operation determines that a connection with request can be created and the associated I/O can be started, NO otherwise.

Discussion

The result of this method is valid as long as no NSURLProtocol classes are registered or unregistered, and request remains unchanged. Applications should be prepared to handle failures even if they have performed request preflighting by calling this method.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLConnection.h

connectionWithRequest:delegate:

Creates and returns an initialized URL connection and begins to load the data for the URL request.

+ (NSURLConnection *)connectionWithRequest:(NSURLRequest *)request delegate:(id < NSURLConnectionDelegate >)delegate
Parameters
request

The URL request to load. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

delegate

The delegate object for the connection. The connection calls methods on this delegate as the load progresses. Delegate methods are called on the same thread that called this method. For the connection to work correctly, the calling thread’s run loop must be operating in the default run loop mode.

Return Value

The URL connection for the URL request. Returns nil if a connection can't be created.

Special Considerations

During the download the connection maintains a strong reference to the delegate. It releases that strong reference when the connection finishes loading, fails, or is canceled.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLConnection.h

sendAsynchronousRequest:queue:completionHandler:

Loads the data for a URL request and executes a handler block on an operation queue when the request completes or fails.

+ (void)sendAsynchronousRequest:(NSURLRequest *)request queue:(NSOperationQueue *)queue completionHandler:(void (^)(NSURLResponse*, NSData*, NSError*))handler
Parameters
request

The URL request to load. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

queue

The operation queue to which the handler block is dispatched when the request completes or failed.

handler

The handler block to execute.

Discussion

If the request completes successfully, the data parameter of the handler block contains the resource data, and the error parameter is nil. If the request fails, the data parameter is nil and the error parameter contain information about the failure.

If authentication is required in order to download the request, the required credentials must be specified as part of the URL. If authentication fails, or credentials are missing, the connection will attempt to continue without credentials.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSURLConnection.h

sendSynchronousRequest:returningResponse:error:

Performs a synchronous load of the specified URL request.

+ (NSData *)sendSynchronousRequest:(NSURLRequest *)request returningResponse:(NSURLResponse **)response error:(NSError **)error
Parameters
request

The URL request to load. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

response

Out parameter for the URL response returned by the server.

error

Out parameter used if an error occurs while processing the request. May be NULL.

Return Value

The downloaded data for the URL request. Returns nil if a connection could not be created or if the download fails.

Discussion

A synchronous load is built on top of the asynchronous loading code made available by the class. The calling thread is blocked while the asynchronous loading system performs the URL load on a thread spawned specifically for this load request. No special threading or run loop configuration is necessary in the calling thread in order to perform a synchronous load.

If authentication is required in order to download the request, the required credentials must be specified as part of the URL. If authentication fails, or credentials are missing, the connection will attempt to continue without credentials.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSURLConnection.h

Instance Methods

cancel

Cancels an asynchronous load of a request.

- (void)cancel
Discussion

After this method is called, the connection makes no further delegate method calls. If you want to reattempt the connection, you should create a new connection object.

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSURLConnection.h

currentRequest

Returns the current connection request.

- (NSURLRequest *)currentRequest
Return Value

Returns the current—possibly modified—connection request.

Discussion

As the connection performs the load, the request may change as a result of protocol canonicalization or due to following redirects.

This method is be used to retrieve the current value.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSURLConnection.h

initWithRequest:delegate:

Returns an initialized URL connection and begins to load the data for the URL request.

- (id)initWithRequest:(NSURLRequest *)request delegate:(id < NSURLConnectionDelegate >)delegate
Parameters
request

The URL request to load. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

delegate

The delegate object for the connection. The connection calls methods on this delegate as the load progresses. Delegate methods are called on the same thread that called this method. By default, for the connection to work correctly, the calling thread’s run loop must be operating in the default run loop mode. See scheduleInRunLoop:forMode: to change the run loop and mode.

Return Value

The URL connection for the URL request. Returns nil if a connection can't be initialized.

Discussion

This is equivalent to calling initWithRequest:delegate:startImmediately: and passing YES for startImmediately.

Special Considerations

During the download the connection maintains a strong reference to the delegate. It releases that strong reference when the connection finishes loading, fails, or is canceled.

Availability
  • Available in OS X v10.2 and later.
Declared In
NSURLConnection.h

initWithRequest:delegate:startImmediately:

Returns an initialized URL connection and begins to load the data for the URL request, if specified.

- (id)initWithRequest:(NSURLRequest *)request delegate:(id < NSURLConnectionDelegate >)delegate startImmediately:(BOOL)startImmediately
Parameters
request

The URL request to load. The request object is deep-copied as part of the initialization process. Changes made to request after this method returns do not affect the request that is used for the loading process.

delegate

The delegate object for the connection. The connection calls methods on this delegate as the load progresses.

startImmediately

YES if the connection should begin loading data immediately, otherwise NO. If you pass NO, the connection is not scheduled with a run loop. You can then schedule the connection in the run loop and mode of your choice by calling scheduleInRunLoop:forMode:.

Return Value

The URL connection for the URL request. Returns nil if a connection can't be initialized.

Special Considerations

During the download the connection maintains a strong reference to the delegate. It releases that strong reference when the connection finishes loading, fails, or is canceled.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURLConnection.h

originalRequest

Returns a deep copy of the original connection request.

- (NSURLRequest *)originalRequest
Return Value

Returns a deep copy of the original connection request.

Discussion

As the connection performs the load, this request may change as a result of protocol canonicalization or due to following redirects. The currentRequest method can be used to retrieve this value.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSURLConnection.h

scheduleInRunLoop:forMode:

Determines the run loop and mode that the connection uses to call methods on its delegate.

- (void)scheduleInRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
Parameters
aRunLoop

The NSRunLoop instance to use when calling delegate methods.

mode

The mode in which to call delegate methods.

Discussion

By default, a connection is scheduled on the current thread in the default mode when it is created. If you create a connection with the initWithRequest:delegate:startImmediately: method and provide NO for the startImmediately parameter, you can schedule the connection on a different run loop or mode before starting it with the start method. You can schedule a connection on multiple run loops and modes, or on the same run loop in multiple modes.

You cannot reschedule a connection after it has started.

It is an error to schedule delegate method calls with both this method and the setDelegateQueue: method.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURLConnection.h

setDelegateQueue:

Determines the operation queue that is used to call methods on the connection’s delegate.

- (void)setDelegateQueue:(NSOperationQueue *)queue
Parameters
queue

The operation queue to use when calling delegate methods.

Discussion

By default, a connection is scheduled on the current thread in the default mode when it is created. If you create a connection with the initWithRequest:delegate:startImmediately: method and provide NO for the startImmediately parameter, you can instead schedule the connection on an operation queue before starting it with the start method.

You cannot reschedule a connection after it has started.

It is an error to schedule delegate method calls with both this method and the scheduleInRunLoop:forMode: method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSURLConnection.h

start

Causes the connection to begin loading data, if it has not already.

- (void)start
Discussion

Calling this method is necessary only if you create a connection with the initWithRequest:delegate:startImmediately: method and provide NO for the startImmediately parameter. If you don’t schedule the connection in a run loop or an operation queue before calling this method, the connection is scheduled in the current run loop in the default mode.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURLConnection.h

unscheduleFromRunLoop:forMode:

Causes the connection to stop calling delegate methods in the specified run loop and mode.

- (void)unscheduleFromRunLoop:(NSRunLoop *)aRunLoop forMode:(NSString *)mode
Parameters
aRunLoop

The run loop instance to unschedule.

mode

The mode to unschedule.

Discussion

By default, a connection is scheduled on the current thread in the default mode when it is created. If you create a connection with the initWithRequest:delegate:startImmediately: method and provide NO for the startImmediately parameter, you can instead schedule connection on a different run loop or mode before starting it with the start method. You can schedule a connection on multiple run loops and modes, or on the same run loop in multiple modes. Use this method to unschedule the connection from an undesired run loop and mode before starting the connection.

You cannot reschedule a connection after it has started. It is not necessary to unschedule a connection after it has finished.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSURLConnection.h