实现交谈 WebSocket 协议的 TCP 套接字。 更多...
| 头： | #include <QWebSocket> |
| qmake: | QT += websockets |
| Since: | Qt 5.3 |
| 继承： | QObject |
该类在 Qt 5.3 引入。
| QWebSocket (const QString & origin = QString(), QWebSocketProtocol::Version version = QWebSocketProtocol::VersionLatest, QObject * parent = nullptr) | |
| virtual | ~QWebSocket () override |
| void | abort () |
| qint64 | bytesToWrite () const |
| QWebSocketProtocol::CloseCode | closeCode () const |
| QString | closeReason () const |
| QAbstractSocket::SocketError | error () const |
| QString | errorString () const |
| bool | flush () |
| void | ignoreSslErrors (const QList<QSslError> & errors ) |
| bool | isValid () const |
| QHostAddress | localAddress () const |
| quint16 | localPort () const |
| const QMaskGenerator * | maskGenerator () const |
| quint64 | maxAllowedIncomingFrameSize () const |
| quint64 | maxAllowedIncomingMessageSize () const |
| QString | origin () const |
| quint64 | outgoingFrameSize () const |
| QAbstractSocket::PauseModes | pauseMode () const |
| QHostAddress | peerAddress () const |
| QString | peerName () const |
| quint16 | peerPort () const |
| QNetworkProxy | proxy () const |
| qint64 | readBufferSize () const |
| QNetworkRequest | request () const |
| QUrl | requestUrl () const |
| QString | resourceName () const |
| void | resume () |
| qint64 | sendBinaryMessage (const QByteArray & data ) |
| qint64 | sendTextMessage (const QString & message ) |
| void | setMaskGenerator (const QMaskGenerator * maskGenerator ) |
| void | setMaxAllowedIncomingFrameSize (quint64 maxAllowedIncomingFrameSize ) |
| void | setMaxAllowedIncomingMessageSize (quint64 maxAllowedIncomingMessageSize ) |
| void | setOutgoingFrameSize (quint64 outgoingFrameSize ) |
| void | setPauseMode (QAbstractSocket::PauseModes pauseMode ) |
| void | setProxy (const QNetworkProxy & networkProxy ) |
| void | setReadBufferSize (qint64 size ) |
| void | setSslConfiguration (const QSslConfiguration & sslConfiguration ) |
| QSslConfiguration | sslConfiguration () const |
| QAbstractSocket::SocketState | state () const |
| QWebSocketProtocol::Version | version () const |
| void | close (QWebSocketProtocol::CloseCode closeCode = QWebSocketProtocol::CloseCodeNormal, const QString & reason = QString()) |
| void | ignoreSslErrors () |
| void | open (const QNetworkRequest & request ) |
| void | open (const QUrl & url ) |
| void | ping (const QByteArray & payload = QByteArray()) |
| void | aboutToClose () |
| void | binaryFrameReceived (const QByteArray & frame , bool isLastFrame ) |
| void | binaryMessageReceived (const QByteArray & message ) |
| void | bytesWritten (qint64 bytes ) |
| void | connected () |
| void | disconnected () |
| void | error (QAbstractSocket::SocketError error ) |
| void | pong (quint64 elapsedTime , const QByteArray & payload ) |
| void | preSharedKeyAuthenticationRequired (QSslPreSharedKeyAuthenticator * authenticator ) |
| void | proxyAuthenticationRequired (const QNetworkProxy & proxy , QAuthenticator * authenticator ) |
| void | readChannelFinished () |
| void | sslErrors (const QList<QSslError> & errors ) |
| void | stateChanged (QAbstractSocket::SocketState state ) |
| void | textFrameReceived (const QString & frame , bool isLastFrame ) |
| void | textMessageReceived (const QString & message ) |
| quint64 | maxIncomingFrameSize () |
| quint64 | maxIncomingMessageSize () |
| quint64 | maxOutgoingFrameSize () |
WebSocket 是通过单 TCP 连接提供全双工通信通道的 Web 技术。WebSocket 协议由 IETF 标准化为 RFC 6455 在 2011 年。QWebSocket 可用于客户端应用程序和服务器应用程序两者。
此类被建模后于 QAbstractSocket .
QWebSocket 目前不支持 WebSocket 扩展 and WebSocket 子协议 .
QWebSocket 只支持第 13 版的 WebSocket 协议, 如提纲于 RFC 6455 .
注意： 有些代理不理解某些 HTTP 所用 Header (头) 在 WebSocket 握手期间。在此情况下，不安全 WebSocket 连接将失败。缓解此问题的最佳方式是使用 WebSocket 通过安全连接。
警告： 要生成屏蔽，此实现的 WebSocket 使用相当安全的 QRandomGenerator::global ()->generate() 函数。有关良好屏蔽重要性的更多信息，见 黄林顺等著的 "和自己交谈的乐趣和收益" 。阻止上文提及的攻击的最佳措施是使用 QWebSocket 通过安全连接 ( wss:// )。一般而言，始终小心不要让第 3 方脚本访问应用程序 QWebSocket。
另请参阅 QAbstractSocket , QTcpSocket ，和 QWebSocket 客户端范例 .
创建新的 QWebSocket 采用给定 origin ， version 要使用的协议和 parent .
The origin 的客户端作为指定在 RFC 6454 。( origin 不需要对于非 Web 浏览器客户端 (见 RFC 6455 ))。 origin 不能包含换行符，否则在握手阶段将立即中止连接。
注意： 目前仅 V13 ( RFC 6455 ) 被支持
[signal]
void
QWebSocket::
aboutToClose
()
此信号被发射当套接字即将关闭时。连接此信号若在套接字关闭之前有操作需要履行 (如：若单独缓冲中有数据需要写入设备)。
另请参阅 close ().
[signal]
void
QWebSocket::
binaryFrameReceived
(const
QByteArray
&
frame
,
bool
isLastFrame
)
此信号被发射每当收到二进制帧。 frame 包含数据和 isLastFrame 指示这是否是完整消息的最后一帧。
此信号可以被用于逐帧处理大消息，而不是等待完整消息的到达。
另请参阅 textFrameReceived ().
[signal]
void
QWebSocket::
binaryMessageReceived
(const
QByteArray
&
message
)
此信号被发射每当收到二进制消息。 message 包含收到的字节。
另请参阅 textMessageReceived ().
[signal]
void
QWebSocket::
bytesWritten
(
qint64
bytes
)
此信号被发射每当已将数据负载写入套接字时。 bytes 自变量是在此负载中写入的设置字节数。
注意： 此信号拥有相同含义，对于安全和非安全 WebSocket。相对于 QSslSocket ，bytesWritten() 才发射当加密数据被有效写入时 (见 QSslSocket::encryptedBytesWritten ()).
另请参阅 close ().
[slot]
void
QWebSocket::
close
(
QWebSocketProtocol::CloseCode
closeCode
= QWebSocketProtocol::CloseCodeNormal, const
QString
&
reason
= QString())
优雅地关闭套接字采用给定 closeCode and reason .
刷新写入缓冲中的任何数据在套接字被关闭之前。 closeCode 是 QWebSocketProtocol::CloseCode 指示关闭的原因，和 reason 更详细描述关闭的原因。所有控制帧，包括关闭帧，被限制为 125 字节。由于其中 2 字节已被用于 closeCode 最大长度的 reason 是 123！若 reason 超过此限制，它将被截取。
[signal]
void
QWebSocket::
connected
()
被发射当连接成功建立时。连接建立成功当套接字被连接且握手成功时。
另请参阅 open () 和 disconnected ().
[signal]
void
QWebSocket::
disconnected
()
发射当套接字已断开连接时。
[signal]
void
QWebSocket::
error
(
QAbstractSocket::SocketError
error
)
此信号发射，在发生错误后。 error 参数描述出现错误的类型。
QAbstractSocket::SocketError 不是注册 Metatype (元类型)，因此，对于队列化连接而言，必须注册它采用 Q_DECLARE_METATYPE () 和 qRegisterMetaType ().
注意： 信号 error 在此类中被重载。通过使用函数指针句法连接到此信号，Qt 提供用于获得如此范例展示的函数指针的方便帮助程序：
connect(webSocket, QOverload<QAbstractSocket::SocketError>::of(&QWebSocket::error), [=](QAbstractSocket::SocketError error){ /* ... */ });
另请参阅 error () 和 errorString ().
[slot]
void
QWebSocket::
ignoreSslErrors
()
此槽告诉 QWebSocket 去忽略错误在 QWebSocket 的握手阶段并继续连接。若想要继续连接即使在握手阶段发生错误，必须调用此槽，或从连接槽到 sslErrors ()，或在握手阶段之前。若在响应出错或握手之前不调用此槽，连接将被丢弃当 sslErrors () 信号已发射。
警告： 确保始终让用户审查报告的错误通过 sslErrors () 信号，且才调用此方法 (当用户确认后继续进行是 OK 的)。若存在意外错误，连接应该被中止。不审查实际错误就调用此方法，很可能会给应用程序带来安全风险。小心使用！
另请参阅 sslErrors (), QSslSocket::ignoreSslErrors ()，和 QNetworkReply::ignoreSslErrors ().
[slot]
void
QWebSocket::
open
(const
QNetworkRequest
&
request
)
打开 WebSocket 连接使用给定 request .
The request URL 将用于打开 WebSocket 连接。请求中存在的 Header (头) 将与 WebSocket 握手所需要的头一起被发送给升级请求服务器。
该函数在 Qt 5.6 引入。
[slot]
void
QWebSocket::
open
(const
QUrl
&
url
)
打开 WebSocket 连接使用给定 url .
若 URL 包含 \r\n 换行符，错误信号将被发射带 QAbstractSocket::ConnectionRefusedError 作为错误类型。
[slot]
void
QWebSocket::
ping
(const
QByteArray
&
payload
= QByteArray())
Ping (乒) 服务器能指示连接仍活着。额外 payload 可以与 Ping 消息一道被发送。
The size of the payload cannot be bigger than 125. If it is larger, the payload 被裁剪到 125 字节。
注意： QWebSocket and QWebSocketServer handles ping requests internally, which means they automatically send back a pong response to the peer.
另请参阅 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 时，客户端必须向服务器发送有效标识和有效 PSK (预共享密钥) 以便 SSL 握手得以继续。应用程序可以在此信号连接的槽中提供此信息，通过填入传递的 authenticator 对象根据需要。
注意： 忽略此信号或未能提供要求证书，将导致握手失败，因此连接将被中止。
注意： The authenticator 对象由 WebSocket 所拥有且不能被删除通过应用程序。
该函数在 Qt 5.8 引入。
另请参阅 QSslPreSharedKeyAuthenticator and QSslSocket::preSharedKeyAuthenticationRequired ().
[signal]
void
QWebSocket::
proxyAuthenticationRequired
(const
QNetworkProxy
&
proxy
,
QAuthenticator
*
authenticator
)
此信号可以被发射当 proxy 要求使用身份验证。 authenticator 然后可以采用所需的详细信息填充对象，以允许身份验证并继续连接。
注意： 使用 QueuedConnection 去连接到此信号是不可能的，因为连接会失败，若身份验证器没有采新信息被填充，当信号返回时。
另请参阅 QAuthenticator and QNetworkProxy .
[signal]
void
QWebSocket::
readChannelFinished
()
此信号被发射当输入 (读取) 流在此设备中被关闭。一检测到正关闭，就会发射它。
另请参阅 close ().
[signal]
void
QWebSocket::
sslErrors
(const
QList
<
QSslError
> &
errors
)
QWebSocket 发射此信号在 SSL 握手之后以指示当建立对等方标识时有发生一个或多个错误。错误通常指示 QWebSocket 无法安全识别对等方。除非采取任何行动，连接将被丢弃在此信号被发射之后。若想要继续连接不管有错误发生，必须调用 QWebSocket::ignoreSslErrors () 从连接到此信号的槽内。若以后需要访问错误列表，可以调用 sslErrors() (不带自变量)。
errors 包含一个或多个错误阻止 QWebSocket 验证对等方身份。
注意： 不可以使用 Qt::QueuedConnection 当连接到此信号时，或调用 QWebSocket::ignoreSslErrors () 没有起作用。
[signal]
void
QWebSocket::
stateChanged
(
QAbstractSocket::SocketState
state
)
此信号发射每当 QWebSocket 的状态改变。 state 参数是新状态。
注意： QAbstractSocket::ConnectedState 被发射在与服务器成功握手之后。
QAbstractSocket::SocketState 不是已注册 Metatype (元类型)，因此对于队列连接，必须注册它采用 Q_REGISTER_METATYPE() 和 qRegisterMetaType ().
另请参阅 state ().
[signal]
void
QWebSocket::
textFrameReceived
(const
QString
&
frame
,
bool
isLastFrame
)
此信号被发射每当收到文本帧时。 frame 包含数据和 isLastFrame 指示这是否是完整消息的最后一帧。
此信号可以被用于逐帧处理大消息，而不是等待完整消息的到达。
另请参阅 binaryFrameReceived ().
[signal]
void
QWebSocket::
textMessageReceived
(const
QString
&
message
)
此信号被发射每当收到文本消息时。 message 包含收到的文本。
另请参阅 binaryMessageReceived ().
[override virtual]
QWebSocket::
~QWebSocket
()
销毁 QWebSocket 。关闭套接字若它仍是打开的，并释放任何使用资源。
中止当前套接字并重置套接字。不像 close ()，此函数立即关闭套接字，丢弃写缓冲中任何待决数据。
返回等待写入的字节数。写入字节当控制回到事件循环或当 flush () 被调用。
该函数在 Qt 5.12 引入。
另请参阅 flush .
返回套接字为什么被关闭的指示代码。
另请参阅 QWebSocketProtocol::CloseCode and closeReason ().
返回套接字为什么被关闭的原因。
另请参阅 closeCode ().
返回最后发生的错误类型
另请参阅 errorString ().
返回人类可读的最后发生的错误的描述
另请参阅 error ().
此函数不阻塞且尽可能多地，把内部缓冲写入到底层网络套接字。若有写入任何数据，此函数返回 true; 否则返回 false。调用此函数若需要 QWebSocket 立即开始发送缓冲数据。成功写入的字节数从属操作系统。在大多数情况下，不需调用此函数，因为 QWebSocket 将开始自动发送数据，一旦控制回到事件循环。
这是重载函数。
此方法告诉 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 ().
返回
true
若套接字已读写就绪；否则返回
false
.
返回本地地址
返回本地端口
返回目前使用的掩码生成器通过此 QWebSocket .
另请参阅 setMaskGenerator ().
返回传入 WebSocket 帧的最大允许尺寸。
该函数在 Qt 5.15 引入。
另请参阅 setMaxAllowedIncomingFrameSize ().
返回传入 WebSocket 消息的最大允许尺寸。
该函数在 Qt 5.15 引入。
另请参阅 setMaxAllowedIncomingMessageSize ().
[static]
quint64
QWebSocket::
maxIncomingFrameSize
()
返回此 WebSocket 实现支持传入的 WebSocket 帧的最大尺寸。
该函数在 Qt 5.15 引入。
[static]
quint64
QWebSocket::
maxIncomingMessageSize
()
返回此 WebSocket 实现支持传入的 WebSocket 消息的最大尺寸。
该函数在 Qt 5.15 引入。
[static]
quint64
QWebSocket::
maxOutgoingFrameSize
()
返回此 WebSocket 实现支持传出的 WebSocket 帧的最大尺寸。
该函数在 Qt 5.15 引入。
返回当前来源。
返回传出 WebSocket 帧的最大尺寸。
该函数在 Qt 5.15 引入。
另请参阅 setOutgoingFrameSize ().
返回此套接字的暂停模式
另请参阅 setPauseMode ().
返回对等方地址
返回对等方名称
返回对等方端口
返回目前配置代理
另请参阅 setProxy ().
返回用于套接字的读取缓冲大小 (以字节为单位)。
另请参阅 setReadBufferSize ().
返回过去 (或将来) 用于打开此套接字的请求。
该函数在 Qt 5.6 引入。
返回套接字已连接或将要连接的 URL。
返回目前访问的资源的名称。
继续在套接字中传输数据。才应该使用此方法仅在套接字被设为当通知时暂停且有收到通知之后。目前唯一支持的通知是 sslErrors ()。调用此方法导致不确定行为若套接字未暂停。
另请参阅 pauseMode () 和 setPauseMode ().
发送给定 data 通过套接字以二进制消息形式，并返回实际发送的字节数。
另请参阅 sendTextMessage ().
发送给定 message 通过套接字以文本消息形式，并返回实际发送的字节数。
另请参阅 sendBinaryMessage ().
把用于创建掩码的生成器设为 maskGenerator 。默认 QWebSocket 生成器可以被重置通过提供 nullptr 。可以随时改变掩码生成器即使连接是打开的。
另请参阅 maskGenerator ().
将传入 WebSocket 帧的最大允许尺寸设为 maxAllowedIncomingFrameSize 。若传入帧超过此限制，对等方将断开连接。接受范围介于 0 到 maxIncomingFrameSize ()，默认为 maxIncomingFrameSize ()。此函数的目的是避免耗尽虚拟内存。
该函数在 Qt 5.15 引入。
另请参阅 maxAllowedIncomingFrameSize ().
把传入 WebSocket 消息的最大允许尺寸设为 maxAllowedIncomingMessageSize 。若传入消息超过此限制，对等方将断开连接。接受范围介于 0 到 maxIncomingMessageSize ()，默认为 maxIncomingMessageSize ()。此函数的目的是避免耗尽虚拟内存。
该函数在 Qt 5.15 引入。
另请参阅 maxAllowedIncomingMessageSize ().
把传出 WebSocket 帧的最大尺寸设为 outgoingFrameSize 。接受范围介于 0 到 maxOutgoingFrameSize ()，默认为 512kB。此函数的目的是为适应接收器允许的最大帧尺寸。
该函数在 Qt 5.15 引入。
另请参阅 outgoingFrameSize ().
控制当收到通知时是否暂停。 pauseMode 参数指定套接字应该被暂停的条件。
目前唯一支持的通知是 sslErrors ()。若设为 PauseOnSslErrors，套接字数据传输将暂停且再次启用需要明确调用 resume ()。默认情况下，此选项被设为 PauseNever。必须调用此选项在连接到服务器之前，否则它将导致未定义行为。
另请参阅 pauseMode () 和 resume ().
把代理设为 networkProxy
另请参阅 proxy ().
设置尺寸为 QWebSocket 的内部读取缓冲到 size 字节。
若缓冲尺寸被限制到某个大小， QWebSocket 不会缓冲超过此尺寸的数据。例外，0 缓冲尺寸意味着读取缓冲是无限的且缓冲所有传入数据。这是默认值。此选项是有用的若仅在某时间点读取数据 (如：在实时流应用程序中)，或者，若希望保护套接字以免接收太多数据 (可能最终导致应用程序内存不足)。
另请参阅 readBufferSize ().
把套接字的 SSL 配置内容设为 sslConfiguration .
此函数把设置的本地证书、密码、私钥及 CA 证书存储在 sslConfiguration 。设置 SSL (安全套接字层) 状态相关字段是不可能的。
另请参阅 sslConfiguration ().
返回套接字的 SSL 配置状态。套接字的默认 SSL 配置是要使用的默认密码、默认 CA 证书，非本地私钥或证书。SSL 配置还包含没有通知可以随时改变的字段。
另请参阅 setSslConfiguration ().
返回套接字的当前状态。
返回目前正在使用的套接字版本。