class QWebSocket#

实现了使用WebSocket协议通信的TCP套接字。 更多…

Inheritance diagram of PySide6.QtWebSockets.QWebSocket

概要#

方法#

槽函数#

信号#

静态函数#

注意

本文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译中存在问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 上创建工单来告诉我们。

详细描述#

WebSocket 是一种网络技术，它通过单个 TCP 连接提供全双工通信通道。WebSocket 协议于 2011 年由 IETF 标准化为 RFC 6455。QWebSocket 可以在客户端应用程序和服务器应用程序中使用。

此类是从 QAbstractSocket 模拟的。

QWebSocket 目前不支持 WebSocket 扩展。

QWebSocket 只支持 WebSocket 协议的 13 版本，如 RFC 6455 中所述。

注意

某些代理不了解 Web 播手握手期间使用的某些 HTTP 标头。在这种情况下，非安全 WebSocket 连接将失败。缓解此问题的最佳方法是使用安全连接进行 WebSocket。

警告

为了生成掩码，此 WebSocket 实现使用合理的加密 QRandomGenerator::global()->generate() 函数。有关良好掩码重要性的更多信息，请参阅 《使用和利润自言自语》by Lin-Shung Huang 等人的文章（“Talking to Yourself for Fun and Profit”）。上述文档中提及的攻击的最佳防御措施是使用 QWebSocket 在安全连接（ws://）上（avoid 3rd party script access to QWebSocket in your application）。

另请参阅

QWebSocket 客户端示例

__init__([origin=""[, version=QWebSocketProtocol.VersionLatest[, parent=None]]])#
参数:

创建一个新的 QWebSocket，带有指定的 origin、要使用的协议 version 和 parent。

客户端的 origin 按照在 RFC 6454 中指定。 （对于非网页浏览器客户端，不需要 origin，见 RFC 6455）。origin 中不能包含换行符，否则在握手阶段，连接将被立即终止。

注意

目前仅支持 V13（ RFC 6455）。

abort()#

终止当前套接字并重置套接字。与 close() 不同，此函数会立即关闭套接字，丢弃任何待处理的写入缓冲区中的数据。

aboutToClose()#

当套接字即将关闭时，会发出此信号。如果您需要在套接字关闭之前执行操作（例如，如果您有一个单独的缓冲区中的数据需要写入设备），请连接此信号。

另请参阅

close()

alertReceived(level, type, description)#
参数:

QWebSocket 在从对等方接收到警报消息时发出此信号。 level 表示警报是致命的还是警告。 type 是解释为何发送警报的代码。当警报消息的文本描述可用时，它将提供在 description 中。

注意

此信号主要用于信息性和调试目的，无需在应用程序中处理。如果警报是致命的，则底层后端将处理它并关闭连接。

注意

并非所有后端都支持此功能。

另请参阅

alertSent() AlertType

alertSent(level, type, description)#
参数:

QWebSocket 在接收到来自对等方的警告消息时发出该信号。level 描述了它是警告还是致命错误。type 提供了警告消息的代码。如果可用，文本描述将提供给 description。

注意

此信号主要用于信息提示，可用于调试目的，通常不需要应用程序采取任何行动。

注意

并非所有后端都支持此功能。

另请参阅

alertReceived() AlertType

authenticationRequired(authenticator)#
参数:

authenticator – QAuthenticator

当服务器要求进行身份验证时，将发出此信号。然后需要用所需的详细信息填写authenticator对象，以便允许身份验证并继续连接。

如果您知道服务器可能需要身份验证，则可以在初始 QUrl 上设置用户名和密码，使用 QUrl::setUserName 和 QUrl::setPassword。即使使用提供的凭据，QWebSocket 也仍会尝试连接 一次，而不使用提供的凭据。

注意

无法使用队列连接连接到该信号，因为如果信号返回时身份验证器没有填写新信息，连接将失败。

另请参阅

QAuthenticator

binaryFrameReceived(frame, isLastFrame)#
参数:

只要接收到二进制帧，就会发出此信号。frame 包含数据，而 isLastFrame 表示这是完整消息的最后一帧。

可以使用该信号按帧处理大型消息，而不是等待完整消息到达。

另请参阅

textFrameReceived()

