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 |
Overview
An NSURLConnection object provides support to perform the loading of a URL request. The interface for NSURLConnection is sparse, providing only the controls to start and cancel asynchronous loads of a URL request.
NSURLConnection’s delegate methods—defined by the NSURLConnectionDelegate Protocol protocol—allow an object to receive informational callbacks about the asynchronous load of a URL request. Other delegate methods provide facilities that allow the delegate to customize the process of performing an asynchronous URL load. These delegate methods are called on the thread that started the asynchronous load operation for the associated NSURLConnection object.
NSURLConnection has a convenience class method, sendSynchronousRequest:returningResponse:error:, to load a URL request synchronously.
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 two formal protocols: NSURLConnectionDelegate Protocolc and NSURLConnectionDownloadDelegate protocol.
In order to use the NSURLConnectionDelegate Protocol protocol you must write a class that conforms to the protocol. The protocol primarily is used for credential handling, but it also handles connection completion. Because it handles connection failure during the download, the protocol typically must be implemented.
The NSURLConnectionDownloadDelegate protocol provides the data as it is downloaded, support for download continuation from interrupted downloads, and provides notification that the download is completed.
Tasks
Preflighting a Connection Request
Connection URL Information
Loading Data Synchronously
Loading Data Asynchronously
-
+ connectionWithRequest:delegate: -
– initWithRequest:delegate: -
– initWithRequest:delegate:startImmediately: -
+ sendAsynchronousRequest:queue:completionHandler: -
– start
Stopping a Connection
Scheduling Delegate Messages
Class Methods
canHandleRequest:
Returns whether a request can be handled based on a preflight evaluation.
Parameters
- request
The request to evaluate. When created, an NSURLConnection performs a deep-copy of the request.
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.
See Also
Declared In
NSURLConnection.hconnectionWithRequest:delegate:
Creates and returns an initialized URL connection and begins to load the data for the URL request.
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 delegate will receive delegate messages as the load progresses. Messages to the delegate will be sent on the thread that calls 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.
See Also
Declared In
NSURLConnection.hsendAsynchronousRequest:queue:completionHandler:
Loads the data for a URL request and executes a handler block on an operation queue when the request completes or fails.
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.
Availability
- Available in OS X v10.7 and later.
Declared In
NSURLConnection.hsendSynchronousRequest:returningResponse:error:
Performs a synchronous load of the specified URL request.
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.
Declared In
NSURLConnection.hInstance Methods
cancel
Cancels an asynchronous load of a request.
Discussion
After this method is called, the connection’s delegate no longer receives any messages for the connection. If you want to reattempt the connection, you should create a new connection object.
Availability
- Available in OS X v10.2 and later.
Declared In
NSURLConnection.hcurrentRequest
Returns the current connection request.
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.
See Also
Declared In
NSURLConnection.hinitWithRequest:delegate:
Returns an initialized URL connection and begins to load the data for the URL request.
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 delegate will receive delegate messages as the load progresses. Messages to the delegate will be sent on the thread that calls 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.hinitWithRequest:delegate:startImmediately:
Returns an initialized URL connection and begins to load the data for the URL request, if specified.
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 delegate receives delegate messages as the load progresses.
- startImmediately
YESif the connection should being loading data immediately, otherwiseNO. If you passNO, 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 callingscheduleInRunLoop: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.horiginalRequest
Returns a deep copy of the original connection request.
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.
See Also
Declared In
NSURLConnection.hscheduleInRunLoop:forMode:
Determines the run loop and mode that the connection uses to send messages to its delegate.
Parameters
- aRunLoop
The NSRunloop instance to use for delegate messages.
- mode
The mode in which to supply delegate messages.
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 messages with both this method and the setDelegateQueue: method.
Availability
- Available in OS X v10.5 and later.
Declared In
NSURLConnection.hsetDelegateQueue:
Determines the operation queue that is used to send messages to the connection’s delegate.
Parameters
- queue
The operation queue to use for delegate messages.
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 messages with both this method and the scheduleInRunLoop:forMode: method.
Availability
- Available in OS X v10.7 and later.
Declared In
NSURLConnection.hstart
Causes the connection to begin loading data, if it has not already.
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.hunscheduleFromRunLoop:forMode:
Causes the connection to stop sending delegate messages using the specified run loop and 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© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)