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 字节以内。由于其中两个用于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() 信号发出后中断。

另请参阅 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 网址将用于打开 WebSocket 连接。请求中的头信息将连同 WebSocket 握手所需的头信息一起在升级请求中发送给服务器。

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

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

如果 url 包含换行符 (\r\n), 则会发出错误信号，错误类型为QAbstractSocket::ConnectionRefusedError 。

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

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

request 网址将用于打开 WebSocket 连接。请求中的头信息将连同 WebSocket 握手所需的头信息一起在升级请求中发送给服务器。

WebSocket 握手的其他选项（如子协议）可在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 中指定。

此函数在 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

当出现问题时，该信号会向你提供早期提示。通过连接到该信号，您可以在握手完成前从连接的插槽内手动选择中断连接。如果不采取任何行动，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)

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 握手后发出此信号，表明在建立对等方身份时发生了一个或多个错误。这些错误通常表明 无法安全地识别对等方。除非采取任何措施，否则连接将在此信号发出后中断。如果想在发生错误的情况下继续连接，则必须在连接到此信号的槽内调用 () 。如果以后需要访问错误列表，可以调用 sslErrors()（不带参数）。QWebSocket QWebSocket::ignoreSslErrors

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

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