binaryMessageReceived(message)#
参数:

message – QByteArray

只要接收到二进制消息，就会发出此信号。message 包含接收到的字节数据。

另请参阅

textMessageReceived()

bytesToWrite()#
返回类型：

整数

返回等待写入的字节数。当控制权返回到事件循环或调用 flush() 函数时，将写入这些字节。

另请参阅

flush

bytesWritten(bytes)#
参数:

bytes – 整数

每当将数据负载写入套接字时，都会发出此信号。`bytes` 参数设置为在此有效负载中写入的字节数。

注意

此信号对安全和非安全 WebSocket 都有相同的意义。与 QSslSocket 不同，只有当加密数据实际写入时，bytesWritten() 才会发出（参见 QSslSocket::encryptedBytesWritten()）。

另请参阅

close()

close([closeCode=QWebSocketProtocol.CloseCodeNormal[, reason=""]])#
参数:

  • closeCode – CloseCode

  • reason – 字符串

优雅地使用给定的 closeCode 和 reason 关闭套接字。

在关闭套接字之前，将刷新写缓冲区中任何数据。`closeCode` 是表示关闭原因的 CloseCode，reason 则更详细地描述关闭的原因。所有控制帧，包括关闭帧，都限于 125 字节。由于其中两个字用于 closeCode，因此 reason 的最大长度为 123！如果 reason 超过此限制，它将被截断。

closeCode()#
返回类型：

CloseCode

返回表示套接字关闭原因的代码。

另请参阅

CloseCode closeReason()

closeReason()#
返回类型：

字符串

返回套接字关闭的原因。

另请参阅

closeCode()

connected()#

当连接成功建立时发出。连接成功建立时，套接字已连接，握手成功。

另请参阅

open() disconnected()

继续中断后的握手()#

如果应用程序想在收到 handshakeInterruptedOnError() 信号后仍然完成握手，必须调用此函数。此调用必须从附加到信号的槽函数中进行。信号-槽连接必须是直接的。

disconnected()#

当套接字断开连接时发出。

另请参阅

close() connected()

error()#
返回类型：

套接字错误

返回最后一次发生的错误类型

另请参阅

errorString()

error(error)
参数:

error – SocketError

注意

此函数已弃用。

请使用 errorOccurred (QAbstractSocket::SocketError error)。

errorOccurred(error)#
参数:

error – SocketError

在发生错误后发出此信号。

error 参数描述了发生的错误类型。

QAbstractSocket::SocketError 不是一个已注册的元类型，因此对于队列连接，您必须使用 Q_DECLARE_METATYPE() 和 qRegisterMetaType() 进行注册。

另请参阅

error() errorString()

errorString()#
返回类型：

字符串

返回最后一次发生的最后一个错误的可读文本描述

另请参阅

error()

flush()#
返回类型：

bool

该函数尽可能地将内部写缓冲区的内容写入底层网络套接字，而不会阻塞。如果写入了一些数据，则此函数返回 true；否则返回 false。如果需要立即开始发送缓冲数据，请调用此函数。成功写入的字节数取决于操作系统。在大多数情况下，不需要调用此函数，因为一旦控制权回到事件循环，QWebSocket 将自动开始发送数据。

handshakeInterruptedOnError(error)#
参数:

错误 – QSslError

如果发现证书验证错误并且启用了 QSslConfiguration 的早期错误报告，QWebSocket 会发出此信号。应用程序应检查 error 并决定是否要继续握手，或终止并向对等发送警报消息。信号-槽连接必须是直接的。

handshakeOptions()#
返回类型：

QWebSocketHandshakeOptions

返回打开此套接字时使用的握手选项。

ignoreSslErrors()#

此槽指示 QWebSocket 在 QWebSocket 的握手阶段忽略错误并继续连接。如果您希望在握手阶段即使发生错误也要继续连接，您必须从连接到 sslErrors() 的槽或握手阶段之前调用此槽。如果您不调用此槽，无论是响应错误还是之手握手之前，连接将在 sslErrors() 信号发出后被断开。

警告

务必始终让用户检查由 sslErrors() 信号报告的错误，并且在用户确认可以进行下一步之前才调用此方法。如果出现意外错误，应终止连接。如果不检查实际错误就调用此方法，可能会对您应用程序的安全性造成风险。请谨慎使用！

