QWebSocketServer Class

成员函数文档

[explicit] QWebSocketServer::QWebSocketServer(const QString &serverName, QWebSocketServer::SslMode secureMode, QObject *parent = nullptr)

使用给定的serverName 创建一个新的QWebSocketServer。serverName 将在HTTP握手阶段用于标识服务器。该字段可以为空，此时不会向客户端发送服务器名称。secureMode 参数用于指定服务器是通过wss（SecureMode ）还是ws（NonSecureMode ）运行。

parent 该参数将传递给QObject 构造函数。

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

销毁QWebSocketServer 对象。如果服务器正在监听连接，则套接字将自动关闭。任何仍处于队列中的客户端QWebSockets都将被关闭并删除。

另请参阅 close()。

[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 如果从对等方接收到警报消息，则发出此信号。level 用于指示该警报是致命错误还是警告。type 是说明发送该警报原因的代码。当警报消息有文本描述时，该描述将通过description 提供。

该函数在 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 如果向对等方发送了警报消息，则发出此信号。level 描述该警报是警告还是致命错误。type 提供警报消息的代码。如果警报消息有文本描述，则通过description 提供。

该函数在 Qt 6.2 中引入。

另请参阅 alertReceived()、QSsl::AlertLevel 以及QSsl::AlertType 。

void QWebSocketServer::close()

关闭服务器。服务器将不再监听传入连接。

[signal] void QWebSocketServer::closed()

当服务器关闭连接时，会发出此信号。

另请参阅 close()。

QWebSocketProtocol::CloseCode QWebSocketServer::error() const

返回最后一次发生的错误的错误代码。如果未发生错误，则返回QWebSocketProtocol::CloseCodeNormal 。

另请参阅 errorString()。

QString QWebSocketServer::errorString() const

返回最近发生的错误的人类可读描述。如果未发生错误，则返回空字符串。

另请参阅 serverError()。

void QWebSocketServer::handleConnection(QTcpSocket *socket) const

将 TCPsocket 升级为 WebSocket。

QWebSocketServer 对象将接管该套接字对象，并在适当的时候将其删除。

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

QWebSocketServer 如果在error 中检测到证书验证，且在QSslConfiguration 中启用了早期错误报告，则会发出此信号。

该函数在 Qt 6.2 中引入。

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

std::chrono::milliseconds QWebSocketServer::handshakeTimeout() const

返回新连接的握手超时时间（单位为毫秒）。

默认值为 10 秒。如果对端花费的时间超过此限，其连接将被关闭。

另请参阅 setHandshakeTimeout() 和handshakeTimeoutMS()。

int QWebSocketServer::handshakeTimeoutMS() const

返回新连接的握手超时时间（以毫秒为单位）。

默认值为 10 秒。如果对端花费的时间超过此限，则其连接将被关闭。

另请参阅 setHandshakeTimeout() 和handshakeTimeout()。

bool QWebSocketServer::hasPendingConnections() const

如果服务器有待处理的连接，则返回 true；否则返回 false。

另请参阅 nextPendingConnection() 和setMaxPendingConnections()。

bool QWebSocketServer::isListening() const

如果服务器当前正在监听传入连接，则返回 true；否则返回 false。如果监听失败，error() 将返回失败原因。

另请参阅 listen() 和error()。

bool QWebSocketServer::listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)

指示服务器在地址address 和端口port 上监听传入连接。如果port 的值为 0，则自动选择端口。如果address 的值为QHostAddress::Any ，则服务器将在所有网络接口上进行监听。

成功时返回 true；否则返回 false。

另请参阅 isListening()。

int QWebSocketServer::maxPendingConnections() const

返回待处理的已接受连接的最大数量。默认值为 30。

另请参阅 setMaxPendingConnections() 和hasPendingConnections()。

[signal] void QWebSocketServer::newConnection()

每当有新的连接可用时，都会发出此信号。

