PySide6.QtWebSockets.QWebSocket¶

class QWebSocket¶

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

概要¶

注意

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

详细描述¶

WebSockets 是一种网络技术，通过单一的 TCP 连接提供全双工通信通道。WebSocket 协议于 2011 年被 IETF 标准化为 RFC 6455。QWebSocket 既可用于客户端应用程序，也可用于服务器应用程序。

这个类是基于QAbstractSocket建模的。

QWebSocket 目前不支持 WebSocket Extensions 。

QWebSocket 仅支持 RFC 6455 中概述的 WebSocket 协议的第13版。

注意

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

警告

为了生成掩码，这个WebSockets的实现使用了相对安全的QRandomGenerator::global()->generate()函数。有关良好掩码重要性的更多信息，请参阅“Talking to Yourself for Fun and Profit” by Lin-Shung Huang et al。针对上述文档中提到的攻击的最佳防护措施是在安全连接（wss://）上使用QWebSocket。一般来说，始终要小心不要让第三方脚本访问应用程序中的QWebSocket。

另请参阅

QWebSocket客户端示例

__init__([origin=""[, version=QWebSocketProtocol.VersionLatest[, parent=None]]])¶

Parameters:

origin – str
版本 – Version
parent – QObject

创建一个新的QWebSocket，使用给定的origin、协议的version和parent。

客户端的origin如RFC 6454中所述。（非网页浏览器客户端不需要origin（参见RFC 6455））。origin不能包含换行符，否则在握手阶段连接将立即中止。

注意

目前仅支持V13（RFC 6455）

abort()¶

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

aboutToClose()¶

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

另请参阅

close()

alertReceived(level, type, description)¶

Parameters:

level – AlertLevel
type – AlertType
描述 – str

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

注意

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

注意

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

另请参阅

alertSent() AlertType

alertSent(level, type, description)¶

Parameters:

level – AlertLevel
type – AlertType
描述 – str

QWebSocket 如果向对等方发送了警报消息，则会发出此信号。level 描述它是警告还是致命错误。type 提供警报消息的代码。当警报消息的文本描述可用时，它会在 description 中提供。

注意

此信号主要是信息性的，可用于调试目的，通常不需要应用程序采取任何操作。

注意

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

另请参阅

alertReceived() AlertType

authenticationRequired(authenticator)¶

Parameters:: 认证器 – QAuthenticator

当服务器需要认证时，会发出此信号。然后必须填写authenticator对象所需的详细信息，以允许认证并继续连接。

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

注意

无法使用QueuedConnection连接到此信号，因为如果信号返回时验证器未填充新信息，连接将失败。

另请参阅

QAuthenticator

binaryFrameReceived(frame, isLastFrame)¶

Parameters:

frame – QByteArray
isLastFrame – 布尔值

每当接收到二进制帧时，都会发出此信号。frame 包含数据，isLastFrame 指示这是否是完整消息的最后一帧。

此信号可用于逐帧处理大消息，而不是等待完整消息到达。

另请参阅

textFrameReceived()

binaryMessageReceived(message)¶

Parameters:: 消息 – QByteArray

每当接收到二进制消息时，都会发出此信号。message 包含接收到的字节。

另请参阅

textMessageReceived()

bytesToWrite()¶

Return type:: 整数

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

另请参阅

flush

bytesWritten(bytes)¶

Parameters:: bytes – 整数

每次向套接字写入数据负载时都会发出此信号。bytes参数设置为在此负载中写入的字节数。

注意

此信号对于安全和非安全的WebSockets具有相同的含义。与QSslSocket不同，bytesWritten()仅在加密数据实际写入时发出（参见QSslSocket::encryptedBytesWritten()）。

另请参阅

close()

close([closeCode=QWebSocketProtocol.CloseCodeNormal[, reason=""]])¶

Parameters:

closeCode – CloseCode
reason – str

优雅地关闭具有给定closeCode和reason的套接字。

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

closeCode()¶

Return type:: CloseCode

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

另请参阅

CloseCode closeReason()

closeReason()¶

Return type:: 字符串

返回套接字关闭的原因。

另请参阅

closeCode()

connected()¶

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

另请参阅

open() disconnected()

continueInterruptedHandshake()¶

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

另请参阅

handshakeInterruptedOnError() setHandshakeMustInterruptOnError()

disconnected()¶

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

另请参阅

close() connected()

error()¶

Return type:: SocketError

返回上次发生的错误类型

另请参阅

errorString()

error(error)

Parameters:: 错误 – SocketError

注意

此函数已弃用。

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

errorOccurred(error)¶

Parameters:: 错误 – SocketError

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

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

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

另请参阅

error() errorString()

errorString()¶

Return type:: 字符串

返回最近发生错误的人类可读描述

另请参阅

error()

flush()¶

Return type:: 布尔

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

handshakeInterruptedOnError(error)¶

Parameters:: 错误 – QSslError

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

另请参阅

continueInterruptedHandshake() sslErrors() setHandshakeMustInterruptOnError()

handshakeOptions()¶

Return type:: QWebSocketHandshakeOptions

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

