Request

public class Request
extension Request: Equatable
extension Request: Hashable
extension Request: CustomStringConvertible

Request is the common superclass of all Alamofire request types and provides common state, delegate, and callback handling.

Initial State

  • id

    UUID providing a unique identifier for the Request, used in the Hashable and Equatable conformances.

    Declaration

    Swift

    public let id: UUID

  • The serial queue for all internal async actions.

    Declaration

    Swift

    public let underlyingQueue: DispatchQueue

  • The queue used for all serialization actions. By default it’s a serial queue that targets underlyingQueue.

    Declaration

    Swift

    public let serializationQueue: DispatchQueue

  • EventMonitor used for event callbacks.

    Declaration

    Swift

    public let eventMonitor: EventMonitor?

  • The Request‘s interceptor.

    Declaration

    Swift

    public let interceptor: RequestInterceptor?

  • The Request‘s delegate.

    Declaration

    Swift

    public private(set) weak var delegate: RequestDelegate? { get }

Mutable State

  • State of the Request.

    Declaration

    Swift

    public var state: State { get }

  • Returns whether state is .initialized.

    Declaration

    Swift

    public var isInitialized: Bool { get }

  • Returns whether state is .resumed.

    Declaration

    Swift

    public var isResumed: Bool { get }

  • Returns whether state is .suspended.

    Declaration

    Swift

    public var isSuspended: Bool { get }

  • Returns whether state is .cancelled.

    Declaration

    Swift

    public var isCancelled: Bool { get }

  • Returns whether state is .finished.

    Declaration

    Swift

    public var isFinished: Bool { get }

Progress

  • Closure type executed when monitoring the upload or download progress of a request.

    Declaration

    Swift

    public typealias ProgressHandler = (Progress) -> Void

  • Progress of the upload of the body of the executed URLRequest. Reset to 0 if the Request is retried.

    Declaration

    Swift

    public let uploadProgress: Progress

  • Progress of the download of any response data. Reset to 0 if the Request is retried.

    Declaration

    Swift

    public let downloadProgress: Progress

  • ProgressHandler called when uploadProgress is updated, on the provided DispatchQueue.

    Declaration

    Swift

    public internal(set) var uploadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)? { get set }

  • ProgressHandler called when downloadProgress is updated, on the provided DispatchQueue.

    Declaration

    Swift

    public internal(set) var downloadProgressHandler: (handler: ProgressHandler, queue: DispatchQueue)? { get set }

Redirect Handling

Cached Response Handling

URLCredential

  • URLCredential used for authentication challenges. Created by calling one of the authenticate methods.

    Declaration

    Swift

    public internal(set) var credential: URLCredential? { get set }

URLRequests

  • All URLRequests created on behalf of the Request, including original and adapted requests.

    Declaration

    Swift

    public var requests: [URLRequest] { get }

  • First URLRequest created on behalf of the Request. May not be the first one actually executed.

    Declaration

    Swift

    public var firstRequest: URLRequest? { get }

  • Last URLRequest created on behalf of the Request.

    Declaration

    Swift

    public var lastRequest: URLRequest? { get }

  • Current URLRequest created on behalf of the Request.

    Declaration

    Swift

    public var request: URLRequest? { get }

  • URLRequests from all of the URLSessionTasks executed on behalf of the Request. May be different from requests due to URLSession manipulation.

    Declaration

    Swift

    public var performedRequests: [URLRequest] { get }

HTTPURLResponse

  • HTTPURLResponse received from the server, if any. If the Request was retried, this is the response of the last URLSessionTask.

    Declaration

    Swift

    public var response: HTTPURLResponse? { get }

Tasks

  • All URLSessionTasks created on behalf of the Request.

    Declaration

    Swift

    public var tasks: [URLSessionTask] { get }

  • First URLSessionTask created on behalf of the Request.

    Declaration

    Swift

    public var firstTask: URLSessionTask? { get }

  • Last URLSessionTask created on behalf of the Request.

    Declaration

    Swift

    public var lastTask: URLSessionTask? { get }

  • Current URLSessionTask created on behalf of the Request.

    Declaration

    Swift

    public var task: URLSessionTask? { get }