另请参阅 hasPendingConnections() 和nextPendingConnection()。

[virtual] QWebSocket *QWebSocketServer::nextPendingConnection()

返回下一个待处理连接，将其作为已连接的QWebSocket 对象。QWebSocketServer 不会获取所返回的QWebSocket 对象的所有权。当该对象不再被使用时，应由调用方显式地将其删除，否则将发生内存泄漏。若在无待处理连接时调用此函数，则返回nullptr。

注意：返回的QWebSocket 对象不能在其他线程中使用。

另请参阅 hasPendingConnections()。

[signal] void QWebSocketServer::originAuthenticationRequired(QWebSocketCorsAuthenticator *authenticator)

当请求建立新连接时，会发出此信号。连接到此信号的槽应指示源（可通过调用 origin() 确定）是否被允许进入authenticator 对象（通过调用setAllowed() 实现）。

如果未将任何槽连接到此信号，则默认情况下将接受所有源。

void QWebSocketServer::pauseAccepting()

暂停接收新连接。已排入队列的连接将保留在队列中。

另请参阅 resumeAccepting()。

[signal] void QWebSocketServer::peerVerifyError(const QSslError &error)

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

该信号可在出现异常时为您提供早期预警。通过订阅此信号，您可以在握手完成之前，从已连接的插槽内部手动选择终止连接。如果不采取任何行动，QWebSocketServer 将继续发出QWebSocketServer::sslErrors() 信号。

另请参阅 sslErrors()。

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

QWebSocketServer 在协商PSK密码套件时会发出此信号，因此随后需要进行PSK身份验证。

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

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

QNetworkProxy QWebSocketServer::proxy() const

返回该服务器的网络代理。默认使用QNetworkProxy::DefaultProxy 。

另请参阅 setProxy()。

void QWebSocketServer::resumeAccepting()

恢复接受新连接。

另请参阅 pauseAccepting()。

QWebSocketServer::SslMode QWebSocketServer::secureMode() const

返回服务器当前运行的安全模式。

另请参阅 QWebSocketServer() 和SslMode 。

QHostAddress QWebSocketServer::serverAddress() const

如果服务器正在监听连接，则返回服务器的地址；否则返回QHostAddress::Null 。

另请参阅 serverPort() 和listen()。

[signal] void QWebSocketServer::serverError(QWebSocketProtocol::CloseCode closeCode)

当建立 WebSocket 连接时发生错误，会触发此信号。closeCode 参数描述了发生的错误类型

另请参阅 errorString()。

QString QWebSocketServer::serverName() const

返回在 HTTP 握手阶段使用的服务器名称。

另请参阅 setServerName()。

quint16 QWebSocketServer::serverPort() const

如果服务器正在监听连接，则返回服务器的端口；否则返回 0。

另请参见 serverAddress() 和listen()。

QUrl QWebSocketServer::serverUrl() const

如果服务器正在监听连接，则返回客户端可用于连接到该服务器的 URL；否则返回一个无效的 URL。

另请参阅 serverPort()、serverAddress() 和listen()。

void QWebSocketServer::setHandshakeTimeout(std::chrono::milliseconds msec)

将新连接的握手超时时间设置为msec 毫秒。

默认情况下，该值设置为 10 秒。如果对端花费更长时间完成握手，则会关闭其连接。您可以传入负值（例如 -1）来禁用该超时。

另请参阅 handshakeTimeout() 和handshakeTimeoutMS()。

void QWebSocketServer::setHandshakeTimeout(int msec)

void QWebSocketServer::setMaxPendingConnections(int numConnections)

将待处理已接受连接的最大数量设置为numConnections 。WebSocketServer 在调用nextPendingConnection()之前，最多接受numConnections 个传入连接。默认情况下，该限制为30个待处理连接。

QWebSocketServer 当连接数达到上限时，将发出error()信号，并附带QWebSocketProtocol::CloseCodeAbnormalDisconnection 关闭代码。WebSocket握手将失败，套接字将被关闭。

