Class

NSURLSessionWebSocketTask

A URL session task that communicates over the WebSockets protocol standard.

Declaration

@interface NSURLSessionWebSocketTask : NSURLSessionTask

Overview

NSURLSessionWebSocketTask is a concrete subclass of NSURLSessionTask that provides a message-oriented transport protocol over TCP and TLS in the form of WebSocket framing. It follows the WebSocket Protocol defined in RFC 6455.

You create a NSURLSessionWebSocketTask with either a ws: or wss: URL. When creating the task, you can also provide a list of protocols to advertise during the handshake phase. Once the handshake completes, your app receives notifications through the session’s delegate.

You send data with sendMessage:completionHandler: and receive data with receiveMessageWithCompletionHandler:. The task performs reads and writes asynchronously, and allows you to send and receive messages that contain both binary frames and UTF-8 encoded text frames. The task enqueues any reads or writes you perform prior to the handshake’s completion, and executes them after the handshake completes.

NSURLSessionWebSocketTask supports redirection and authentication like other types of tasks do, using the methods in NSURLSessionTaskDelegate. The WebSocket task calls the redirection and authentication delegate methods prior to completing the handshake. The WebSocket task also supports cookies, by storing cookies to the session configuration’s HTTPCookieStorage, and attaches cookies to outgoing HTTP handshake requests.

Topics

Sending and Receiving Data

- sendMessage:completionHandler:

Sends a WebSocket message, receiving the result in a completion handler.

- receiveMessageWithCompletionHandler:

Reads a WebSocket message once all the frames of the message are available.

maximumMessageSize

The maximum number of bytes to buffer before the receive call fails with an error.

Sending Ping Frames

- sendPingWithPongReceiveHandler:

Sends a ping frame from the client side, with a closure to receive the pong from the server endpoint.

Closing the Connection

- cancelWithCloseCode:reason:

Sends a close frame with the given close code and optional close reason.

closeCode

A code that indicates the reason a connection closed.

NSURLSessionWebSocketCloseCode

A code that indicates why a WebSocket connection closed.

closeReason

A block of data that provides further information about why a connection closed.

Relationships

Inherits From

See Also

Adding WebSocket Tasks to a Session

- webSocketTaskWithURL:

Creates a WebSocket task for the provided URL.

- webSocketTaskWithRequest:

Creates a WebSocket task for the provided URL request.

- webSocketTaskWithURL:protocols:

Creates a WebSocket task given a URL and an array of protocols.

NSURLSessionWebSocketDelegate

A protocol that defines methods that URL session instances call on their delegates to handle task-level events specific to WebSocket tasks.