QWebSocket Class

成员函数文档

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

使用给定的origin 、要使用的协议的version 以及parent 创建一个新的QWebSocket。

客户端的origin 应符合RFC 6454的规范。（对于非网页浏览器客户端，origin 并非必需（参见RFC 6455）。）origin 中不得包含换行符，否则连接将在握手阶段立即终止。

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

销毁QWebSocket 。如果套接字仍处于打开状态，则将其关闭，并释放所有已占用的资源。

void QWebSocket::abort()

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

[signal] void QWebSocket::aboutToClose()

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

另请参阅 close()。

[signal, since 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 。

[signal, since 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 。

[signal, since 6.6] void QWebSocket::authenticationRequired(QAuthenticator *authenticator)

当服务器需要身份验证时，会发出此信号。此时必须在authenticator 对象中填写所需的详细信息，以便进行身份验证并继续建立连接。

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

此函数在 Qt 6.6 中引入。

另请参阅 QAuthenticator 。

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

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

该信号可用于逐帧处理大型消息，而无需等待完整消息到达。

另请参阅 textFrameReceived()。

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

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

另请参阅 textMessageReceived()。

qint64 QWebSocket::bytesToWrite() const

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

另请参阅 flush 。

[signal] void QWebSocket::bytesWritten(qint64 bytes)

每当向套接字写入数据负载时，都会触发此信号。bytes 参数的值即为该负载中写入的字节数。

另请参阅 close()。

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

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

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

QWebSocketProtocol::CloseCode QWebSocket::closeCode() const

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

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

QString QWebSocket::closeReason() const

返回套接字被关闭的原因。

另请参阅 closeCode()。

[signal] void QWebSocket::connected()

当连接成功建立时触发。当套接字已连接且握手成功时，即视为连接成功建立。

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

[since 6.2] void QWebSocket::continueInterruptedHandshake()

如果某个应用程序希望在接收到handshakeInterruptedOnError()信号后仍继续完成握手过程，则必须调用此函数。此调用必须从与该信号关联的槽函数中进行。信号与槽的连接必须是直接的。

该函数在 Qt 6.2 中引入。

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

[signal] void QWebSocket::disconnected()

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

另请参阅 close() 和connected()。

QAbstractSocket::SocketError QWebSocket::error() const

返回上次发生的错误类型

另请参阅 errorString()。

[signal, since 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 就会自动开始发送数据。

[signal, since 6.2] void QWebSocket::handshakeInterruptedOnError(const QSslError &error)

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

该函数在 Qt 6.2 中引入。

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

[since 6.4] QWebSocketHandshakeOptions QWebSocket::handshakeOptions() const

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

该函数在 Qt 6.4 中引入。

[slot] void QWebSocket::ignoreSslErrors()

此插槽指示QWebSocket 在QWebSocket 的握手阶段忽略错误并继续建立连接。若希望即使在握手阶段发生错误仍继续建立连接，则必须调用此插槽——既可以通过连接到sslErrors()的插槽调用，也可以在握手阶段开始前调用。 若未在响应错误或握手阶段开始前调用此槽，则在发出sslErrors() 信号后，连接将被断开。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        webSocket, qOverload<>(&QWebSocket::ignoreSslErrors));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        webSocket, [receiver = webSocket]() { receiver->ignoreSslErrors(); });

另请参阅 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()。

[static] quint64 QWebSocket::maxIncomingFrameSize()

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

[static] quint64 QWebSocket::maxIncomingMessageSize()

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

[static] quint64 QWebSocket::maxOutgoingFrameSize()

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

[slot] void QWebSocket::open(const QNetworkRequest &request)

使用给定的request 建立 WebSocket 连接。

将使用request 该 URL 来建立 WebSocket 连接。请求中包含的头部信息将与 WebSocket 握手所需的头部信息一同，在升级请求中发送至服务器。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        webSocket, qOverload(&QWebSocket::open));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        webSocket, [receiver = webSocket](const QNetworkRequest &request) { receiver->open(request); });

[slot] void QWebSocket::open(const QUrl &url)