另请参阅

sslErrors() ignoreSslErrors()

ignoreSslErrors(errors)
参数:

errors –QSslError 的列表

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

这是一个重载函数。

此方法告诉 QWebSocket 忽略 errors 中给出的错误。

注意，您可以在SSL错误中设置预期的证书：如果要连接到使用自签名证书的服务器，请考虑以下代码片段

cert = QSslCertificate.fromPath("server-certificate.pem")
error = QSslError(QSslError.SelfSignedCertificate, cert.at(0))
expectedSslErrors = QList()
expectedSslErrors.append(error)
socket = QWebSocket()
socket.ignoreSslErrors(expectedSslErrors)
socket.open(QUrl("wss://myserver.at.home"))

对该函数的多次调用将替换之前调用中传入的错误列表。您可以通过调用该函数并传入空列表来清除要忽略的错误列表。

另请参阅

sslErrors()

isValid()
返回类型：

bool

如果套接字已准备好进行读写，则返回 true；否则返回 false。

localAddress()
返回类型：

QHostAddress

返回本地地址

localPort()
返回类型：

整数

返回本地端口

maskGenerator()
返回类型：

QMaskGenerator

返回当前此 QWebSocket 正在使用的掩码生成器。

另请参阅

setMaskGenerator()

maxAllowedIncomingFrameSize()
返回类型：

整数

返回允许接收的WebSocket帧的最大大小。

maxAllowedIncomingMessageSize()
返回类型：

整数

返回允许接收的WebSocket消息的最大大小。

static maxIncomingFrameSize()
返回类型：

整数

返回对此WebSocket实现允许接收的WebSocket帧支持的最大大小。

static maxIncomingMessageSize()#
返回类型：

整数

返回此WebSocket实现所支持的最大入站WebSocket消息大小。

static maxOutgoingFrameSize()#
返回类型：

整数

返回此WebSocket实现所支持的最大出站WebSocket帧大小。

open(url, options)#
参数:

使用给定的 url 和 options 打开WebSocket连接。

如果url包含换行符（\r\n），则将发出错误信号，错误类型为 QAbstractSocket::ConnectionRefusedError。

可以通过 options 指定WebSocket握手的其他选项，如子协议。

open(url)
参数:

url – QUrl

使用给定的 url 打开WebSocket连接。

如果url包含换行符（\r\n），则将发出错误信号，错误类型为 QAbstractSocket::ConnectionRefusedError。

open(request)
参数:

request – QNetworkRequest

使用给定的 request 打开WebSocket连接。

request 的url将用于打开WebSocket连接。请求中现有的头部将作为升级请求发送到服务器，连同WebSocket握手所需的头部。

open(request, options)
参数:

使用给定的 request 和 options 打开WebSocket连接。

request 的url将用于打开WebSocket连接。请求中现有的头部将作为升级请求发送到服务器，连同WebSocket握手所需的头部。

可以通过 options 指定WebSocket握手的其他选项，如子协议。

origin()#
返回类型：

字符串

返回当前源。

outgoingFrameSize()#
返回类型：

整数

返回出站WebSocket帧的最大大小。

另请参阅

setOutgoingFrameSize()

pauseMode()#
返回类型：

组合了 PauseMode

返回此套接字的暂停模式。

另请参阅

setPauseMode()

peerAddress()#
返回类型：

QHostAddress

返回对等方地址

peerName()#
返回类型：

字符串

返回 peerName

peerPort()#
返回类型：

整数

返回对等方端口 peerport

peerVerifyError(error)#
参数:

错误 – QSslError

QWebSocket 在 SSL 握手过程中可以多次发出此信号，在加密建立之前，以指示在建立对等方身份时发生了错误。错误通常表明 QWebSocket 无法安全地识别对等方。

此信号可以为您提供早期错误指示。通过连接到此信号，您可以选择在握手完成之前，在连接的槽内部手动断开连接。如果不采取任何行动，QWebSocket 将继续发出 sslErrors() .

另请参阅

sslErrors()

ping([payload=QByteArray()])#
参数:

payload – QByteArray

向服务器发送 ping 消息以指示连接仍然活跃。可以发送额外的 payload 附加到 ping 消息上。

