SAPURLSessionObserving

public protocol SAPURLSessionObserving : AnyObject

Declares the methods which allow callers to modify the network request and the response.

  • Tells the URL session that the session has been invalidated. If you invalidate a session by calling its finishTasksAndInvalidate() method, the session waits until after the final task in the session finishes or fails before calling this delegate method. If you call the invalidateAndCancel() method, the session calls this delegate method immediately.

    Default Implementation

    Tells the URL session that the session has been invalidated.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, didBecomeInvalidWithError error: Error?, completionHandler: @escaping () -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session object that was invalidated.

    error

    The error that caused invalidation, or nil if the invalidation was explicit.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that all messages enqueued for a session have been delivered.

    Default Implementation

    Tells the delegate that all messages enqueued for a session have been delivered.

    Declaration

    Swift

    func sapURLSessionDidFinishEvents(forBackgroundURLSession session: SAPURLSession, completionHandler: @escaping () -> Swift.Void) -> Swift.Void
  • Tells the delegate that a delayed URL session task will now begin loading. This method is called when a background session task with a delayed start time (as set with the earliestBeginDate property) is ready to start. This delegate method should only be implemented if the request might become stale while waiting for the network load and needs to be replaced by a new request. For loading to continue, the delegate must call the completion handler, passing in a disposition that indicates how the task should proceed. Passing the cancel disposition is equivalent to calling cancel() on the task directly.

    Default Implementation

    Tells the delegate that a delayed URL session task will now begin loading.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, willBeginDelayedRequest request: URLRequest, completionHandler: @escaping (SAPURLSession.DelayedRequestDisposition) -> Void)

    Parameters

    session

    The session containing the delayed request.

    task

    The task handling the delayed request.

    request

    The request that was delayed.

    completionHandler

    A completion handler to perform the request.

  • Tells the delegate that the task is waiting until suitable connectivity is available before beginning the network load. This method is called if the waitsForConnectivity property of URLSessionConfiguration is true, and sufficient connectivity is unavailable. The delegate can use this opportunity to update the user interface; for example, by presenting an offline mode or a cellular-only mode. This method is called, at most, once per task, and only if connectivity is initially unavailable. It is never called for background sessions because waitsForConnectivity is ignored for those sessions.

    Default Implementation

    Tells the delegate that the task is waiting until suitable connectivity is available before beginning the network load.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, taskIsWaitingForConnectivity task: SAPURLSessionTask)

    Parameters

    session

    The session that contains the waiting task.

    task

    The task that is waiting for a change in connectivity.

  • Tells the delegate that the remote server requested an HTTP redirect. This method is called only for tasks in default and ephemeral sessions. Tasks in background sessions automatically follow redirects.

    Default Implementation

    Tells the delegate that the remote server requested an HTTP redirect.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse, newRequest request: URLRequest, completionHandler: @escaping (SAPURLSession.HTTPRedirectDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the task whose request resulted in a redirect.

    task

    The task whose request resulted in a redirect.

    response

    An object containing the server’s response to the original request.

    request

    A URL request object filled out with the new location.

    completionHandler

    A completion handler that your delegate method must call.

  • Requests credentials from the delegate in response to an authentication request from the remote server. This method handles task-level authentication challenges.

    Default Implementation

    Requests credentials from the delegate in response to an authentication request from the remote server.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (SAPURLSession.AuthChallengeDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the task whose request requires authentication.

    task

    The task whose request requires authentication.

    challenge

    An object that contains the request for authentication.

    completionHandler

    A completion handler that your delegate method must call.

  • sapURLSession(_:task:willUse:for:) Default implementation

    Can be used to obtain credentials that are passed to the didReceive challenge delegate / observer method.

    Default Implementation

    Can be used to obtain credentials that are passed to the didReceive challenge delegate / observer method.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, willUse credential: URLCredential, for challenge: URLAuthenticationChallenge)

    Parameters

    session

    The session containing the task whose request requires authentication.

    task

    The task whose request required authentication.

    willUse

    The URLCredential that are going to be used.

    challenge

    The URLAuthenticationChallenge that has been handled.

  • Tells the delegate when a task requires a new request body stream to send to the remote server. This delegate method is called under two circumstances:

    • To provide the initial request body stream if the task was created with uploadTask(withStreamedRequest:)
    • To provide a replacement request body stream if the task needs to resend a request that has a body stream because of an authentication challenge or other recoverable server error.

    Default Implementation

    Tells the delegate when a task requires a new request body stream to send to the remote server.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, needNewBodyStream completionHandler: @escaping (SAPURLSession.InputStreamDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the task that needs a new body stream.

    task

    The task that needs a new body stream.

    completionHandler

    A completion handler that your delegate method must call.

  • Periodically informs the delegate of the progress of sending body content to the server.

    Default Implementation

    Periodically informs the delegate of the progress of sending body content to the server.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didSendBodyData bytesSent: Int64, totalBytesSent: Int64, totalBytesExpectedToSend: Int64, completionHandler: @escaping (SAPURLSession.CancellableDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the data task.

    task

    The data task.

    bytesSent

    The number of bytes sent since the last time this delegate method was called.

    totalBytesSent

    The total number of bytes sent so far.

    totalBytesExpectedToSend

    The expected length of the body data.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the session finished collecting metrics for the task.

    Default Implementation

    Tells the delegate that the session finished collecting metrics for the task.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics, completionHandler: @escaping () -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session collecting the metrics.

    task

    The task whose metrics have been collected.

    metrics

    The collected metrics.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the task finished transferring data. Server errors are not reported through the error parameter. The only errors your delegate receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host.

    Default Implementation

    Tells the delegate that the task finished transferring data.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didCompleteWithError error: Error?, completionHandler: @escaping (SAPURLSession.DidCompleteDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the task whose request finished transferring data.

    task

    The task whose request finished transferring data.

    error

    If an error occurred, an error object indicating how the transfer failed, otherwise nil.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the data task received the initial reply (headers) from the server. This method is optional unless you need to support the (relatively obscure) multipart/x-mixed-replace content type. With that content type, the server sends a series of parts, each of which is intended to replace the previous part. The session calls this method at the beginning of each part, and you should then display, discard, or otherwise process the previous part, as appropriate. If you do not provide this delegate method, the session always allows the task to continue.

    Default Implementation

    Tells the delegate that the data task received the initial reply (headers) from the server.

    Tells the delegate that the data task has received some of the expected data.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, dataTask: SAPURLSessionTask, didReceive response: URLResponse, completionHandler: @escaping (SAPURLSession.ResponseDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the data task that received an initial reply.

    dataTask

    The data task that received an initial reply.

    response

    A URL response object populated with headers.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the data task was changed to a download task.

    Default Implementation

    Tells the delegate that the data task was changed to a download task.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, dataTask: SAPURLSessionTask, didBecome downloadTask: URLSessionDownloadTask, completionHandler: @escaping (SAPURLSession.CancellableDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the task that was replaced by a download task.

    dataTask

    The data task that was replaced by a download task.

    downloadTask

    The new download task that replaced the data task.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the data task has received some of the expected data.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, dataTask: SAPURLSessionTask, didReceive data: Data, completionHandler: @escaping (SAPURLSession.DataDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the data task that provided data.

    dataTask

    The data task that provided data.

    data

    A data object containing the transferred data.

    completionHandler

    A completion handler that your delegate method must call.

  • Asks the delegate whether the data (or upload) task should store the response in the cache.

    Default Implementation

    Asks the delegate whether the data (or upload) task should store the response in the cache.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, dataTask: SAPURLSessionTask, willCacheResponse proposedResponse: CachedURLResponse, completionHandler: @escaping (SAPURLSession.CacheResponseDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the data (or upload) task.

    dataTask

    The data (or upload) task.

    proposedResponse

    The default caching behavior. This behavior is determined based on the current caching policy and the values of certain received headers, such as the Pragma and Cache-Control headers.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that a download task has finished downloading.

    Default Implementation

    Tells the delegate that a download task has finished downloading.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, downloadTask: SAPURLSessionTask, didFinishDownloadingTo location: URL, completionHandler: @escaping (SAPURLSession.DidCompleteDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the download task that finished.

    downloadTask

    The download task that finished.

    location

    A file URL for the temporary file. Because the file is temporary, you must either open the file for reading or move it to a permanent location in your app’s sandbox container directory before returning from this delegate method.

    completionHandler

    A completion handler that your delegate method must call.

  • Periodically informs the delegate about the download’s progress.

    Default Implementation

    Periodically informs the delegate about the download’s progress.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, downloadTask: SAPURLSessionTask, didWriteData bytesWritten: Int64, totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64, completionHandler: @escaping (SAPURLSession.CancellableDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the download task.

    downloadTask

    The download task.

    bytesWritten

    The number of bytes transferred since the last time this delegate method was called.

    totalBytesWritten

    The total number of bytes transferred so far.

    totalBytesExpectedToWrite

    The expected length of the file, as provided by the Content-Length header. If this header was not provided, the value is NSURLSessionTransferSizeUnknown.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the download task has resumed downloading.

    Default Implementation

    Tells the delegate that the download task has resumed downloading.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, downloadTask: SAPURLSessionTask, didResumeAtOffset fileOffset: Int64, expectedTotalBytes: Int64, completionHandler: @escaping (SAPURLSession.CancellableDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session containing the download task that finished.

    downloadTask

    The download task that resumed. See explanation in the discussion.

    fileOffset

    If the file’s cache policy or last modified date prevents reuse of the existing content, then this value is zero. Otherwise, this value is an integer representing the number of bytes on disk that do not need to be retrieved again.

    expectedTotalBytes

    The expected length of the file, as provided by the Content-Length header. If this header was not provided, the value is NSURLSessionTransferSizeUnknown.

    completionHandler

    A completion handler that your delegate method must call.

  • sapURLSession(_:task:didCreate:) Default implementation

    Invoked after request observers are executed, the backing URLSessionDataTask is instantiated.

    Default Implementation

    Invoked after request observers are executed, the backing URLSessionDataTask is instantiated.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didCreate sessionTask: URLSessionTask)

    Parameters

    session

    The session containing the task which underlying task has been created.

    task

    sessionTask

    The created underlying session task

  • sapURLSession(_:didCreate:for:) Default implementation

    Invoked after the resume of a background task, the wrapper SAPURLSessionTask is instantiated.

    Default Implementation

    Invoked after the resume of a background task, the wrapper SAPURLSessionTask is instantiated.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, didCreate task: SAPURLSessionTask, for sessionTask: URLSessionTask)

    Parameters

    session

    The session that came back from background.

    task

    The newly created wrapper task.

    sessionTask

    The session task that resumed.

  • Invoked before a request is sent. An observer can modify the request, or cancel it.

    Default Implementation

    Invoked before a request is sent. An observer can modify the request, or cancel it.

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, willSend request: URLRequest, completionHandler: @escaping (SAPURLSession.RequestDisposition) -> Swift.Void) -> Swift.Void

    Parameters

    session

    The session which will contain the task after creation.

    task

    The task which is about to be created.

    request

    The request with which the task will be created.

    completionHandler

    A completion handler that your delegate method must call.

  • Tells the delegate that the task finished transferring data and enumerated all observers. Server errors are not reported through the error parameter. The only errors your delegate receives through the error parameter are client-side errors, such as being unable to resolve the hostname or connect to the host.

    Default Implementation

    Tells the delegate that the task finished transferring data and enumerated all observers

    Declaration

    Swift

    func sapURLSession(_ session: SAPURLSession, task: SAPURLSessionTask, didCompleteWithError error: Error?)

    Parameters

    session

    The session containing the task whose request finished transferring data.

    task

    The task whose request finished transferring data.

    error

    If an error occurred, an error object indicating how the transfer failed, otherwise nil.