starscream

Starscream 是一个符合 WebSocket (RFC 6455) 规范的 Swift 库。

特性

导入框架

首先是导入框架。请参阅安装说明，了解如何将框架添加到您的项目中。

import Starscream

连接到 WebSocket 服务器

导入后，您可以打开与 WebSocket 服务器的连接。请注意，socket 最好作为属性，这样它就不会在设置后立即被释放。

var request = URLRequest(url: URL(string: "https://:8080")!)
request.timeoutInterval = 5
socket = WebSocket(request: request)
socket.delegate = self
socket.connect()

连接后，您可以使用委托或闭包来处理 WebSocket 事件。

从 WebSocket 接收数据

didReceive 在一个易于处理的枚举中接收所有 WebSocket 事件。

func didReceive(event: WebSocketEvent, client: WebSocket) {
	switch event {
	case .connected(let headers):
		isConnected = true
		print("websocket is connected: \(headers)")
	case .disconnected(let reason, let code):
		isConnected = false
		print("websocket is disconnected: \(reason) with code: \(code)")
	case .text(let string):
		print("Received text: \(string)")
	case .binary(let data):
		print("Received data: \(data.count)")
	case .ping(_):
		break
	case .pong(_):
		break
	case .viabilityChanged(_):
		break
	case .reconnectSuggested(_):
		break
	case .cancelled:
		isConnected = false
	case .error(let error):
		isConnected = false
		handleError(error)
        case .peerClosed:
               break
	}
}

它的闭包是

socket.onEvent = { event in
	switch event {
		// handle events just like above...
	}
}

写入 WebSocket

写入二进制帧

writeData 方法为您提供了一种将 Data (二进制) 数据发送到服务器的简单方法。

socket.write(data: data) //write some Data over the socket!

写入字符串帧

writeString 方法与 writeData 相同，但发送的是文本/字符串。

socket.write(string: "Hi Server!") //example on how to write text over the socket!

写入 ping 帧

writePing 方法与 write 相同，但发送的是 ping 控制帧。

socket.write(ping: Data()) //example on how to write a ping control frame over the socket!

写入 pong 帧

writePong 方法与 writePing 相同，但发送的是 pong 控制帧。

socket.write(pong: Data()) //example on how to write a pong control frame over the socket!

Starscream 会自动响应传入的 ping 控制帧，因此您无需手动发送 pong。

但是，如果出于某种原因您需要控制此过程，您可以禁用 respondToPingWithPong 来关闭自动 ping 响应。

socket.respondToPingWithPong = false //Do not automaticaly respond to incoming pings with pongs.

在大多数情况下，您不需要这样做。

断开连接

disconnect 方法执行您所期望的操作并关闭套接字。

socket.disconnect()

如果需要，disconnect 方法还可以发送自定义关闭代码。

socket.disconnect(closeCode: CloseCode.normal.rawValue)

自定义标头、协议和超时

您可以覆盖默认的 websocket 标头，添加您自己的自定义标头并设置超时

var request = URLRequest(url: URL(string: "ws://:8080/")!)
request.timeoutInterval = 5 // Sets the timeout for the connection
request.setValue("someother protocols", forHTTPHeaderField: "Sec-WebSocket-Protocol")
request.setValue("14", forHTTPHeaderField: "Sec-WebSocket-Version")
request.setValue("chat,superchat", forHTTPHeaderField: "Sec-WebSocket-Protocol")
request.setValue("Everything is Awesome!", forHTTPHeaderField: "My-Awesome-Header")
let socket = WebSocket(request: request)

SSL Pinning

Starscream 也支持 SSL Pinning。

允许自签名证书

var request = URLRequest(url: URL(string: "ws://:8080/")!)
let pinner = FoundationSecurity(allowSelfSigned: true) // don't validate SSL certificates
let socket = WebSocket(request: request, certPinner: pinner)

TODO：更新关于如何将证书和公钥加载到应用程序包，使用内置 pinner 和 TrustKit 的文档。

压缩扩展

Starscream 支持压缩扩展 (RFC 7692)。默认情况下启用压缩，但是，只有服务器也支持它时才会使用压缩。 您可以通过添加 compressionHandler 来启用压缩。

var request = URLRequest(url: URL(string: "ws://:8080/")!)
let compression = WSCompression()
let socket = WebSocket(request: request, compressionHandler: compression)

如果您的应用程序正在传输已压缩、随机或其他不可压缩的数据，则应禁用压缩。

自定义队列

调用委托方法时，可以指定自定义队列。 默认情况下，使用 DispatchQueue.main，因此所有委托方法调用都在主线程上运行。 重要的是要注意，所有 WebSocket 处理都在后台线程上完成，只有在修改队列时才会更改委托方法调用。 实际处理始终在后台线程上进行，不会暂停您的应用程序。

socket = WebSocket(url: URL(string: "ws://:8080/")!, protocols: ["chat","superchat"])
//create a custom queue
socket.callbackQueue = DispatchQueue(label: "com.vluxe.starscream.myapp")

示例项目

查看 examples 目录中的 SimpleTest 项目，了解如何设置与 WebSocket 服务器的简单连接。

要求

Starscream 适用于 iOS 8/10.10 或更高版本，支持 CocoaPods/框架。 要在以 iOS 7 为目标的项目中使用 Starscream，您必须将所有 Swift 文件直接包含在您的项目中。

安装

Swift 包管理器

Swift 包管理器是一种用于自动化 Swift 代码分发的工具，并且已集成到 swift 编译器中。

设置好 Swift 包后，添加 Starscream 作为依赖项就像将其添加到 Package.swift 的 dependencies 值一样简单。

dependencies: [
    .package(url: "https://github.com/daltoniam/Starscream.git", from: "4.0.6")
]

CocoaPods

请查看 cocoapods.org 上的 入门 选项卡。

要在您的项目中使用 Starscream，请将以下 'Podfile' 添加到您的项目

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'
use_frameworks!

pod 'Starscream', '~> 4.0.6'

然后运行

pod install

Carthage

查看 Carthage 文档，了解如何添加安装。 Starscream 框架已经设置了共享 schemes。

Carthage 安装

您可以使用以下命令使用 Homebrew 安装 Carthage

$ brew update
$ brew install carthage

要使用 Carthage 将 Starscream 集成到您的 Xcode 项目中，请在您的 Cartfile 中指定它

github "daltoniam/Starscream" >= 4.0.6

其他

只需获取该框架（通过 git 子模块或另一个包管理器）。

将 Starscream.xcodeproj 添加到您的 Xcode 项目。 完成后，在您的“构建阶段”中，将 Starscream.framework 添加到您的“将二进制文件与库链接”阶段。

添加复制框架阶段

如果您在 OSX 应用程序中或在物理 iOS 设备上运行此应用程序，则需要确保将 Starscream.framework 添加到您的应用程序包中。 为此，在 Xcode 中，通过单击蓝色项目图标导航到目标配置窗口，然后在侧边栏中的“Targets”标题下选择应用程序目标。 在该窗口顶部的选项卡栏中，打开“Build Phases”面板。 展开“Link Binary with Libraries”组，然后添加 Starscream.framework。 单击面板左上角的 + 按钮，然后选择“New Copy Files Phase”。 将此新阶段重命名为“Copy Frameworks”，将“Destination”设置为“Frameworks”，并分别添加 Starscream.framework。

待办事项

许可证

Starscream 采用 Apache v2 许可证。

联系

Dalton Cherry

Austin Cherry