payload 的大小不能超过 125。如果大于 125 字节，则 payload 被截断为 125 字节。

注意

QWebSocket 和 QWebSocketServer 会内部处理 ping 请求，这意味着它们自动向对等方发送 pong 响应。

另请参阅

pong()

pong(elapsedTime, payload)#
参数:

在收到对之前的ping的响应时触发。`elapsedTime`包含往返时间（以毫秒为单位），而`payload`包含与ping一起发送的可选有效负载。

另请参阅

ping()

preSharedKeyAuthenticationRequired(authenticator)#
参数:

authenticator – QSslPreSharedKeyAuthenticator

如果SSL/TLS握手协商了PSK加密套件，则发出此信号，因此需要PSK身份验证。

在使用PSK时，客户端必须发送一个有效的身份和一个有效的预共享密钥到服务器，以便SSL握手能继续进行。应用程序可以通过连接到该信号的slot提供此信息，根据需要填写传过的`authenticator`对象。

注意

忽略此信号或未能提供所需的凭据将导致握手失败，因此连接将被终止。

注意

`authenticator`对象由WebSocket拥有，应用程序不能删除它。

另请参阅

preSharedKeyAuthenticationRequired()

proxy()#
返回类型：

QNetworkProxy

返回当前配置的代理

另请参阅

setProxy()

proxyAuthenticationRequired(proxy, pAuthenticator)#
参数:

当使用需要身份验证的代理时，可以发出此信号。然后可以填写`authenticator`对象，添加所需的详细信息，以允许身份验证并继续连接。

注意

无法使用队列连接连接到该信号，因为如果信号返回时身份验证器没有填写新信息，连接将失败。

另请参阅

QAuthenticatorQNetworkProxy

readBufferSize()#
返回类型：

整数

返回由套接字使用的读取缓冲区的大小（以字节为单位）。

另请参阅

setReadBufferSize()

readChannelFinished()#

当在此设备中关闭输入（读取）流时发出此信号。它一旦检测到关闭即被触发。

另请参阅

close()

request()#
返回类型：

QNetworkRequest

返回用于打开此套接字或即将用于打开此套接字的请求。

requestUrl()#
返回类型：

QUrl

返回套接字连接到的或将要连接到的URL。

resourceName()#
返回类型：

字符串

返回当前访问的资源名称。

resume()#

继续在套接字上传输数据。应该在套接字被设置为接收通知时暂停，并且已经接收到通知后使用此方法。当前唯一支持的通告是 sslErrors() 。如果套接字没有暂停而调用此方法，则结果是不确定的。

sendBinaryMessage(data)#
参数:

data – QByteArray

返回类型：

整数

通过套接字将给定的 data 作为二进制消息发送，并返回实际发送的字节数。

另请参阅

sendTextMessage()

sendTextMessage(message)#
参数:

message – str

返回类型：

整数

通过套接字将给定的 message 作为文本消息发送，并返回实际发送的字节数。

另请参阅

sendBinaryMessage()

setMaskGenerator(maskGenerator)
参数:

maskGenerator – QMaskGenerator

将用于创建掩码的生成器设置为 maskGenerator。默认的 QWebSocket 生成器可以通过提供 nullptr 来重置。掩码生成器可以在任何时候更改，即使在连接打开时也可以。

另请参阅

maskGenerator()

setMaxAllowedIncomingFrameSize(maxAllowedIncomingFrameSize)#
参数:

maxAllowedIncomingFrameSize – int

将允许接收的 WebSocket 框架的最大大小设置为 maxAllowedIncomingFrameSize。如果接收到的框架超过此限制，则对端会被断开连接。接受的范围是 0 和 maxIncomingFrameSize() 之间，默认为 maxIncomingFrameSize() 。此函数的目的是为了避免耗尽虚拟内存。

setMaxAllowedIncomingMessageSize(maxAllowedIncomingMessageSize)#
参数:

maxAllowedIncomingMessageSize – int

设置接收的WebSocket消息的最大允许大小为maxAllowedIncomingMessageSize。如果接收到的消息超过此限制，则对端将被断开连接。接受的值在0和maxIncomingMessageSize()之间，默认为maxIncomingMessageSize()。该函数的目的是为了避免耗尽虚拟内存。