ignoreSslErrors()¶

这个插槽告诉 QWebSocket 在 QWebSocket 的握手阶段忽略错误并继续连接。如果您希望在握手阶段发生错误时仍然继续连接，那么您必须调用这个插槽，无论是从连接到 sslErrors() 的插槽中调用，还是在握手阶段之前调用。如果您不调用这个插槽，无论是响应错误还是在握手之前，连接将在 sslErrors() 信号发出后被断开。

警告

请务必始终让用户检查由sslErrors()信号报告的错误，并且只有在用户确认继续操作后才调用此方法。如果出现意外错误，应中止连接。在不检查实际错误的情况下调用此方法很可能会对您的应用程序构成安全风险。请谨慎使用！

另请参阅

sslErrors() ignoreSslErrors()

ignoreSslErrors(errors)

Parameters:: 错误 – .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()¶

Return type:: 布尔

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

localAddress()¶

Return type:: QHostAddress

返回本地地址

localPort()¶

Return type:: 整数

返回本地端口

maskGenerator()¶

Return type:: QMaskGenerator

返回当前由这个QWebSocket使用的掩码生成器。

另请参阅

setMaskGenerator()

maxAllowedIncomingFrameSize()¶

Return type:: 整数

返回传入的websocket帧的最大允许大小。

另请参阅

setMaxAllowedIncomingFrameSize()

maxAllowedIncomingMessageSize()¶

Return type:: 整数

返回传入的websocket消息的最大允许大小。

另请参阅

setMaxAllowedIncomingMessageSize()

static maxIncomingFrameSize()¶

Return type:: 整数

返回此websocket实现所支持的传入websocket帧的最大大小。

static maxIncomingMessageSize()¶

Return type:: 整数

返回此websocket实现支持的传入websocket消息的最大大小。

static maxOutgoingFrameSize()¶

Return type:: 整数

返回此websocket实现支持的最大传出websocket帧大小。

open(request)¶

Parameters:: 请求 – QNetworkRequest

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

request URL 将用于打开 WebSocket 连接。请求中的头部信息将与 WebSocket 握手所需的头部信息一起发送到服务器。

open(url)

Parameters:: url – QUrl

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

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

open(request, options)

Parameters:

请求 – QNetworkRequest
options – QWebSocketHandshakeOptions

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

request URL 将用于打开 WebSocket 连接。请求中的标头将与 WebSocket 握手所需的标头一起发送到服务器。

可以在options中指定WebSocket握手的其他选项，例如子协议。

open(url, options)

Parameters:

url – QUrl
options – QWebSocketHandshakeOptions

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

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

可以在options中指定WebSocket握手的其他选项，例如子协议。

origin()¶

Return type:: 字符串

返回当前来源。

outgoingFrameSize()¶

Return type:: 整数

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

另请参阅

setOutgoingFrameSize()

pauseMode()¶

Return type:: PauseMode的组合

返回此套接字的暂停模式

另请参阅

setPauseMode()

peerAddress()¶

Return type:: QHostAddress

返回对等地址

peerName()¶

Return type:: 字符串

返回 peerName

peerPort()¶

Return type:: 整数

返回对等端口

peerVerifyError(error)¶

Parameters:: 错误 – QSslError

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

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

另请参阅

sslErrors()

ping([payload=QByteArray()])¶

Parameters:: payload – QByteArray

向服务器发送ping以指示连接仍然活跃。可以随ping消息一起发送额外的payload。

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

注意

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

另请参阅

pong()

pong(elapsedTime, payload)¶

Parameters:

elapsedTime – int
payload – QByteArray

当接收到一个pong消息作为之前ping的回复时发出。elapsedTime 包含往返时间（以毫秒为单位），payload 包含与ping一起发送的可选负载。

另请参阅

ping()

preSharedKeyAuthenticationRequired(authenticator)¶

Parameters:: 认证器 – QSslPreSharedKeyAuthenticator

如果SSL/TLS握手协商了一个PSK密码套件，则会发出此信号，因此需要PSK认证。

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

注意

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

注意

authenticator 对象由 websocket 拥有，应用程序不得删除它。

另请参阅

preSharedKeyAuthenticationRequired()

proxy()¶

Return type:: QNetworkProxy

返回当前配置的代理

另请参阅

setProxy()

proxyAuthenticationRequired(proxy, pAuthenticator)¶

Parameters:

proxy – QNetworkProxy
pAuthenticator – QAuthenticator

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

注意

无法使用QueuedConnection连接到此信号，因为如果信号返回时验证器未填充新信息，连接将失败。

另请参阅

QAuthenticatorQNetworkProxy

readBufferSize()¶

Return type:: 整数

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

另请参阅

setReadBufferSize()

readChannelFinished()¶

当此设备中的输入（读取）流关闭时，会发出此信号。一旦检测到关闭，就会立即发出信号。

另请参阅

close()

request()¶

Return type:: QNetworkRequest

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

requestUrl()¶

Return type:: QUrl

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

resourceName()¶

Return type:: 字符串

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

resume()¶

