# NSURLSession documentation

hugo@algoriddim.com
Generated at 2025-12-02 21:52:00 +0000
2017-2024 Free Software Foundation, Inc.
Software documentation for the NSURLSession class
Foundation/NSURLSession.h
NSURLSession is a replacement API for NSURLConnection. It provides options that affect the policy of, and various aspects of the mechanism by which NSURLRequest objects are retrieved from the network.
An NSURLSession may be bound to a delegate object. The delegate is invoked for certain events during the lifetime of a session. NSURLSession instances are threadsafe. An NSURLSession creates NSURLSessionTask objects which represent the action of a resource being loaded. NSURLSessionTask objects are always created in a suspended state and must be sent the -resume message before they will execute. Subclasses of NSURLSessionTask are used to syntactically differentiate between data and file downloads. An NSURLSessionDataTask receives the resource as a series of calls to the URLSession:dataTask:didReceiveData: delegate method. This is type of task most commonly associated with retrieving objects for immediate parsing by the consumer.
sessionWithConfiguration:
configuration
Description forthcoming.
sessionWithConfiguration:
configuration
delegate:
delegate
delegateQueue:
queue
Customization of NSURLSession occurs during creation of a new session. If you do specify a delegate, the delegate will be retained until after the delegate has been sent the URLSession:didBecomeInvalidWithError: message.
sharedSession
Description forthcoming.
configuration
The configuration object used to create the session. A copy of the configuration object is made. Changes to the configuration object after the session is created have no effect.
dataTaskWithRequest:
request
Creates a data task with the given request. The request may have a body stream.
dataTaskWithURL:
url
Creates a data task to retrieve the contents of the given URL.
delegate
The delegate for the session. This is the object to which delegate messages will be sent. The session keeps a strong reference to the delegate.
delegateQueue
This serial NSOperationQueue queue is used for dispatching delegate messages and completion handlers.
downloadTaskWithRequest:
request
Description forthcoming.
downloadTaskWithResumeData:
resumeData
Description forthcoming.
downloadTaskWithURL:
url
Description forthcoming.
finishTasksAndInvalidate
-finishTasksAndInvalidate
returns immediately and existing tasks will be allowed to run to completion. New tasks may not be created. The session will continue to make delegate callbacks until URLSession:didBecomeInvalidWithError: has been issued. When invalidating a background session, it is not safe to create another background session with the same identifier until URLSession:didBecomeInvalidWithError: has been issued.
getAllTasksWithCompletionHandler:
completionHandler
Description forthcoming.
getTasksWithCompletionHandler:
completionHandler
Description forthcoming.
invalidateAndCancel
-invalidateAndCancel
acts as -finishTasksAndInvalidate , but issues -cancel to all outstanding tasks for this session. Note task cancellation is subject to the state of the task, and some tasks may have already have completed at the time they are sent -cancel .
sessionDescription
An App-specific description of the session.
setSessionDescription:
description
Sets an app-specific description of the session.
uploadTaskWithRequest:
request
fromData:
bodyData
Description forthcoming.
uploadTaskWithRequest:
request
fromFile:
fileURL
Description forthcoming.
uploadTaskWithStreamedRequest:
request
Description forthcoming.
Software documentation for the NSURLSessionConfiguration class
Foundation/NSURLSession.h
NSCopying
Description forthcoming.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
backgroundSessionConfigurationWithIdentifier:
identifier
Description forthcoming.
defaultSessionConfiguration
Description forthcoming.
ephemeralSessionConfiguration
Description forthcoming.
HTTPAdditionalHeaders
Description forthcoming.
HTTPCookieAcceptPolicy
Description forthcoming.
HTTPCookieStorage
Description forthcoming.
HTTPMaximumConnectionLifetime
Permits a session to be configured so that older connections are reused. A value of zero or less uses the default behavior where connections are reused as long as they are not older than 118 seconds, which is reasonable for the vast majority if situations.
HTTPMaximumConnectionsPerHost
Description forthcoming.
HTTPShouldSetCookies
Indicates whether the session should set cookies. This property controls whether tasks within sessions based on this configuration should automatically include cookies from the shared cookie store when making requests. If set to `NO`, you must manually provide cookies by adding a Cookie header through the session's HTTPAdditionalHeaders property or on a per-request basis using a custom NSURLRequest object. The default value is `YES`. See Also: - HTTPCookieAcceptPolicy - HTTPCookieStorage - NSHTTPCookieStorage - NSHTTPCookie
HTTPShouldUsePipelining
HTTP/1.1 pipelining is not implemented. This flag is ignored.
URLCache
Description forthcoming.
URLCredentialStorage
Description forthcoming.
configureRequest:
request
Description forthcoming.
identifier
Description forthcoming.
protocolClasses
Description forthcoming.
requestCachePolicy
Description forthcoming.
setHTTPAdditionalHeaders:
headers
Description forthcoming.
setHTTPCookieAcceptPolicy:
policy
Description forthcoming.
setHTTPCookieStorage:
storage
Description forthcoming.
setHTTPMaximumConnectionLifetime:
n
Description forthcoming.
setHTTPMaximumConnectionsPerHost:
n
Description forthcoming.
setHTTPShouldSetCookies:
flag
Sets whether the session should set cookies. This method controls whether tasks within sessions based on this configuration should automatically include cookies from the shared cookie store when making requests. If set to `NO`, you must manually provide cookies by adding a Cookie header through the session's HTTPAdditionalHeaders property or on a per-request basis using a custom NSURLRequest object. The default value is `YES`. See Also: - HTTPCookieAcceptPolicy - HTTPCookieStorage - NSHTTPCookieStorage - NSHTTPCookie
setHTTPShouldUsePipelining:
flag
Description forthcoming.
setRequestCachePolicy:
policy
Description forthcoming.
setTimeoutIntervalForRequest:
interval
Sets the timeout interval to use when waiting for additional data to arrive.
setTimeoutIntervalForResource:
interval
Sets the maximum amount of time that a resource request should be allowed to take.
setURLCache:
cache
Description forthcoming.
setURLCredentialStorage:
storage
Description forthcoming.
timeoutIntervalForRequest
Gets the timeout interval to use when waiting for additional data to arrive. The request timeout interval controls how long (in seconds) a task should wait for additional data to arrive before giving up. The timer is reset whenever new data arrives. When the request timer reaches the specified interval without receiving any new data, it triggers a timeout. Currently not used by NSURLSession.
timeoutIntervalForResource
Gets the maximum amount of time that a resource request should be allowed to take. The resource timeout interval controls how long (in seconds) to wait for an entire resource to transfer before giving up. The resource timer starts when the request is initiated and counts until either the request completes or this timeout interval is reached, whichever comes first.
Software documentation for the NSURLSessionDataTask class
Foundation/NSURLSession.h
Description forthcoming.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Software documentation for the NSURLSessionDownloadTask class
Foundation/NSURLSession.h
Description forthcoming.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Software documentation for the NSURLSessionStreamTask class
Foundation/NSURLSession.h
Description forthcoming.
Software documentation for the NSURLSessionTask class
Foundation/NSURLSession.h
NSCopying
NSProgressReporting
Description forthcoming.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.
cancel
Cancels the task and the ongoing transfer.
countOfBytesClientExpectsToReceive
Description forthcoming.
countOfBytesClientExpectsToSend
Description forthcoming.
countOfBytesExpectedToReceive
Description forthcoming.
countOfBytesExpectedToSend
Description forthcoming.
countOfBytesReceived
Description forthcoming.
countOfBytesSent
Description forthcoming.
currentRequest
Description forthcoming.
delegate
Description forthcoming.
earliestBeginDate
Description forthcoming.
error
Description forthcoming.
originalRequest
Description forthcoming.
priority
Description forthcoming.
progress
Description forthcoming.
response
Description forthcoming.
resume
Description forthcoming.
setDelegate:
delegate
Description forthcoming.
setEarliestBeginDate:
date
Description forthcoming.
setPriority:
priority
Description forthcoming.
setTaskDescription:
description
Sets an app-specific description of the task.
state
Description forthcoming.
suspend
Description forthcoming.
taskDescription
App-specific description of the task.
taskIdentifier
Description forthcoming.
Software documentation for the NSURLSessionUploadTask class
Foundation/NSURLSession.h
Description forthcoming.
Software documentation for the NSURLSession(NSURLSessionAsynchronousConvenience) category
Foundation/NSURLSession.h
NSURLSession convenience routines deliver results to a completion handler block. These convenience routines are not available to NSURLSessions that are configured as background sessions. Task objects are always created in a suspended state and must be sent the -resume message before they will execute.
dataTaskWithRequest:
request
completionHandler:
completionHandler
Description forthcoming.
dataTaskWithURL:
url
completionHandler:
completionHandler
Description forthcoming.
downloadTaskWithRequest:
request
completionHandler:
completionHandler
Description forthcoming.
downloadTaskWithResumeData:
resumeData
completionHandler:
completionHandler
Description forthcoming.
downloadTaskWithURL:
url
completionHandler:
completionHandler
Description forthcoming.
uploadTaskWithRequest:
request
fromData:
bodyData
completionHandler:
completionHandler
Description forthcoming.
uploadTaskWithRequest:
request
fromFile:
fileURL
completionHandler:
completionHandler
Description forthcoming.
Software documentation for the NSURLSessionDataDelegate protocol
Foundation/NSURLSession.h
NSURLSessionTaskDelegate
Description forthcoming.
URLSession:
session
dataTask:
dataTask
didReceiveData:
data
Description forthcoming.
URLSession:
session
dataTask:
dataTask
didReceiveResponse:
response
completionHandler:
completionHandler
Informs the delegate of a response. This message is sent when all the response headers have arrived, before the body of the response arrives.
Software documentation for the NSURLSessionDelegate protocol
Foundation/NSURLSession.h
NSObject
Description forthcoming.
URLSession:
session
didBecomeInvalidWithError:
error
Description forthcoming.
URLSession:
session
didReceiveChallenge:
challenge
completionHandler:
handler
Description forthcoming.
Software documentation for the NSURLSessionDownloadDelegate protocol
Foundation/NSURLSession.h
NSURLSessionTaskDelegate
Description forthcoming.
URLSession:
session
downloadTask:
downloadTask
didFinishDownloadingToURL:
location
Description forthcoming.
URLSession:
session
downloadTask:
downloadTask
didResumeAtOffset:
fileOffset
expectedTotalBytes:
expectedTotalBytes
Description forthcoming.
URLSession:
session
downloadTask:
downloadTask
didWriteData:
bytesWritten
totalBytesWritten:
totalBytesWritten
totalBytesExpectedToWrite:
totalBytesExpectedToWrite
Description forthcoming.
Software documentation for the NSURLSessionTaskDelegate protocol
Foundation/NSURLSession.h
NSURLSessionDelegate
Description forthcoming.
URLSession:
session
didCreateTask:
task
Description forthcoming.
URLSession:
session
task:
task
didCompleteWithError:
error
Description forthcoming.
URLSession:
session
task:
task
didReceiveChallenge:
challenge
completionHandler:
handler
Description forthcoming.
URLSession:
session
task:
task
didSendBodyData:
bytesSent
totalBytesSent:
totalBytesSent
totalBytesExpectedToSend:
totalBytesExpectedToSend
Description forthcoming.
URLSession:
session
task:
task
needNewBodyStream:
completionHandler
Description forthcoming.
URLSession:
session
task:
task
willPerformHTTPRedirection:
response
newRequest:
request
completionHandler:
completionHandler
Description forthcoming.