setOutgoingFrameSize(outgoingFrameSize)#
参数:

outgoingFrameSize – int

设置发送的WebSocket帧的最大大小为outgoingFrameSize。接受的值在0和maxOutgoingFrameSize()之间，默认为512kB。该函数的目的是以适应接收方的最大允许帧大小。

另请参阅

outgoingFrameSize()

setPauseMode(pauseMode)#
参数:

pauseMode – PauseMode组合

控制是否在接收到通知时暂停。 pauseMode 参数指定了在哪些条件下应该暂停套接字。

目前唯一支持的通告是 sslErrors()。如果设置为 PauseOnSslErrors，套接字中的数据传输将被暂停，并且需要通过调用 resume() 显式启用。默认情况下，此选项设置为 PauseNever。此选项必须在连接到服务器之前调用，否则将产生未定义的行为。

另请参阅

pauseMode() resume()

setProxy(networkProxy)#
参数:

networkProxy – QNetworkProxy

将代理设置为 networkProxy

另请参阅

proxy()

setReadBufferSize(size)#
参数:

size – int

将 QWebSocket 的内部读取缓冲区大小设为 size 字节。

如果缓冲区大小被限制为一定大小，QWebSocket 不会缓存超过此大小的数据。例外情况下，缓冲区大小为0表示读取缓冲区是无限的，所有传入的数据都会被缓存。这是默认设置。此选项在您只在特定时间点读取数据（例如，在实时流应用程序中）或者想要防止接收过多数据（这可能导致您的应用程序耗尽内存）时很有用。

另请参阅

readBufferSize()

setSslConfiguration(sslConfiguration)#
参数:

sslConfiguration – QSslConfiguration

将套接字的SSL配置设置为sslConfiguration的内容。

此函数将本地证书、加密算法、私钥和CA证书设置为存储在sslConfiguration中。无法设置SSL状态相关字段。

另请参阅

sslConfiguration()

sslConfiguration()#
返回类型：

QSslConfiguration

返回套接字的SSL配置状态。套接字的默认SSL配置是使用默认的加密算法、默认的CA证书、没有本地私钥或证书。SSL配置还包含可能会更改的字段，而无需通知。

另请参阅

setSslConfiguration()

sslErrors(errors)#
参数:

errors –QSslError 的列表

QWebSocket在完成SSL握手后发出此信号，表示在验证对等方身份时发生了一个或多个错误。这些错误通常表明QWebSocket无法安全地识别对等方。除非采取任何行动，否则发出此信号后将会断开连接。如果您想要尽管发生错误仍然继续连接，您必须从连接到此信号的槽内部调用ignoreSslErrors()。如果您需要稍后访问错误列表，您可以通过不带参数调用sslErrors()来实现。

errors 包含一个或多个错误，这些错误阻止了 QWebSocket 验证对方的身份。

注意

当连接到此信号或在调用 ignoreSslErrors() 时，不能使用 Qt::QueuedConnection，即使调用 ignoreSslErrors() 也没有效果。

state()#
返回类型：

SocketState

返回当前套接字的状态。

stateChanged(state)#
参数:

state – SocketState

每当 QWebSocket 的状态发生变化时，就会发射此信号。参数 state 是新的状态。

注意

在服务器握手成功后，将发出 QAbstractSocket::ConnectedState。

QAbstractSocket::SocketState 不是一个注册的元类型，因此对于队列连接，您必须使用 Q_REGISTER_METATYPE() 和 qRegisterMetaType() 来注册它。

另请参阅

state()

subprotocol()#
返回类型：

字符串

返回当前使用的 WebSocket 协议。

textFrameReceived(frame, isLastFrame)#
参数:

  • frame – str

  • isLastFrame – bool

接收文本帧时会发射此信号。参数 frame 包含数据，而 isLastFrame 指示这是完整消息的最后帧。

可以使用该信号按帧处理大型消息，而不是等待完整消息到达。

另请参阅

binaryFrameReceived()

textMessageReceived(message)#
参数:

message – str

接收到文本消息时会发射此信号。参数 message 包含接收到的文本。

version()#
返回类型：

Version

返回当前套接字正在使用的版本。