Metrics

  • All URLSessionTaskMetrics gathered on behalf of the Request. Should correspond to the tasks created.

    Declaration

    Swift

    public var allMetrics: [URLSessionTaskMetrics] { get }

  • First URLSessionTaskMetrics gathered on behalf of the Request.

    Declaration

    Swift

    public var firstMetrics: URLSessionTaskMetrics? { get }

  • Last URLSessionTaskMetrics gathered on behalf of the Request.

    Declaration

    Swift

    public var lastMetrics: URLSessionTaskMetrics? { get }

  • Current URLSessionTaskMetrics gathered on behalf of the Request.

    Declaration

    Swift

    public var metrics: URLSessionTaskMetrics? { get }

Retry Count

  • Number of times the Request has been retried.

    Declaration

    Swift

    public var retryCount: Int { get }

Error

  • Error returned from Alamofire internally, from the network request directly, or any validators executed.

    Declaration

    Swift

    public internal(set) var error: AFError? { get set }

State

  • Cancels the instance. Once cancelled, a Request can no longer be resumed or suspended.

    Declaration

    Swift

    @discardableResult
public func cancel() -> Self

    Return Value

    The instance.

  • Suspends the instance.

    Declaration

    Swift

    @discardableResult
public func suspend() -> Self

    Return Value

    The instance.

  • Resumes the instance.

    Declaration

    Swift

    @discardableResult
public func resume() -> Self

    Return Value

    The instance.

Closure API

  • Associates a credential using the provided values with the instance.

    Declaration

    Swift

    @discardableResult
public func authenticate(username: String, password: String, persistence: URLCredential.Persistence = .forSession) -> Self

    Parameters

    username

    The username.
    password

    The password.
    persistence

    The URLCredential.Persistence for the created URLCredential. .forSession by default.

    Return Value

    The instance.

  • Associates the provided credential with the instance.

    Declaration

    Swift

    @discardableResult
public func authenticate(with credential: URLCredential) -> Self

    Parameters

    credential

    The URLCredential.

    Return Value

    The instance.

  • Sets a closure to be called periodically during the lifecycle of the instance as data is read from the server.

    Note

    Only the last closure provided is used.

    Declaration

    Swift

    @discardableResult
public func downloadProgress(queue: DispatchQueue = .main, closure: @escaping ProgressHandler) -> Self

    Parameters

    queue

    The DispatchQueue to execute the closure on. .main by default.
    closure

    The closure to be executed periodically as data is read from the server.

    Return Value

    The instance.

  • Sets a closure to be called periodically during the lifecycle of the instance as data is sent to the server.

    Note

    Only the last closure provided is used.

    Declaration

    Swift

    @discardableResult
public func uploadProgress(queue: DispatchQueue = .main, closure: @escaping ProgressHandler) -> Self

    Parameters

    queue

    The DispatchQueue to execute the closure on. .main by default.
    closure

    The closure to be executed periodically as data is sent to the server.

    Return Value

    The instance.

Redirects

  • Sets the redirect handler for the instance which will be used if a redirect response is encountered.

    Note

    Attempting to set the redirect handler more than once is a logic error and will crash.

    Declaration

    Swift

    @discardableResult
public func redirect(using handler: RedirectHandler) -> Self

    Parameters

    handler

    Return Value

    The instance.

Cached Responses

  • Sets the cached response handler for the Request which will be used when attempting to cache a response.

    Note

    Attempting to set the cache handler more than once is a logic error and will crash.

    Declaration

    Swift

    @discardableResult
public func cacheResponse(using handler: CachedResponseHandler) -> Self

    Parameters

    handler

    Return Value

    The instance.

Lifetime APIs

  • Sets a handler to be called when the cURL description of the request is available.

    Note

    When waiting for a Request‘s URLRequest to be created, only the last handler will be called.

    Declaration

    Swift

    @discardableResult
