NSURLSessionWebSocketTask

NSURLSessionWebSocketTask是一项允许客户端连接到支持
WebSocket的服务器的任务。该任务将执行HTTP握手以升级连接，
并且一旦WebSocket握手成功，客户端就可以读取和写入
将由框架使用WebSocket协议进行构架的消息。

一、NSURLSessionWebSocketTask 定义

/* WebSocket关闭代码遵循RFC中给出的关闭代码 */
typedef NS_ENUM(NSInteger, NSURLSessionWebSocketCloseCode)
{
    NSURLSessionWebSocketCloseCodeInvalid =                             0,
    NSURLSessionWebSocketCloseCodeNormalClosure =                    1000,
    NSURLSessionWebSocketCloseCodeGoingAway =                        1001,
    NSURLSessionWebSocketCloseCodeProtocolError =                    1002,
    NSURLSessionWebSocketCloseCodeUnsupportedData =                  1003,
    NSURLSessionWebSocketCloseCodeNoStatusReceived =                 1005,
    NSURLSessionWebSocketCloseCodeAbnormalClosure =                  1006,
    NSURLSessionWebSocketCloseCodeInvalidFramePayloadData =          1007,
    NSURLSessionWebSocketCloseCodePolicyViolation =                  1008,
    NSURLSessionWebSocketCloseCodeMessageTooBig =                    1009,
    NSURLSessionWebSocketCloseCodeMandatoryExtensionMissing =        1010,
    NSURLSessionWebSocketCloseCodeInternalServerError =              1011,
    NSURLSessionWebSocketCloseCodeTLSHandshakeFailure =              1015,
} API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));

/*
  *可以使用ws或wss url创建WebSocket任务。 客户也可以提供
  *它希望在WebSocket握手阶段发布的协议的列表。
  *握手成功完成后，将通过可选的委托通知客户端。
  *握手完成前排队的所有读写将排队，并且
  *一旦hanshake成功执行。 在握手完成之前，可以调用客户端进行处理
  *使用与NSURLSessionTask相同的委托进行重定向或身份验证。 WebSocket任务还将提供
  *支持cookie，并将cookie存储到会话中的cookie存储中，并将cookie附加到
  *传出的HTTP握手请求。
  */
API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
@interface NSURLSessionWebSocketTask : NSURLSessionTask

/*发送WebSocket消息。 如果发生错误，任何未完成的工作也将失败。
  *请注意，完成处理程序的调用不会
  *确保远端仅接收了所有字节
  *它们已被写入内核。
  */
- (void)sendMessage:(NSURLSessionWebSocketMessage *)message completionHandler:(void (^)(NSError * _Nullable error))completionHandler;

/*一旦消息的所有框架可用，便读取WebSocket消息。
  *如果在缓冲帧时达到了最大消息大小，则receiveMessage调用将出错
  *并且所有未完成的工作也将失败，从而导致任务结束。
  */
- (void)receiveMessageWithCompletionHandler:(void (^)(NSURLSessionWebSocketMessage* _Nullable message, NSError * _Nullable error))completionHandler;

/*从客户端发送ping帧。 客户端时调用pongReceiveHandler
  *从服务器端点接收到一个Pong。 如果连接丢失或接收前发生错误
  *来自端点的pong，pongReceiveHandler块将被错误调用。
  *注意-pongReceiveHandler将始终按照ping的发送顺序进行调用。
  */
- (void)sendPingWithPongReceiveHandler:(void (^)(NSError* _Nullable error))pongReceiveHandler;

/*发送具有给定closeCode的关闭帧。 发送关闭帧时可以提供可选原因。
  *简单地在任务上调用取消将导致发送取消帧而没有任何原因。
  */
- (void)cancelWithCloseCode:(NSURLSessionWebSocketCloseCode)closeCode reason:(NSData * _Nullable)reason;

