QWebSocket类

成员函数文档

[explicit] QWebSocket::QWebSocket(const QString &origin = QString(), QWebSocketProtocol::Version version = QWebSocketProtocol::VersionLatest, QObject *parent = nullptr)

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

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

[override virtual noexcept] QWebSocket::~QWebSocket()

销毁 QWebSocket。如果套接字仍然打开，则关闭套接字，并释放任何使用的资源。

void QWebSocket::abort()

中断当前套接字并重置套接字。与 close 不同，此函数立即关闭套接字，弃置写入缓冲区中的任何挂起数据。

[signal] void QWebSocket::aboutToClose()

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

另请参阅：close。

[信号，自6.2版本开始] void QWebSocket::alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QWebSocket 在接收到来自对等方的警报消息时会发出此信号。 level 提示警报是致命的还是警告。 type 提供了发送警报的原因代码。当可用时，警报消息的文本描述将包含在 description 中。

此函数是在 Qt 6.2 版本中引入的。

另请参阅：alertSent()，QSsl::AlertLevel 和 QSsl::AlertType。

[信号，自6.2版本开始] void QWebSocket::alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

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

此函数是在 Qt 6.2 版本中引入的。

另请参阅：alertReceived()，QSsl::AlertLevel 和 QSsl::AlertType。

[信号，自6.6版本开始] void QWebSocket::authenticationRequired(QAuthenticator *authenticator)

当服务器需要身份验证时，会发出此信号。此时，必须使用所需的详细信息来填充 authenticator 对象，以允许身份验证并继续连接。

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

此函数是在 Qt 6.6 版本中引入的。

另请参阅：QAuthenticator。

[信号] void QWebSocket::binaryFrameReceived(const QByteArray &frame, bool isLastFrame)

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

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

另请参阅：textFrameReceived。

[信号] void QWebSocket::binaryMessageReceived(const QByteArray &message)

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

另请参阅textMessageReceived().

qint64 QWebSocket::bytesToWrite() const

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

另请参阅flush.

[信号] void QWebSocket::bytesWritten(qint64 bytes)

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

另请参阅：close。

[槽] void QWebSocket::close(QWebSocketProtocol::CloseCode closeCode = QWebSocketProtocol::CloseCodeNormal, const QString &reason = QString())

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

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

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

返回指示为什么关闭套接字的代码。

另请参阅QWebSocketProtocol::CloseCode 和 closeReason().

QString QWebSocket::closeReason() const

返回关闭套接字的原因。

另请参阅closeCode().

[信号] void QWebSocket::connected()

在成功建立连接时发出。一旦套接字连接并握手成功，连接即为成功建立。

另请参阅open() 和 disconnected().

[自 6.2 版以来] void QWebSocket::continueInterruptedHandshake()

如果一个应用程序在接收到handshakeInterruptedOnError()信号后仍然想要建立一个握手，它必须调用此函数。此调用必须从与信号关联的槽函数中进行。信号-槽连接必须是直接的。

此函数是在 Qt 6.2 版本中引入的。

另请参阅handshakeInterruptedOnError() 和 QSslConfiguration::setHandshakeMustInterruptOnError。

[信号] void QWebSocket::disconnected()

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

另请参阅close() 和 connected。

QAbstractSocket::SocketError QWebSocket::error() const

返回最后发生的错误类型

另请参阅errorString。

[信号，自6.5起] void QWebSocket::errorOccurred(QAbstractSocket::SocketError error)

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

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

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

此功能自 Qt 6.5 中引入。

另请参阅error() 和 errorString。

QString QWebSocket::errorString() const

返回最后发生的错误的可读描述

另请参阅error。

bool QWebSocket::flush()

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

[信号，自6.2起] void QWebSocket::handshakeInterruptedOnError(const QSslError &error)

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

此函数是在 Qt 6.2 版本中引入的。

另请参阅continueInterruptedHandshake、sslErrors 和 QSslConfiguration::setHandshakeMustInterruptOnError。

[自6.4起] QWebSocketHandshakeOptions QWebSocket::handshakeOptions() const

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

此函数自 Qt 6.4 版本引入。

[槽] void QWebSocket::ignoreSslErrors()

