实现基于 WebSocket 的服务器。 更多...
| 头： | #include <QWebSocketServer> |
| CMake: |
find_package(Qt6 COMPONENTS WebSockets REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::WebSockets) |
| qmake: | QT += websockets |
| Since: | Qt 5.3 |
| 继承： | QObject |
| enum | SslMode { SecureMode, NonSecureMode } |
| QWebSocketServer (const QString & serverName , QWebSocketServer::SslMode secureMode , QObject * parent = nullptr) | |
| virtual | ~QWebSocketServer () override |
| void | close () |
| QWebSocketProtocol::CloseCode | error () const |
| QString | errorString () const |
| void | handleConnection (QTcpSocket * socket ) const |
| std::chrono::milliseconds | handshakeTimeout () const |
| int | handshakeTimeoutMS () const |
| bool | hasPendingConnections () const |
| bool | isListening () const |
| bool | listen (const QHostAddress & address = QHostAddress::Any, quint16 port = 0) |
| int | maxPendingConnections () const |
| virtual QWebSocket * | nextPendingConnection () |
| void | pauseAccepting () |
| QNetworkProxy | proxy () const |
| void | resumeAccepting () |
| QWebSocketServer::SslMode | secureMode () const |
| QHostAddress | serverAddress () const |
| QString | serverName () const |
| quint16 | serverPort () const |
| QUrl | serverUrl () const |
| void | setHandshakeTimeout (std::chrono::milliseconds msec ) |
| void | setHandshakeTimeout (int msec ) |
| void | setMaxPendingConnections (int numConnections ) |
| void | setProxy (const QNetworkProxy & networkProxy ) |
| void | setServerName (const QString & serverName ) |
| bool | setSocketDescriptor (qintptr socketDescriptor ) |
| void | setSslConfiguration (const QSslConfiguration & sslConfiguration ) |
| qintptr | socketDescriptor () const |
| QSslConfiguration | sslConfiguration () const |
| QList<QWebSocketProtocol::Version> | supportedVersions () const |
| void | acceptError (QAbstractSocket::SocketError socketError ) |
| void | alertReceived (QSsl::AlertLevel level , QSsl::AlertType type , const QString & description ) |
| void | alertSent (QSsl::AlertLevel level , QSsl::AlertType type , const QString & description ) |
| void | closed () |
| void | handshakeInterruptedOnError (const QSslError & error ) |
| void | newConnection () |
| void | originAuthenticationRequired (QWebSocketCorsAuthenticator * authenticator ) |
| void | peerVerifyError (const QSslError & error ) |
| void | preSharedKeyAuthenticationRequired (QSslPreSharedKeyAuthenticator * authenticator ) |
| void | serverError (QWebSocketProtocol::CloseCode closeCode ) |
| void | sslErrors (const QList<QSslError> & errors ) |
它被建模根据 QTcpServer ，且行为相同。因此，若知道如何使用 QTcpServer ，就知道如何使用 QWebSocketServer。此类使之成为可能接受传入 WebSocket 连接。可以指定端口或让 QWebSocketServer 自动挑选一个。可以监听特定地址或所有机器地址。调用 listen () 以让服务器监听传入连接。
newConnection () 信号然后被发射，每次客户端连接到服务器时。调用 nextPendingConnection () 以接受待决连接作为已连接 QWebSocket 。函数返回的指针指向 QWebSocket in QAbstractSocket::ConnectedState ，可以用于与客户端进行通信。
若出现错误， serverError () 返回错误的类型，且 errorString () 可以被调用，以获得发生什么的人类可读描述。
当监听连接时，服务器正监听的可用地址和端口为 serverAddress () 和 serverPort ().
调用 close () 使 QWebSocketServer 停止监听传入连接。
QWebSocketServer 目前不支持 WebSocket 扩展 and WebSocket 子协议 .
注意： 当与自签名证书一起工作时， Firefox bug 594502 阻止 Firefox 去连接到安全 WebSocket 服务器。要解决此问题，先浏览到安全 WebSocket 服务器使用 HTTPS。FireFox 将指示证书无效。从这里开始，证书会被添加到异常。在此之后，安全 WebSocket 连接应该工作。
QWebSocketServer 只支持第 13 版的 WebSocket 协议, 如提纲于 RFC 6455 .
为避免拒绝服务，默认连接握手超时为 10 秒，还可以定制使用 setHandshakeTimeout ().
另请参阅 WebSocket 服务器范例 and QWebSocket .
指示服务器操作是通过 wss (SecureMode) 还是通过 ws (NonSecureMode)
| 常量 | 值 | 描述 |
|---|---|---|
QWebSocketServer::SecureMode
|
0
|
服务器运转于安全模式下 (通过 wss) |
QWebSocketServer::NonSecureMode
|
1
|
服务器运转于非安全模式下 (通过 wss) |
构造新 QWebSocketServer 采用给定 serverName 。 serverName 将在 HTTP 握手阶段被用于标识服务器。它可以为空，在这种情况下，不会把服务器名称发送给客户端。 secureMode 参数指示服务器操作是通过 wss ( SecureMode ) 或通过 ws ( NonSecureMode ).
parent 被传递给 QObject 构造函数。
[signal]
void
QWebSocketServer::
acceptError
(
QAbstractSocket::SocketError
socketError
)
此信号被发射当承兑的新连接导致错误时。 socketError 参数描述出现错误的类型。
另请参阅 pauseAccepting () 和 resumeAccepting ().
[signal, since 6.2]
void
QWebSocketServer::
alertReceived
(
QSsl::AlertLevel
level
,
QSsl::AlertType
type
, const
QString
&
description
)
QWebSocketServer emits this signal if an alert message was received from a peer. level tells if the alert was fatal or it was a warning. type is the code explaining why the alert was sent. When a textual description of the alert message is available, it is supplied in description .
注意： The signal is mostly for informational and debugging purposes and does not require any handling in the application. If the alert was fatal, underlying backend will handle it and close the connection.
注意： 并非所有后端都支持此功能。
该函数在 Qt 6.2 引入。
另请参阅 alertSent (), QSsl::AlertLevel ，和 QSsl::AlertType .
[signal, since 6.2]
void
QWebSocketServer::
alertSent
(
QSsl::AlertLevel
level
,
QSsl::AlertType
type
, const
QString
&
description
)
QWebSocketServer emits this signal if an alert message was sent to a peer. level describes if it was a warning or a fatal error. type gives the code of the alert message. When a textual description of the alert message is available, it is supplied in description .
注意： This signal is mostly informational and can be used for debugging purposes, normally it does not require any actions from the application.
注意： 并非所有后端都支持此功能。
该函数在 Qt 6.2 引入。
另请参阅 alertReceived (), QSsl::AlertLevel ，和 QSsl::AlertType .
[signal]
void
QWebSocketServer::
closed
()
此信号被发射当服务器关闭其连接时。
另请参阅 close ().
[signal, since 6.2]
void
QWebSocketServer::
handshakeInterruptedOnError
(const
QSslError
&
error
)
QWebSocketServer emits this signal if a certificate verification error was found and if early error reporting was enabled in QSslConfiguration .
该函数在 Qt 6.2 引入。
另请参阅 sslErrors () 和 QSslConfiguration::setHandshakeMustInterruptOnError ().
[signal]
void
QWebSocketServer::
newConnection
()
此信号被发射，每次有新连接可用时。
另请参阅 hasPendingConnections () 和 nextPendingConnection ().
[signal]
void
QWebSocketServer::
originAuthenticationRequired
(
QWebSocketCorsAuthenticator
*
authenticator
)
此信号被发射当请求新连接时。连接到此信号的槽应该指示是否允许来源 (可以通过调用 origin() 来确定) 在 authenticator 对象 (通过发出 setAllowed() ).
若没有槽连接到此信号，默认接受所有来源。
注意： 使用 QueuedConnection 连接到此信号是不可能的，因为连接将始终成功。
[signal]
void
QWebSocketServer::
peerVerifyError
(const
QSslError
&
error
)
QWebSocketServer 可以在 SSL 握手期间多次发射此信号，在建立加密之前，以指示当建立对等方的标识时有发生错误。 error 通常指示 QWebSocketServer 无法安全标识对等方。
此信号为您提供早期指示当出错时。通过连接到此信号，可以手动选择在握手完成之前从连接槽内拆毁连接。如果不采取行动， QWebSocketServer 将继续进行以发射 QWebSocketServer::sslErrors ().
另请参阅 sslErrors ().
[signal, since 5.8]
void
QWebSocketServer::
preSharedKeyAuthenticationRequired
(
QSslPreSharedKeyAuthenticator
*
authenticator
)
QWebSocketServer 发射此信号当它协商 PSK (预共享密钥) 密码套件时，因此接着需要 PSK 身份验证。
当使用 PSK 时，客户端必须向服务器发送有效标识和有效 PSK (预共享密钥) 以便 SSL 握手得以继续。应用程序可以在此信号连接的槽中提供此信息，通过填入传递的 authenticator 对象根据需要。
注意： 忽略此信号或未能提供要求证书，将导致握手失败，因此连接将被中止。
注意： authenticator 对象由套接字所拥有且不能被删除通过应用程序。
该函数在 Qt 5.8 引入。
另请参阅 QSslPreSharedKeyAuthenticator and QSslSocket::preSharedKeyAuthenticationRequired ().
[signal]
void
QWebSocketServer::
serverError
(
QWebSocketProtocol::CloseCode
closeCode
)
此信号被发射，当设置 WebSocket 连接期间出现错误时。 closeCode 参数描述出现错误的类型
另请参阅 errorString ().
[signal]
void
QWebSocketServer::
sslErrors
(const
QList
<
QSslError
> &
errors
)
QWebSocketServer 发射此信号在 SSL 握手之后以指示当建立对等方标识时有发生一个或多个错误。错误通常指示 QWebSocketServer 无法安全地识别对等方。除非采取任何行动，连接将被丢弃在此信号被发射之后。
errors 包含一个或多个错误阻止 QSslSocket 验证对等方身份。
另请参阅 peerVerifyError ().
[override virtual]
QWebSocketServer::
~QWebSocketServer
()
销毁 QWebSocketServer 对象。若服务器正在监听连接，套接字将自动关闭。任何客户端 QWebSocket 仍在队列的将被关闭并删除。
另请参阅 close ().
关闭服务器。服务器将不再监听传入连接。
返回最后发生错误的错误代码。若没有发生错误， QWebSocketProtocol::CloseCodeNormal 被返回。
另请参阅 errorString ().
返回人类可读的最后发生的错误的描述。若未发生错误，返回空字符串。
另请参阅 serverError ().
[since 5.9]
void
QWebSocketServer::
handleConnection
(
QTcpSocket
*
socket
) const
升级 TCP socket 到 WebSocket。
QWebSocketServer 对象将拥有套接字对象的所有权，并在适当时删除它。
该函数在 Qt 5.9 引入。
[since 5.14]
std::chrono::milliseconds
QWebSocketServer::
handshakeTimeout
() const
返回新连接的握手超时 (以毫秒为单位)。
默认为 10 秒。若对等方使用更多的时间完成握手，其连接会被关闭。
该函数在 Qt 5.14 引入。
另请参阅 setHandshakeTimeout () 和 handshakeTimeoutMS ().
[since 5.14]
int
QWebSocketServer::
handshakeTimeoutMS
() const
返回新连接的握手超时 (以毫秒为单位)。
默认为 10 秒。若对等方使用更多的时间完成握手，其连接会被关闭。
该函数在 Qt 5.14 引入。
另请参阅 setHandshakeTimeout () 和 handshakeTimeout ().
返回 true 若服务器有待决连接；否则返回 false。
另请参阅 nextPendingConnection () 和 setMaxPendingConnections ().
返回 true 若服务器目前正在监听传入连接；否则返回 false。若监听失败， error () 将返回原因。
告诉服务器去监听传入连接在地址 address 和端口 port 。若 port 为 0，自动选取端口。若 address is QHostAddress::Any ，服务器将监听所有网络接口。
返回 true 当成功时；否则返回 false。
另请参阅 isListening ().
返回最大待决已接受连接数。默认为 30。
另请参阅 setMaxPendingConnections () 和 hasPendingConnections ().
[虚拟]
QWebSocket
*QWebSocketServer::
nextPendingConnection
()
返回下一待决连接作为连接的 QWebSocket 对象。 QWebSocketServer 不拥有所有权对于返回的 QWebSocket 对象。直到调用者明确删除对象，当它不再被使用时，否则会发生内存泄漏。返回 nullptr，若在没有待决连接时调用此函数。
注意：返回的 QWebSocket 对象不可以用于其它线程。
另请参阅 hasPendingConnections ().
暂停传入新连接。排队连接将保留在队列中。
另请参阅 resumeAccepting ().
返回此服务器的网络代理。默认情况下 QNetworkProxy::DefaultProxy 被使用。
另请参阅 setProxy ().
再继续接受新连接。
另请参阅 pauseAccepting ().
返回服务器运行所处的安全模式。
另请参阅 QWebSocketServer () 和 SslMode .
返回服务器的地址，若服务器正在监听连接；否则返回 QHostAddress::Null .
另请参阅 serverPort () 和 listen ().
返回在 HTTP 握手阶段使用的服务器名称。
另请参阅 setServerName ().
返回服务器端口，若服务器正监听连接；否则返回 0。
另请参阅 serverAddress () 和 listen ().
返回客户端可以用来连接到此服务器的 URL，若服务器正在监听连接。否则，返回无效 URL。
另请参阅 serverPort (), serverAddress ()，和 listen ().
[since 5.14]
void
QWebSocketServer::
setHandshakeTimeout
(
std::chrono::milliseconds
msec
)
把新连接的握手超时设为 msec 毫秒。
默认情况下，这被设为 10 秒。若对等方使用更多时间去完成握手，其连接就会被关闭。可以传递负值 (如 -1) 以禁用超时。
该函数在 Qt 5.14 引入。
另请参阅 handshakeTimeout () 和 handshakeTimeoutMS ().
这是重载函数。
把最大待决接受连接数设为 numConnections . WebSocketServer 将接受不超过 numConnections 传入连接先于 nextPendingConnection () 被调用。默认情况下，限制为 30 个待决连接。
QWebSocketServer 将发射 error () 信号采用 QWebSocketProtocol::CloseCodeAbnormalDisconnection 关闭代码当达到最大连接数时。WebSocket 握手将失败且套接字会被关闭。
另请参阅 maxPendingConnections () 和 hasPendingConnections ().
把此服务器的显式网络代理设为 networkProxy .
要禁用代理的使用，使用 QNetworkProxy::NoProxy 代理类型：
server->setProxy(QNetworkProxy::NoProxy);
另请参阅 proxy ().
把 HTTP 握手阶段将使用的服务器名称设为给定 serverName 。 serverName 可以为空，在这种情况下，将向客户端发送空服务器名称。现有已连接客户端不会被通知对于此改变，仅新近连接客户端会见到此新名称。
另请参阅 serverName ().
[since 5.3]
bool
QWebSocketServer::
setSocketDescriptor
(
qintptr
socketDescriptor
)
把此服务器在监听传入连接时应该使用的套接字描述符设为 socketDescriptor .
返回 true，若套接字设置成功；否则返回 false。假定套接字处于监听状态。
该函数在 Qt 5.3 引入。
另请参阅 socketDescriptor () 和 isListening ().
设置 SSL 配置为 QWebSocketServer to sslConfiguration 。此方法不起作用若 QWebSocketServer 运行在非安全模式下 ( QWebSocketServer::NonSecureMode ).
另请参阅 sslConfiguration () 和 SslMode .
[since 5.3]
qintptr
QWebSocketServer::
socketDescriptor
() const
返回服务器用于监听传入指令的本机套接字描述符，或 -1 若服务器未监听。若服务器正在使用 QNetworkProxy ，返回的描述符可能不能用于本机套接字函数。
该函数在 Qt 5.3 引入。
另请参阅 setSocketDescriptor () 和 isListening ().
返回 SSL 配置使用通过 QWebSocketServer 。若服务器未运行在安全模式下 ( QWebSocketServer::SecureMode )，此方法返回 QSslConfiguration::defaultConfiguration ().
另请参阅 setSslConfiguration (), SslMode ，和 QSslConfiguration::defaultConfiguration ().
返回此服务器支持的 WebSocket 版本列表。