Session

open class Session

Session creates and manages Alamofire’s Request types during their lifetimes. It also provides common functionality for all Requests, including queuing, interception, trust management, redirect handling, and response cache handling.

  • Shared singleton instance used by all AF.request APIs. Cannot be modified.

    Declaration

    Swift

    public static let `default`: Session
  • Underlying URLSession used to create URLSessionTasks for this instance, and for which this instance’s delegate handles URLSessionDelegate callbacks.

    Declaration

    Swift

    public let session: URLSession
  • Instance’s SessionDelegate, which handles the URLSessionDelegate methods and Request interaction.

    Declaration

    Swift

    public let delegate: SessionDelegate
  • Root DispatchQueue for all internal callbacks and state update. MUST be a serial queue.

    Declaration

    Swift

    public let rootQueue: DispatchQueue
  • Value determining whether this instance automatically calls resume() on all created Requests.

    Declaration

    Swift

    public let startRequestsImmediately: Bool
  • DispatchQueue on which URLRequests are created asynchronously. By default this queue uses rootQueue as its target, but a separate queue can be used if request creation is determined to be a bottleneck. Always profile and test before introducing an additional queue.

    Declaration

    Swift

    public let requestQueue: DispatchQueue
  • DispatchQueue passed to all Requests on which they perform their response serialization. By default this queue uses rootQueue as its target but a separate queue can be used if response serialization is determined to be a bottleneck. Always profile and test before introducing an additional queue.

    Declaration

    Swift

    public let serializationQueue: DispatchQueue
  • RequestInterceptor used for all Request created by the instance. RequestInterceptors can also be set on a per-Request basis, in which case the Request‘s interceptor takes precedence over this value.

    Declaration

    Swift

    public let interceptor: RequestInterceptor?
  • ServerTrustManager instance used to evaluate all trust challenges and provide certificate and key pinning.

    Declaration

    Swift

    public let serverTrustManager: ServerTrustManager?
  • RedirectHandler instance used to provide customization for request redirection.

    Declaration

    Swift

    public let redirectHandler: RedirectHandler?
  • CachedResponseHandler instance used to provide customization of cached response handling.

    Declaration

    Swift

    public let cachedResponseHandler: CachedResponseHandler?
  • CompositeEventMonitor used to compose Alamofire’s defaultEventMonitors and any passed EventMonitors.

    Declaration

    Swift

    public let eventMonitor: CompositeEventMonitor
  • EventMonitors included in all instances. [AlamofireNotifications()] by default.

    Declaration

    Swift

    public let defaultEventMonitors: [EventMonitor]
  • Creates a Session from a URLSession and other parameters.

    Note

    When passing a URLSession, you must create the URLSession with a specific delegateQueue value and pass the delegateQueue‘s underlyingQueue as the rootQueue parameter of this initializer.

    Declaration

    Swift

    public init(session: URLSession,
                delegate: SessionDelegate,
                rootQueue: DispatchQueue,
                startRequestsImmediately: Bool = true,
                requestQueue: DispatchQueue? = nil,
                serializationQueue: DispatchQueue? = nil,
                interceptor: RequestInterceptor? = nil,
                serverTrustManager: ServerTrustManager? = nil,
                redirectHandler: RedirectHandler? = nil,
                cachedResponseHandler: CachedResponseHandler? = nil,
                eventMonitors: [EventMonitor] = [])

    Parameters

    session

    Underlying URLSession for this instance.

    delegate

    SessionDelegate that handles session‘s delegate callbacks as well as Request interaction.

    rootQueue

    Root DispatchQueue for all internal callbacks and state updates. MUST be a serial queue.

    startRequestsImmediately

    Determines whether this instance will automatically start all Requests. true by default. If set to false, all Requests created must have .resume() called. on them for them to start.

    requestQueue

    DispatchQueue on which to perform URLRequest creation. By default this queue will use the rootQueue as its target. A separate queue can be used if it’s determined request creation is a bottleneck, but that should only be done after careful testing and profiling. nil by default.

    serializationQueue

    DispatchQueue on which to perform all response serialization. By default this queue will use the rootQueue as its target. A separate queue can be used if it’s determined response serialization is a bottleneck, but that should only be done after careful testing and profiling. nil by default.

    interceptor

    RequestInterceptor to be used for all Requests created by this instance. nil by default.

    serverTrustManager

    ServerTrustManager to be used for all trust evaluations by this instance. nil by default.

    redirectHandler

    RedirectHandler to be used by all Requests created by this instance. nil by default.

    cachedResponseHandler

    CachedResponseHandler to be used by all Requests created by this instance. nil by default.

    eventMonitors

    Additional EventMonitors used by the instance. Alamofire always adds a AlamofireNotifications EventMonitor to the array passed here. [] by default.

  • Creates a Session from a URLSessionConfiguration.

    Note

    This initializer lets Alamofire handle the creation of the underlying URLSession and its delegateQueue, and is the recommended initializer for most uses.

    Declaration

    Swift

    public convenience init(configuration: URLSessionConfiguration = URLSessionConfiguration.af.default,
                            delegate: SessionDelegate = SessionDelegate(),
                            rootQueue: DispatchQueue = DispatchQueue(label: "org.alamofire.session.rootQueue"),
                            startRequestsImmediately: Bool = true,
                            requestQueue: DispatchQueue? = nil,
                            serializationQueue: DispatchQueue? = nil,
                            interceptor: RequestInterceptor? = nil,
                            serverTrustManager: ServerTrustManager? = nil,
                            redirectHandler: RedirectHandler? = nil,
                            cachedResponseHandler: CachedResponseHandler? = nil,
                            eventMonitors: [EventMonitor] = [])

    Parameters

    configuration

    URLSessionConfiguration to be used to create the underlying URLSession. Changes to this value after being passed to this initializer will have no effect. URLSessionConfiguration.af.default by default.

    delegate

    SessionDelegate that handles session‘s delegate callbacks as well as Request interaction. SessionDelegate() by default.

    rootQueue

    Root DispatchQueue for all internal callbacks and state updates. MUST be a serial queue. DispatchQueue(label: "org.alamofire.session.rootQueue") by default.

    startRequestsImmediately

    Determines whether this instance will automatically start all Requests. true by default. If set to false, all Requests created must have .resume() called. on them for them to start.

    requestQueue

    DispatchQueue on which to perform URLRequest creation. By default this queue will use the rootQueue as its target. A separate queue can be used if it’s determined request creation is a bottleneck, but that should only be done after careful testing and profiling. nil by default.

    serializationQueue

    DispatchQueue on which to perform all response serialization. By default this queue will use the rootQueue as its target. A separate queue can be used if it’s determined response serialization is a bottleneck, but that should only be done after careful testing and profiling. nil by default.

    interceptor

    RequestInterceptor to be used for all Requests created by this instance. nil by default.

    serverTrustManager

    ServerTrustManager to be used for all trust evaluations by this instance. nil by default.

    redirectHandler

    RedirectHandler to be used by all Requests created by this instance. nil by default.

    cachedResponseHandler

    CachedResponseHandler to be used by all Requests created by this instance. nil by default.

    eventMonitors

    Additional EventMonitors used by the instance. Alamofire always adds a AlamofireNotifications EventMonitor to the array passed here. [] by default.

  • Cancel all active Requests, optionally calling a completion handler when complete.

    Note

    This is an asynchronous operation and does not block the creation of future Requests. Cancelled Requests may not cancel immediately due internal work, and may not cancel at all if they are close to completion when cancelled.

    Declaration

    Swift

    public func cancelAllRequests(completingOnQueue queue: DispatchQueue = .main, completion: (() -> Void)? = nil)

    Parameters

    queue

    DispatchQueue on which the completion handler is run. .main by default.

    completion

    Closure to be called when all Requests have been cancelled.

  • Creates an UploadRequest for the multipart form data built using a closure and sent using the provided URLRequest components and RequestInterceptor.

    It is important to understand the memory implications of uploading MultipartFormData. If the cumulative payload is small, encoding the data in-memory and directly uploading to a server is the by far the most efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be used for larger payloads such as video content.

    The encodingMemoryThreshold parameter allows Alamofire to automatically determine whether to encode in-memory or stream from disk. If the content length of the MultipartFormData is below the encodingMemoryThreshold, encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding technique was used.

    Declaration

    Swift

    open func upload(multipartFormData: @escaping (MultipartFormData) -> Void,
                     to url: URLConvertible,
                     usingThreshold encodingMemoryThreshold: UInt64 = MultipartFormData.encodingMemoryThreshold,
                     method: HTTPMethod = .post,
                     headers: HTTPHeaders? = nil,
                     interceptor: RequestInterceptor? = nil,
                     fileManager: FileManager = .default) -> UploadRequest

    Parameters

    multipartFormData

    MultipartFormData building closure.

    convertible

    URLConvertible value to be used as the URLRequest‘s URL.

    encodingMemoryThreshold

    Byte threshold used to determine whether the form data is encoded into memory or onto disk before being uploaded. MultipartFormData.encodingMemoryThreshold by default.

    method

    HTTPMethod for the URLRequest. .post by default.

    headers

    HTTPHeaders value to be added to the URLRequest. nil by default.

    interceptor

    RequestInterceptor value to be used by the returned DataRequest. nil by default.

    fileManager

    FileManager to be used if the form data exceeds the memory threshold and is written to disk before being uploaded. .default instance by default.

    Return Value

    The created UploadRequest.

  • Creates an UploadRequest using a MultipartFormData building closure, the provided URLRequestConvertible value, and a RequestInterceptor.

    It is important to understand the memory implications of uploading MultipartFormData. If the cumulative payload is small, encoding the data in-memory and directly uploading to a server is the by far the most efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be used for larger payloads such as video content.

    The encodingMemoryThreshold parameter allows Alamofire to automatically determine whether to encode in-memory or stream from disk. If the content length of the MultipartFormData is below the encodingMemoryThreshold, encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding technique was used.

    Declaration

    Swift

    open func upload(multipartFormData: @escaping (MultipartFormData) -> Void,
                     with request: URLRequestConvertible,
                     usingThreshold encodingMemoryThreshold: UInt64 = MultipartFormData.encodingMemoryThreshold,
                     interceptor: RequestInterceptor? = nil,
                     fileManager: FileManager = .default) -> UploadRequest

    Parameters

    multipartFormData

    MultipartFormData building closure.

    request

    URLRequestConvertible value to be used to create the URLRequest.

    encodingMemoryThreshold

    Byte threshold used to determine whether the form data is encoded into memory or onto disk before being uploaded. MultipartFormData.encodingMemoryThreshold by default.

    interceptor

    RequestInterceptor value to be used by the returned DataRequest. nil by default.

    fileManager

    FileManager to be used if the form data exceeds the memory threshold and is written to disk before being uploaded. .default instance by default.

    Return Value

    The created UploadRequest.

  • Creates an UploadRequest for the prebuilt MultipartFormData value using the provided URLRequest components and RequestInterceptor.

    It is important to understand the memory implications of uploading MultipartFormData. If the cumulative payload is small, encoding the data in-memory and directly uploading to a server is the by far the most efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be used for larger payloads such as video content.

    The encodingMemoryThreshold parameter allows Alamofire to automatically determine whether to encode in-memory or stream from disk. If the content length of the MultipartFormData is below the encodingMemoryThreshold, encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding technique was used.

    Declaration

    Swift

    open func upload(multipartFormData: MultipartFormData,
                     to url: URLConvertible,
                     usingThreshold encodingMemoryThreshold: UInt64 = MultipartFormData.encodingMemoryThreshold,
                     method: HTTPMethod = .post,
                     headers: HTTPHeaders? = nil,
                     interceptor: RequestInterceptor? = nil,
                     fileManager: FileManager = .default) -> UploadRequest

    Parameters

    multipartFormData

    MultipartFormData instance to upload.

    url

    URLConvertible value to be used as the URLRequest‘s URL.

    encodingMemoryThreshold

    Byte threshold used to determine whether the form data is encoded into memory or onto disk before being uploaded. MultipartFormData.encodingMemoryThreshold by default.

    method

    HTTPMethod for the URLRequest. .post by default.

    headers

    HTTPHeaders value to be added to the URLRequest. nil by default.

    interceptor

    RequestInterceptor value to be used by the returned DataRequest. nil by default.

    fileManager

    FileManager to be used if the form data exceeds the memory threshold and is written to disk before being uploaded. .default instance by default.

    Return Value

    The created UploadRequest.

  • Creates an UploadRequest for the prebuilt MultipartFormData value using the providing URLRequestConvertible value and RequestInterceptor.

    It is important to understand the memory implications of uploading MultipartFormData. If the cumulative payload is small, encoding the data in-memory and directly uploading to a server is the by far the most efficient approach. However, if the payload is too large, encoding the data in-memory could cause your app to be terminated. Larger payloads must first be written to disk using input and output streams to keep the memory footprint low, then the data can be uploaded as a stream from the resulting file. Streaming from disk MUST be used for larger payloads such as video content.

    The encodingMemoryThreshold parameter allows Alamofire to automatically determine whether to encode in-memory or stream from disk. If the content length of the MultipartFormData is below the encodingMemoryThreshold, encoding takes place in-memory. If the content length exceeds the threshold, the data is streamed to disk during the encoding process. Then the result is uploaded as data or as a stream depending on which encoding technique was used.

    Declaration

    Swift

    open func upload(multipartFormData: MultipartFormData,
                     with request: URLRequestConvertible,
                     usingThreshold encodingMemoryThreshold: UInt64 = MultipartFormData.encodingMemoryThreshold,
                     interceptor: RequestInterceptor? = nil,
                     fileManager: FileManager = .default) -> UploadRequest

    Parameters

    multipartFormData

    MultipartFormData instance to upload.

    request

    URLRequestConvertible value to be used to create the URLRequest.

    encodingMemoryThreshold

    Byte threshold used to determine whether the form data is encoded into memory or onto disk before being uploaded. MultipartFormData.encodingMemoryThreshold by default.

    interceptor

    RequestInterceptor value to be used by the returned DataRequest. nil by default.

    fileManager

    FileManager instance to be used by the returned UploadRequest. .default instance by default.

    Return Value

    The created UploadRequest.