另请参阅 maxPendingConnections() 和hasPendingConnections()。

void QWebSocketServer::setProxy(const QNetworkProxy &networkProxy)

将此服务器的显式网络代理设置为networkProxy 。

若要禁用代理，请使用QNetworkProxy::NoProxy 代理类型：

server->setProxy(QNetworkProxy::NoProxy);

另请参阅 proxy()。

void QWebSocketServer::setServerName(const QString &serverName)

将HTTP握手阶段中使用的服务器名称设置为给定的serverName 。serverName 可以为空，此时将向客户端发送空服务器名称。已连接的客户端不会收到此更改的通知，只有新连接的客户端才会看到这个新名称。

另请参阅 serverName()。

bool QWebSocketServer::setSocketDescriptor(qintptr socketDescriptor)

设置该服务器在监听发往socketDescriptor 的传入连接时应使用的套接字描述符。

如果套接字设置成功，则返回 true；否则返回 false。该套接字被视为处于监听状态。

另请参阅 socketDescriptor() 和isListening()。

void QWebSocketServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)

将QWebSocketServer 的SSL配置设置为sslConfiguration 。如果QWebSocketServer 以非安全模式（QWebSocketServer::NonSecureMode ）运行，则此方法无效。

另请参阅 sslConfiguration() 和SslMode 。

[since 6.4] void QWebSocketServer::setSupportedSubprotocols(const QStringList &protocols)

将服务器支持的协议列表设置为protocols 。

该函数在 Qt 6.4 中引入。

另请参阅 supportedSubprotocols()。

qintptr QWebSocketServer::socketDescriptor() const

返回服务器用于监听传入指令的原生套接字描述符；如果服务器未处于监听状态，则返回 -1。如果服务器使用的是QNetworkProxy ，则返回的描述符可能无法与原生套接字函数配合使用。

另请参阅 setSocketDescriptor() 和isListening()。

QSslConfiguration QWebSocketServer::sslConfiguration() const

返回QWebSocketServer 所使用的SSL配置。如果服务器未以安全模式运行（QWebSocketServer::SecureMode ），则该方法返回QSslConfiguration::defaultConfiguration()。

另请参阅 setSslConfiguration()、SslMode 以及QSslConfiguration::defaultConfiguration()。

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

QWebSocketServer 在 SSL 握手完成后发出此信号，以指示在确认对等方身份的过程中发生了一个或多个错误。

这些错误通常表明QWebSocketServer 无法安全地识别对端。除非采取任何措施，否则在发出此信号后，连接将被断开。

errors 包含一个或多个导致QSslSocket 无法验证对等方身份的错误。

另请参阅 peerVerifyError() 和sslErrorsOccurred()。

[signal, since 6.11] void QWebSocketServer::sslErrorsOccurred(QSslSocket *socket, const QList<QSslError> &errors)

QWebSocketServer 在 SSL 握手完成后发出此信号，以指示在确定对端身份的过程中发生了一个或多个错误。

这些错误通常表明socket 无法安全地识别对端。除非采取任何措施，否则在发出此信号后，连接将被断开。

errors 包含一个或多个导致QSslSocket 无法验证对等方身份的错误。

若您希望在出现错误的情况下继续连接，必须在连接到该信号的槽内调用QSslSocket::ignoreSslErrors()。若您需要在后续访问错误列表，可调用QSslSocket::sslHandshakeErrors()。

该函数于 Qt 6.11 中引入。

另请参阅 peerVerifyError() 和sslErrors()。

[since 6.4] QStringList QWebSocketServer::supportedSubprotocols() const

返回服务器支持的协议列表。

该函数自 Qt 6.4 起引入。

另请参阅 setSupportedSubprotocols()。

QList<QWebSocketProtocol::Version> QWebSocketServer::supportedVersions() const

返回该服务器支持的 WebSocket 版本列表。