继续在套接字上进行数据传输。此方法仅应在套接字被设置为在收到通知时暂停并且已收到通知后使用。当前唯一支持的通知是sslErrors()。如果套接字未暂停，调用此方法将导致未定义的行为。

另请参阅

pauseMode() setPauseMode()

sendBinaryMessage(data)¶

Parameters:: 数据 – QByteArray
Return type:: 整数

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

另请参阅

sendTextMessage()

sendTextMessage(message)¶

Parameters:: 消息 – str
Return type:: 整数

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

另请参阅

sendBinaryMessage()

setMaskGenerator(maskGenerator)¶

Parameters:: maskGenerator – QMaskGenerator

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

另请参阅

maskGenerator()

setMaxAllowedIncomingFrameSize(maxAllowedIncomingFrameSize)¶

Parameters:: maxAllowedIncomingFrameSize – int

设置传入的websocket帧的最大允许大小为maxAllowedIncomingFrameSize。如果传入的帧超过此限制，对等方将被断开连接。可接受的范围在0到maxIncomingFrameSize()之间，默认值为maxIncomingFrameSize()。此函数的目的是避免耗尽虚拟内存。

另请参阅

maxAllowedIncomingFrameSize()

setMaxAllowedIncomingMessageSize(maxAllowedIncomingMessageSize)¶

Parameters:: maxAllowedIncomingMessageSize – int

设置传入的websocket消息的最大允许大小为maxAllowedIncomingMessageSize。如果传入的消息超过此限制，对等方将被断开连接。接受的范围在0到maxIncomingMessageSize()之间，默认值为maxIncomingMessageSize()。此函数的目的是避免耗尽虚拟内存。

另请参阅

maxAllowedIncomingMessageSize()

setOutgoingFrameSize(outgoingFrameSize)¶

Parameters:: outgoingFrameSize – int

设置传出WebSocket帧的最大大小为outgoingFrameSize。可接受的范围是0到maxOutgoingFrameSize()，默认值为512kB。此函数的目的是适应接收器允许的最大帧大小。

另请参阅

outgoingFrameSize()

setPauseMode(pauseMode)¶

Parameters:: pauseMode – PauseMode 的组合

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

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

另请参阅

pauseMode() resume()

setProxy(networkProxy)¶

Parameters:: networkProxy – QNetworkProxy

设置代理为 networkProxy

另请参阅

proxy()

setReadBufferSize(size)¶

Parameters:: size – int

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

如果缓冲区大小限制为某个特定大小，QWebSocket 将不会缓冲超过此大小的数据。例外情况下，缓冲区大小为0意味着读取缓冲区是无限的，所有传入的数据都会被缓冲。这是默认设置。此选项在您仅在特定时间点读取数据（例如，在实时流应用程序中）或您希望保护您的套接字免受接收过多数据的影响时非常有用，这最终可能导致您的应用程序内存不足。

另请参阅

readBufferSize()

setSslConfiguration(sslConfiguration)¶

Parameters:: sslConfiguration – QSslConfiguration

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

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

另请参阅

sslConfiguration()

sslConfiguration()¶

Return type:: QSslConfiguration

返回套接字的SSL配置状态。套接字的默认SSL配置是使用默认的加密算法、默认的CA证书，没有本地私钥或证书。SSL配置还包含一些字段，这些字段可能会随时间变化而不另行通知。

另请参阅

setSslConfiguration()

sslErrors(errors)¶

Parameters:: 错误 – .QSslError 列表

QWebSocket 在SSL握手后发出此信号，表示在建立对等方身份时发生了一个或多个错误。这些错误通常表明 QWebSocket 无法安全地识别对等方。除非采取任何措施，否则在发出此信号后，连接将被断开。如果您希望在发生错误后继续连接，您必须从连接到该信号的槽中调用 ignoreSslErrors()。如果您需要在稍后访问错误列表，您可以调用 sslErrors()（不带参数）。

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

注意

连接到这个信号时不能使用Qt::QueuedConnection，否则调用ignoreSslErrors()将无效。

state()¶

Return type:: SocketState

返回套接字的当前状态。

stateChanged(state)¶

Parameters:: 状态 – SocketState

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

注意

QAbstractSocket::ConnectedState 在与服务器的握手成功后发出。

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

另请参阅

state()

subprotocol()¶

Return type:: 字符串

返回使用的WebSocket协议。

textFrameReceived(frame, isLastFrame)¶

Parameters:

frame – str
isLastFrame – 布尔值

每当接收到文本帧时，都会发出此信号。frame 包含数据，isLastFrame 指示这是否是完整消息的最后一帧。

此信号可用于逐帧处理大消息，而不是等待完整消息到达。

另请参阅

binaryFrameReceived()

textMessageReceived(message)¶

Parameters:: 消息 – str

每当接收到文本消息时，都会发出此信号。message 包含接收到的文本。

另请参阅

binaryMessageReceived()

version()¶

Return type:: 版本

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

PySide6.QtWebSockets.QWebSocket¶

概要¶

方法¶

插槽¶

信号¶

静态函数¶

详细描述¶