使用给定的url 建立 WebSocket 连接。

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

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        webSocket, qOverload(&QWebSocket::open));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        webSocket, [receiver = webSocket](const QUrl &url) { receiver->open(url); });

[slot, since 6.4] void QWebSocket::open(const QNetworkRequest &request, const QWebSocketHandshakeOptions &options)

使用给定的request 和options 建立 WebSocket 连接。

将使用request 该 URL 来建立 WebSocket 连接。请求中存在的头部信息将与 WebSocket 握手所需的头部信息一同，在升级请求中发送至服务器。

WebSocket 握手的相关附加选项（例如子协议）可在options 中指定。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        webSocket, qOverload(&QWebSocket::open));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        webSocket, [receiver = webSocket](const QNetworkRequest &request, const QWebSocketHandshakeOptions &options) { receiver->open(request, options); });

该函数于 Qt 6.4 中引入。

[slot, since 6.4] void QWebSocket::open(const QUrl &url, const QWebSocketHandshakeOptions &options)

使用给定的url 和options 建立 WebSocket 连接。

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

WebSocket 握手过程的其他选项（例如子协议）可在options 中指定。

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        webSocket, qOverload(&QWebSocket::open));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        webSocket, [receiver = webSocket](const QUrl &url, const QWebSocketHandshakeOptions &options) { receiver->open(url, options); });

该函数于 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

返回 peerName

quint16 QWebSocket::peerPort() const

返回对等端口

[signal, since 6.2] void QWebSocket::peerVerifyError(const QSslError &error)

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

该信号可在出现问题时为您提供早期预警。通过连接此信号，您可以在握手完成之前，在已连接槽（connected slot）内手动选择断开连接。如果不采取任何行动，QWebSocket 将继续发出QWebSocket::sslErrors() 信号。

该函数在 Qt 6.2 中引入。

另请参阅 sslErrors()。

[slot] void QWebSocket::ping(const QByteArray &payload = QByteArray())

向服务器发送ping请求，以表明连接仍处于活动状态。可在ping消息中附加payload 。

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

另请参阅 pong()。

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

当收到对先前 ping 请求的响应（pong 消息）时触发。elapsedTime 包含往返时间（以毫秒为单位），payload 包含随 ping 请求一并发送的可选有效载荷。

另请参阅 ping()。

[signal] void QWebSocket::preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)

如果 SSL/TLS 握手协商出一个 PSK 加密套件，则会发出此信号，因此随后需要进行 PSK 身份验证。

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

另请参阅 QSslPreSharedKeyAuthenticator 和QSslSocket::preSharedKeyAuthenticationRequired()。

QNetworkProxy QWebSocket::proxy() const

返回当前配置的代理

另请参阅 setProxy()。

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

当使用需要身份验证的proxy 时，可能会触发此信号。此时，可向authenticator 对象填充所需的详细信息，以完成身份验证并继续连接。

另请参阅 QAuthenticator 和QNetworkProxy 。

qint64 QWebSocket::readBufferSize() const

返回套接字所使用的读取缓冲区的字节大小。

另请参阅 setReadBufferSize()。

[signal] 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()。

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

QWebSocket 在 SSL 握手完成后发出此信号，以指示在确定对端身份的过程中发生了一个或多个错误。这些错误通常表明QWebSocket 无法安全地识别对端。除非采取任何措施，否则在发出此信号后，连接将被断开。 若您希望在出现错误的情况下继续建立连接，必须在连接到该信号的槽内调用QWebSocket::ignoreSslErrors()。若您需要在后续访问错误列表，可调用 sslErrors()（不带参数）。

errors 包含一个或多个错误，导致QWebSocket 无法验证对端的身份。

QAbstractSocket::SocketState QWebSocket::state() const

返回套接字的当前状态。

[signal] 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 中引入。

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

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

该信号可用于逐帧处理大型消息，而无需等待完整消息到达。

另请参阅 binaryFrameReceived()。

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

每当收到一条短信时，都会发出此信号。message 包含收到的短信内容。

另请参阅 binaryMessageReceived()。

QWebSocketProtocol::Version QWebSocket::version() const

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