public func cURLDescription(on queue: DispatchQueue, calling handler: @escaping (String) -> Void) -> Self

    Parameters

    queue

    DispatchQueue on which handler will be called.
    handler

    Closure to be called when the cURL description is available.

    Return Value

    The instance.

  • Sets a handler to be called when the cURL description of the request is available.

    Note

    When waiting for a Request‘s URLRequest to be created, only the last handler will be called.

    Declaration

    Swift

    @discardableResult
public func cURLDescription(calling handler: @escaping (String) -> Void) -> Self

    Parameters

    handler

    Closure to be called when the cURL description is available. Called on the instance’s underlyingQueue by default.

    Return Value

    The instance.

  • Sets a closure to called whenever Alamofire creates a URLRequest for this instance.

    Note

    This closure will be called multiple times if the instance adapts incoming URLRequests or is retried.

    Declaration

    Swift

    @discardableResult
public func onURLRequestCreation(on queue: DispatchQueue = .main, perform handler: @escaping (URLRequest) -> Void) -> Self

    Parameters

    queue

    DispatchQueue on which handler will be called. .main by default.
    handler

    Closure to be called when a URLRequest is available.

    Return Value

    The instance.

  • Sets a closure to be called whenever the instance creates a URLSessionTask.

    Note

    This API should only be used to provide URLSessionTasks to existing API, like NSFileProvider. It SHOULD NOT be used to interact with tasks directly, as that may be break Alamofire features. Additionally, this closure may be called multiple times if the instance is retried.

    Declaration

    Swift

    @discardableResult
public func onURLSessionTaskCreation(on queue: DispatchQueue = .main, perform handler: @escaping (URLSessionTask) -> Void) -> Self

    Parameters

    queue

    DispatchQueue on which handler will be called. .main by default.
    handler

    Closure to be called when the URLSessionTask is available.

    Return Value

    The instance.

  • Posted when a Request is resumed. The Notification contains the resumed Request.

    Declaration

    Swift

    public static let didResumeNotification: Notification.Name

  • Posted when a Request is suspended. The Notification contains the suspended Request.

    Declaration

    Swift

    public static let didSuspendNotification: Notification.Name

  • Posted when a Request is cancelled. The Notification contains the cancelled Request.

    Declaration

    Swift

    public static let didCancelNotification: Notification.Name

  • Posted when a Request is finished. The Notification contains the completed Request.

    Declaration

    Swift

    public static let didFinishNotification: Notification.Name

  • Posted when a URLSessionTask is resumed. The Notification contains the Request associated with the URLSessionTask.

    Declaration

    Swift

    public static let didResumeTaskNotification: Notification.Name

  • Posted when a URLSessionTask is suspended. The Notification contains the Request associated with the URLSessionTask.

    Declaration

    Swift

    public static let didSuspendTaskNotification: Notification.Name

  • Posted when a URLSessionTask is cancelled. The Notification contains the Request associated with the URLSessionTask.

    Declaration

    Swift

    public static let didCancelTaskNotification: Notification.Name

  • Posted when a URLSessionTask is completed. The Notification contains the Request associated with the URLSessionTask.

    Declaration

    Swift

    public static let didCompleteTaskNotification: Notification.Name

  • Type indicating how a DataRequest or DataStreamRequest should proceed after receiving an HTTPURLResponse.

    See more

    Declaration

    Swift

    public enum ResponseDisposition

Protocol Conformances

  • Declaration

    Swift

    public static func == (lhs: Request, rhs: Request) -> Bool

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

  • A textual representation of this instance, including the HTTPMethod and URL if the URLRequest has been created, as well as the response status code, if a response has been received.

    Declaration

    Swift

    public var description: String { get }

  • cURL representation of the instance.

    Declaration

    Swift

    public func cURLDescription() -> String

    Return Value

    The cURL equivalent of the instance.

Request Event Streams

Helper Types

  • Used to represent whether a validation succeeded or failed.

    Declaration

    Swift

    public typealias ValidationResult = Result<Void, Error>