@property NSInteger maximumMessageSize; /* 错误输出前要缓冲的最大字节数。 这包括连续帧中所有字节的总和。 如果达到此值，接收数据将出错 */
@property (readonly) NSURLSessionWebSocketCloseCode closeCode; /* 可以随时查询任务的结束代码。 当任务未关闭时，它将被设置为NSURLSessionWebSocketCloseCodeInvalid */
@property (nullable, readonly, copy) NSData *closeReason; /* 任何时候都可以查询任务的紧迫原因。 nil值表示没有closeReason或任务仍在运行 */


- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;

@end

二、NSURLSessionWebSocketMessage 定义

typedef NS_ENUM(NSInteger, NSURLSessionWebSocketMessageType) {
    NSURLSessionWebSocketMessageTypeData = 0,
    NSURLSessionWebSocketMessageTypeString = 1,
} API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));

/*客户端可以创建一个WebSocket消息对象，该对象将传递给发送调用
  *，并将通过接听电话发送。 可以使用数据或字符串初始化该消息。
  *如果使用数据初始化，则字符串属性将为nil，反之亦然。
  */
API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
@interface NSURLSessionWebSocketMessage : NSObject

/* 创建数据类型的消息 */
- (instancetype)initWithData:(NSData *)data NS_DESIGNATED_INITIALIZER;

/* 创建一个字符串类型的消息 */
- (instancetype)initWithString:(NSString *)string NS_DESIGNATED_INITIALIZER;

@property (readonly) NSURLSessionWebSocketMessageType type;
@property (nullable, readonly, copy) NSData *data;
@property (nullable, readonly, copy) NSString *string;


- (instancetype)init NS_UNAVAILABLE;
+ (instancetype)new NS_UNAVAILABLE;

@end

三、NSURLSessionWebSocketTask 创建

/* 给定URL创建一个WebSocket任务。 给定的URL必须具有ws或wss方案。 */
- (NSURLSessionWebSocketTask *)webSocketTaskWithURL:(NSURL *)url API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));

/*根据给定的url和协议数组创建一个WebSocket任务。 该协议将在WebSocket握手中用于
  *与服务器协商首选协议
  *注意-协议不会影响WebSocket框架。 有关该协议的更多详细信息，请阅读WebSocket RFC。
  */
- (NSURLSessionWebSocketTask *)webSocketTaskWithURL:(NSURL *)url protocols:(NSArray<NSString *>*)protocols API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));

/*根据请求创建一个WebSocket任务。 可以修改请求属性，任务将在HTTP握手阶段使用该属性。
  *想要添加自定义协议的客户端可以通过使用密钥Sec-WebSocket-Protocol直接添加标头来实现
  *和它们希望与服务器协商的协议的逗号分隔列表。 客户端提供的自定义HTTP标头在与服务器握手时将保持不变。
  */
- (NSURLSessionWebSocketTask *)webSocketTaskWithRequest:(NSURLRequest *)request API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));


- (instancetype)init API_DEPRECATED("Please use +[NSURLSession sessionWithConfiguration:] or other class methods to create instances", macos(10.9,10.15), ios(7.0,13.0), watchos(2.0,6.0), tvos(9.0,13.0));
+ (instancetype)new API_DEPRECATED("Please use +[NSURLSession sessionWithConfiguration:] or other class methods to create instances", macos(10.9,10.15), ios(7.0,13.0), watchos(2.0,6.0), tvos(9.0,13.0));

四、NSURLSessionWebSocketTask 代理

API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
@protocol NSURLSessionWebSocketDelegate <NSURLSessionTaskDelegate>
@optional

/*表示WebSocket握手成功，并且连接已升级到webSockets。
  *它还将提供握手中选择的协议。 如果握手失败，则不会调用此委托。
  */
- (void)URLSession:(NSURLSession *)session webSocketTask:(NSURLSessionWebSocketTask *)webSocketTask didOpenWithProtocol:(NSString * _Nullable) protocol;

/*表示WebSocket已从服务器端点接收到关闭帧。
  *如果服务器选择发送，则关闭代码和关闭原因可由委托人提供
  *此信息在封闭框中
*/
- (void)URLSession:(NSURLSession *)session webSocketTask:(NSURLSessionWebSocketTask *)webSocketTask didCloseWithCode:(NSURLSessionWebSocketCloseCode)closeCode reason:(NSData * _Nullable)reason;

@end