此槽函数告诉 QWebSocket 忽略在 QWebSocket 握手阶段出现的错误，并继续连接。如果您想在握手阶段出现错误时继续连接，则必须调用此槽函数，或者将其连接到 sslErrors() 槽，或者在握手阶段之前。如果您不调用此槽，无论是响应错误还是握手之前，连接将在发出 sslErrors() 信号后被断开。

另请参阅：sslErrors、QSslSocket::ignoreSslErrors 和 QNetworkReply::ignoreSslErrors。

void QWebSocket::ignoreSslErrors(const QList<QSslError> &errors)

这是一个重载的函数。

此方法告诉 QWebSocket 忽略由 errors 指定的错误。

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

QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem"));
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QWebSocket socket;
socket.ignoreSslErrors(expectedSslErrors);
socket.open(QUrl(QStringLiteral("wss://myserver.at.home")));

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

另请参阅：sslErrors。

bool QWebSocket::isValid() const

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

QHostAddress QWebSocket::localAddress() const

返回本地地址

quint16 QWebSocket::localPort() const

返回本地端口号

const QMaskGenerator *QWebSocket::maskGenerator() const

返回当前用于此 QWebSocket 的掩码生成器。

另请参阅：setMaskGenerator。

quint64 QWebSocket::maxAllowedIncomingFrameSize() const

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

另请参阅：setMaxAllowedIncomingFrameSize。

quint64 QWebSocket::maxAllowedIncomingMessageSize() const

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

另请参阅：setMaxAllowedIncomingMessageSize。

[静态] quint64 QWebSocket::maxIncomingFrameSize()

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

[静态] quint64 QWebSocket::maxIncomingMessageSize()

返回此WebSocket实现支持的接收WebSocket消息的最大大小。

[静态] quint64 QWebSocket::maxOutgoingFrameSize()

返回此WebSocket实现支持的发送WebSocket帧的最大大小。

[槽函数] void QWebSocket::open(const QUrl &url)

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

如果url包含换行符（\r\n），则错误信号将产生带有QAbstractSocket::ConnectionRefusedError错误类型的错误。

[槽函数] void QWebSocket::open(const QNetworkRequest &request)

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

request的url将被用来打开WebSocket连接。请求中存在的头部将被发送到服务器，包括WebSocket握手所需的一些头部。

[槽函数，自6.4版本起] void QWebSocket::open(const QUrl &url, const QWebSocketHandshakeOptions &options)

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

如果url包含换行符（\r\n），则错误信号将产生带有QAbstractSocket::ConnectionRefusedError错误类型的错误。

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

此函数自 Qt 6.4 版本引入。

[槽函数，自6.4版本起] void QWebSocket::open(const QNetworkRequest &request, const QWebSocketHandshakeOptions &options)

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

request的url将被用来打开WebSocket连接。请求中存在的头部将被发送到服务器，包括WebSocket握手所需的一些头部。

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

此函数自 Qt 6.4 版本引入。

QString QWebSocket::origin() const

返回当前源。

quint64 QWebSocket::outgoingFrameSize() const

返回发送WebSocket帧的最大大小。

另请参阅setOutgoingFrameSize().

QAbstractSocket::PauseModes QWebSocket::pauseMode() const

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

另请参阅setPauseMode().

QHostAddress QWebSocket::peerAddress() const

返回对等方地址。

QString QWebSocket::peerName() const

返回对等方的名称。

quint16 QWebSocket::peerPort() const

返回对等端口的值

[信号，自6.2版本起] void QWebSocket::peerVerifyError(const QSslError &error)

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

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

此函数是在 Qt 6.2 版本中引入的。

另请参阅：sslErrors。

[槽函数] void QWebSocket::ping(const QByteArray &payload = QByteArray())

向服务器发送ping请求以表明连接仍然存活。可以发送额外的payload作为ping消息的一部分。

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

另请参阅：pong。

[信号] void QWebSocket::pong(quint64 elapsedTime, const QByteArray &payload)

在接收到关于先前ping的pong消息时发出。☞ elapsedTime包含往返时间（毫秒），payload包含与ping一起发送的任意负载。

另请参阅：ping。

[信号] void QWebSocket::preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)

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

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

另请参阅：QSslPreSharedKeyAuthenticator和QSslSocket::preSharedKeyAuthenticationRequired。

QNetworkProxy QWebSocket::proxy() const

返回当前配置的代理

另请参阅：setProxy。

[信号] void QWebSocket::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)

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

参阅QAuthenticator和QNetworkProxy。

qint64 QWebSocket::readBufferSize() const

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

参阅setReadBufferSize。

[信号] void QWebSocket::readChannelFinished()

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

另请参阅：close。

QNetworkRequest QWebSocket::request() const

返回打开此套接字所使用或将要使用的请求。

QUrl QWebSocket::requestUrl() const

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

QString QWebSocket::resourceName() const

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

void QWebSocket::resume()

在套接字上继续数据传输。此方法应在套接字已设置为在接收到通知时暂停并且已接收到通知之后使用。目前唯一支持的告警是sslErrors。如果套接字未暂停则调用此方法，则结果将是未定义的行为。

参见pauseMode()和setPauseMode。

qint64 QWebSocket::sendBinaryMessage(const QByteArray &data)

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

参阅sendTextMessage。

qint64 QWebSocket::sendTextMessage(const QString &message)

以文本消息的形式通过套接字发送指定的message，并返回实际发送的字节数。

参阅sendBinaryMessage。

void QWebSocket::setMaskGenerator(const QMaskGenerator *maskGenerator)

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

参阅maskGenerator。

void QWebSocket::setMaxAllowedIncomingFrameSize(quint64 maxAllowedIncomingFrameSize)

设置允许接收的最大WebSocket帧大小为maxAllowedIncomingFrameSize。如果接收到的帧超过此限制，则对端将被断开连接。有效范围是0到maxIncomingFrameSize()，默认为maxIncomingFrameSize()。此函数的目的是防止虚拟内存耗尽。

另请参阅maxAllowedIncomingFrameSize。

void QWebSocket::setMaxAllowedIncomingMessageSize(quint64 maxAllowedIncomingMessageSize)

设置允许接收的最大WebSocket消息大小为maxAllowedIncomingMessageSize。如果接收到的消息超过此限制，则对端将被断开连接。有效范围是0到maxIncomingMessageSize()，默认为maxIncomingMessageSize()。此函数的目的是防止虚拟内存耗尽。

另请参阅maxAllowedIncomingMessageSize。

void QWebSocket::setOutgoingFrameSize(quint64 outgoingFrameSize)

设置输出WebSocket帧的最大大小为outgoingFrameSize。有效范围是0到maxOutgoingFrameSize()，默认为512kB。此函数的目的是适应接收方允许的最大帧大小。

另请参阅outgoingFrameSize。

void QWebSocket::setPauseMode(QAbstractSocket::PauseModes pauseMode)

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

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

另请参阅pauseMode和resume。

void QWebSocket::setProxy(const QNetworkProxy &networkProxy)

设置代理为networkProxy

另请参阅proxy。

void QWebSocket::setReadBufferSize(qint64 size)

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

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

另请参阅 readBufferSize。

void QWebSocket::setSslConfiguration(const QSslConfiguration &sslConfiguration)

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

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

另请参阅 sslConfiguration。

QSslConfiguration QWebSocket::sslConfiguration() const

返回套接字的 SSL 配置状态。套接字的默认 SSL 配置是使用默认的密钥、默认的 CA 证书、无本地私钥或证书。SSL 配置还包含可能随时更改的字段。

另请参阅 setSslConfiguration。

[信号] void QWebSocket::sslErrors(const QList<QSslError> &errors)

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

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

QAbstractSocket::SocketState QWebSocket::state() const

返回套接字的当前状态。

[信号] void QWebSocket::stateChanged(QAbstractSocket::SocketState state)

每当 QWebSocket 的状态更改时都会发出此信号。参数state是新的状态。

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

另请参阅 state。

[since 6.4] QString QWebSocket::subprotocol() const

返回所使用的 WebSocket 协议。

此函数自 Qt 6.4 版本引入。

[信号] void QWebSocket::textFrameReceived(const QString &frame, bool isLastFrame)

每当接收文本帧时，会发出此信号。变量 frame 包含数据，而变量 isLastFrame 标示这是完整消息的最后一个帧。

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

另请参阅 binaryFrameReceived().

[信号] void QWebSocket::textMessageReceived(const QString &message)

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

另请参阅 binaryMessageReceived().

QWebSocketProtocol::Version QWebSocket::version() const

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