En esta página

QWebSocketServer Class

Implementa un servidor basado en WebSocket. Más información...

Encabezado: #include <QWebSocketServer>
CMake: find_package(Qt6 REQUIRED COMPONENTS WebSockets)
target_link_libraries(mytarget PRIVATE Qt6::WebSockets)
qmake: QT += websockets
Heredado de: QObject

Tipos públicos

enum SslMode { SecureMode, NonSecureMode }

Funciones públicas

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)
(since 6.4) void setSupportedSubprotocols(const QStringList &protocols)
qintptr socketDescriptor() const
QSslConfiguration sslConfiguration() const
(since 6.4) QStringList supportedSubprotocols() const
QList<QWebSocketProtocol::Version> supportedVersions() const

Señales

void acceptError(QAbstractSocket::SocketError socketError)
(since 6.2) void alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)
(since 6.2) void alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)
void closed()
(since 6.2) 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)
(since 6.11) void sslErrorsOccurred(QSslSocket *socket, const QList<QSslError> &errors)

Descripción detallada

Se basa en QTcpServer y funciona de la misma manera. Por lo tanto, si sabes cómo utilizar QTcpServer, ya sabes cómo utilizar QWebSocketServer. Esta clase permite aceptar conexiones WebSocket entrantes. Puedes especificar el puerto o dejar que QWebSocketServer elija uno automáticamente. Se puede escuchar en una dirección específica o en todas las direcciones del equipo. Llame a ` listen()` para que el servidor escuche las conexiones entrantes.

A continuación, se emite la señal « newConnection()» cada vez que un cliente se conecta al servidor. Llama a « nextPendingConnection()» para aceptar la conexión pendiente como un « QWebSocket » conectado. La función devuelve un puntero a un « QWebSocket » en « QAbstractSocket::ConnectedState » que puedes utilizar para comunicarte con el cliente.

Si se produce un error, serverError() devuelve el tipo de error, y se puede llamar a errorString() para obtener una descripción legible por el usuario de lo que ha ocurrido.

Al escuchar conexiones, la dirección y el puerto en los que el servidor está a la escucha están disponibles mediante serverAddress() y serverPort().

Al llamar a close(), QWebSocketServer deja de escuchar conexiones entrantes.

Actualmente, QWebSocketServer no es compatible con las extensiones de WebSocket.

Nota: Al trabajar con certificados autofirmados, el error 594502 de Firefox impide que este navegador se conecte a un servidor WebSocket seguro. Para solucionar este problema, primero accede al servidor WebSocket seguro mediante HTTPS. Firefox indicará que el certificado no es válido. A partir de ahí, se puede añadir el certificado a las excepciones. Tras ello, la conexión segura de WebSockets debería funcionar.

QWebSocketServer solo es compatible con la versión 13 del protocolo WebSocket, tal y como se describe en el RFC 6455.

Hay un tiempo de espera predeterminado de 10 segundos para el establecimiento de la conexión, con el fin de evitar ataques de denegación de servicio, que se puede personalizar mediante ` setHandshakeTimeout()`.

Véase también Ejemplo de servidor WebSocket y QWebSocket.

Documentación sobre los tipos de miembros

enum QWebSocketServer::SslMode

Indica si el servidor funciona en modo wss (SecureMode) o ws (NonSecureMode)

ConstanteValorDescripción
QWebSocketServer::SecureMode0El servidor funciona en modo seguro (a través de WSS).
QWebSocketServer::NonSecureMode1El servidor funciona en modo no seguro (a través de WS)

Documentación de la función miembro

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

Crea un nuevo QWebSocketServer con el parámetro « serverName » proporcionado. El parámetro « serverName » se utilizará en la fase de establecimiento de conexión HTTP para identificar el servidor. Puede dejarse vacío; en ese caso, no se enviará ningún nombre de servidor al cliente. El parámetro « secureMode » indica si el servidor funciona a través de wss (SecureMode) o de ws (NonSecureMode).

parent Se pasa al constructor QObject.

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

Destruye el objeto ` QWebSocketServer `. Si el servidor está a la espera de conexiones, el socket se cierra automáticamente. Cualquier solicitud de cliente ` QWebSocket` que aún esté en cola se cierra y se elimina.

Véase también close().

[signal] void QWebSocketServer::acceptError(QAbstractSocket::SocketError socketError)

Esta señal se emite cuando la aceptación de una nueva conexión da lugar a un error. El parámetro socketError describe el tipo de error que se ha producido.

Véase también pauseAccepting() y resumeAccepting().

[signal, since 6.2] void QWebSocketServer::alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QWebSocketServer Emite esta señal si se ha recibido un mensaje de alerta de un par. « level » indica si la alerta fue grave o si se trataba de una advertencia. « type » es el código que explica por qué se envió la alerta. Cuando hay disponible una descripción textual del mensaje de alerta, se proporciona en « description ».

Nota: La señal tiene principalmente fines informativos y de depuración, y no requiere ningún tipo de gestión por parte de la aplicación. Si la alerta fue grave, el backend subyacente se encargará de gestionarla y cerrará la conexión.

Nota: No todos los backends admiten esta funcionalidad.

Esta función se introdujo en Qt 6.2.

Véase también alertSent(), QSsl::AlertLevel y QSsl::AlertType.

[signal, since 6.2] void QWebSocketServer::alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QWebSocketServer Emite esta señal si se ha enviado un mensaje de alerta a un par. « level » describe si se trataba de una advertencia o de un error grave. « type » proporciona el código del mensaje de alerta. Cuando hay disponible una descripción textual del mensaje de alerta, esta se incluye en « description ».

Nota: Esta señal es principalmente informativa y puede utilizarse con fines de depuración; normalmente no requiere ninguna acción por parte de la aplicación.

Nota: No todos los backends admiten esta funcionalidad.

Esta función se introdujo en Qt 6.2.

Véase también alertReceived(), QSsl::AlertLevel y QSsl::AlertType.

void QWebSocketServer::close()

Cierra el servidor. El servidor dejará de escuchar las conexiones entrantes.

[signal] void QWebSocketServer::closed()

Esta señal se emite cuando el servidor ha cerrado su conexión.

Véase también close().

QWebSocketProtocol::CloseCode QWebSocketServer::error() const

Devuelve un código de error correspondiente al último error que se ha producido. Si no se ha producido ningún error, se devuelve el valor « QWebSocketProtocol::CloseCodeNormal ».

Véase también errorString().

QString QWebSocketServer::errorString() const

Devuelve una descripción legible para el usuario del último error que se ha producido. Si no se ha producido ningún error, se devuelve una cadena vacía.

Véase también serverError().

void QWebSocketServer::handleConnection(QTcpSocket *socket) const

Actualiza un objeto `tcp socket ` a `WebSocket`.

El objeto ` QWebSocketServer ` asumirá la propiedad del objeto `socket` y lo eliminará cuando sea oportuno.

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

QWebSocketServer Emite esta señal si se ha detectado un error de verificación de certificados error y si se ha habilitado la notificación temprana de errores en QSslConfiguration.

Esta función se introdujo en Qt 6.2.

Véase también sslErrors() y QSslConfiguration::setHandshakeMustInterruptOnError().

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

Devuelve el tiempo de espera del protocolo de establecimiento de conexión para nuevas conexiones, expresado en milisegundos.

El valor predeterminado es 10 segundos. Si un par tarda más tiempo en completar el protocolo de enlace, se cierra su conexión.

Véase también setHandshakeTimeout() y handshakeTimeoutMS().

int QWebSocketServer::handshakeTimeoutMS() const

Devuelve el tiempo de espera del protocolo de establecimiento de conexión para nuevas conexiones, en milisegundos.

El valor predeterminado es de 10 segundos. Si un par tarda más tiempo en completar el protocolo de enlace, se cierra su conexión.

Véase también setHandshakeTimeout() y handshakeTimeout().

bool QWebSocketServer::hasPendingConnections() const

Devuelve «true» si el servidor tiene conexiones pendientes; en caso contrario, devuelve «false».

Véase también nextPendingConnection() y setMaxPendingConnections().

bool QWebSocketServer::isListening() const

Devuelve «true» si el servidor está actualmente a la espera de conexiones entrantes; en caso contrario, devuelve «false». Si la escucha falla, la función ` error()` devolverá el motivo.

Véanse también ` listen()` y ` error()`.

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

Indica al servidor que escuche las conexiones entrantes en la dirección address y en el puerto port. Si port es 0, se elige un puerto automáticamente. Si address es QHostAddress::Any, el servidor escuchará en todas las interfaces de red.

Devuelve «true» si la operación se realiza correctamente; en caso contrario, devuelve «false».

Véase también isListening().

int QWebSocketServer::maxPendingConnections() const

Devuelve el número máximo de conexiones aceptadas pendientes. El valor por defecto es 30.

Véase también setMaxPendingConnections() y hasPendingConnections().

[signal] void QWebSocketServer::newConnection()

Esta señal se emite cada vez que hay una nueva conexión disponible.

Véase también hasPendingConnections() y nextPendingConnection().

[virtual] QWebSocket *QWebSocketServer::nextPendingConnection()

Devuelve la siguiente conexión pendiente como un objeto ` QWebSocket ` conectado. ` QWebSocketServer ` no asume la propiedad del objeto ` QWebSocket ` devuelto. Corresponde al llamante eliminar el objeto de forma explícita cuando ya no se vaya a utilizar; de lo contrario, se producirá una fuga de memoria. Se devuelve `nullptr` si se llama a esta función cuando no hay conexiones pendientes.

Nota: El objeto QWebSocket devuelto no puede utilizarse desde otro hilo.

Véase también hasPendingConnections().

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

Esta señal se emite cuando se solicita una nueva conexión. El slot conectado a esta señal debe indicar si el origen (que puede determinarse mediante la llamada a `origin()`) está permitido en el objeto ` authenticator ` (mediante la llamada a ` setAllowed()`).

Si no hay ninguna ranura conectada a esta señal, se aceptarán todos los orígenes por defecto.

Nota: Noes posible utilizar una `QueuedConnection` para conectarse a esta señal, ya que la conexión siempre se establecerá con éxito.

void QWebSocketServer::pauseAccepting()

Detiene las nuevas conexiones entrantes. Las conexiones en cola permanecerán en la cola.

Véase también resumeAccepting().

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

QWebSocketServer Puede emitir esta señal varias veces durante el protocolo de enlace SSL, antes de que se haya establecido el cifrado, para indicar que se ha producido un error al verificar la identidad del interlocutor. La señal « error » suele indicar que QWebSocketServer no puede identificar de forma segura al interlocutor.

Esta señal te proporciona una indicación temprana de que algo va mal. Al conectarte a esta señal, puedes optar manualmente por interrumpir la conexión desde el interior del slot conectado antes de que se haya completado el protocolo de enlace. Si no se toma ninguna medida, QWebSocketServer procederá a emitir QWebSocketServer::sslErrors().

Véase también sslErrors().

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

QWebSocketServer emite esta señal cuando negocia un conjunto de cifrado PSK, por lo que a continuación se requiere una autenticación PSK.

Al utilizar PSK, el cliente debe enviar al servidor una identidad válida y una clave precompartida válida para que el protocolo de enlace SSL pueda continuar. Las aplicaciones pueden proporcionar esta información en un slot conectado a esta señal, rellenando el objeto ` authenticator ` pasado según sus necesidades.

Nota: Ignorar esta señal o no proporcionar las credenciales necesarias provocará que el protocolo de enlace falle y, por lo tanto, que la conexión se interrumpa.

Nota: El objeto ` authenticator ` es propiedad del socket y la aplicación no debe eliminarlo.

Véase también QSslPreSharedKeyAuthenticator y QSslSocket::preSharedKeyAuthenticationRequired().

QNetworkProxy QWebSocketServer::proxy() const

Devuelve el proxy de red de este servidor. Por defecto, se utiliza QNetworkProxy::DefaultProxy.

Véase también setProxy().

void QWebSocketServer::resumeAccepting()

Se reanuda la aceptación de nuevas conexiones.

Véase también pauseAccepting().

QWebSocketServer::SslMode QWebSocketServer::secureMode() const

Devuelve el modo seguro en el que se está ejecutando el servidor.

Véase también QWebSocketServer() y SslMode.

QHostAddress QWebSocketServer::serverAddress() const

Devuelve la dirección del servidor si este está a la escucha para recibir conexiones; en caso contrario, devuelve QHostAddress::Null.

Véanse también serverPort() y listen().

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

Esta señal se emite cuando se produce un error durante la configuración de una conexión WebSocket. El parámetro « closeCode » describe el tipo de error que se ha producido

Véase también errorString().

QString QWebSocketServer::serverName() const

Devuelve el nombre del servidor que se utiliza durante la fase de establecimiento de la conexión HTTP.

Véase también setServerName().

quint16 QWebSocketServer::serverPort() const

Devuelve el puerto del servidor si este está a la espera de conexiones; en caso contrario, devuelve 0.

Véase también serverAddress() y listen().

QUrl QWebSocketServer::serverUrl() const

Devuelve una URL que los clientes pueden utilizar para conectarse a este servidor si este está a la espera de conexiones. En caso contrario, se devuelve una URL no válida.

Véase también serverPort(), serverAddress() y listen().

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

Establece el tiempo de espera del protocolo de establecimiento de conexión para nuevas conexiones en msec milisegundos.

Por defecto, está establecido en 10 segundos. Si un par tarda más tiempo en completar el protocolo de enlace, se cierra su conexión. Se puede pasar un valor negativo (por ejemplo, -1) para desactivar el tiempo de espera.

Véase también handshakeTimeout() y handshakeTimeoutMS().

void QWebSocketServer::setHandshakeTimeout(int msec)

Esta es una función sobrecargada.

void QWebSocketServer::setMaxPendingConnections(int numConnections)

Establece el número máximo de conexiones aceptadas pendientes en numConnections. WebSocketServer no aceptará más de numConnections conexiones entrantes antes de que se llame a nextPendingConnection(). Por defecto, el límite es de 30 conexiones pendientes.

QWebSocketServer Emitirá la señal error() con el código de cierre QWebSocketProtocol::CloseCodeAbnormalDisconnection cuando se haya alcanzado el número máximo de conexiones. El protocolo de enlace de WebSocket fallará y el socket se cerrará.

Véase también maxPendingConnections() y hasPendingConnections().

void QWebSocketServer::setProxy(const QNetworkProxy &networkProxy)

Establece el proxy de red explícito de este servidor en networkProxy.

Para desactivar el uso de un proxy, utiliza el tipo de proxy QNetworkProxy::NoProxy:

server->setProxy(QNetworkProxy::NoProxy);

Véase también proxy().

void QWebSocketServer::setServerName(const QString &serverName)

Establece el nombre del servidor que se utilizará durante la fase de establecimiento de la conexión HTTP en el valor especificado: serverName. El parámetro serverName puede dejarse vacío; en ese caso, se enviará al cliente un nombre de servidor vacío. Los clientes ya conectados no recibirán notificación de este cambio; solo los clientes que se conecten a partir de ese momento verán este nuevo nombre.

Véase también serverName().

bool QWebSocketServer::setSocketDescriptor(qintptr socketDescriptor)

Establece el descriptor de socket que este servidor debe utilizar al escuchar conexiones entrantes a socketDescriptor.

Devuelve «true» si el socket se ha configurado correctamente; en caso contrario, devuelve «false». Se supone que el socket se encuentra en estado de escucha.

Véase también socketDescriptor() y isListening().

void QWebSocketServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)

Establece la configuración SSL para QWebSocketServer en sslConfiguration. Este método no tiene ningún efecto si QWebSocketServer se ejecuta en modo no seguro (QWebSocketServer::NonSecureMode).

Véase también sslConfiguration() y SslMode.

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

Establece la lista de protocolos compatibles con el servidor en « protocols ».

Esta función se introdujo en Qt 6.4.

Véase también supportedSubprotocols().

qintptr QWebSocketServer::socketDescriptor() const

Devuelve el descriptor de socket nativo que utiliza el servidor para escuchar las instrucciones entrantes, o -1 si el servidor no está a la escucha. Si el servidor utiliza QNetworkProxy, es posible que el descriptor devuelto no sea compatible con las funciones de socket nativas.

Véanse también setSocketDescriptor() y isListening().

QSslConfiguration QWebSocketServer::sslConfiguration() const

Devuelve la configuración SSL utilizada por QWebSocketServer. Si el servidor no se está ejecutando en modo seguro (QWebSocketServer::SecureMode), este método devuelve QSslConfiguration::defaultConfiguration().

Véase también setSslConfiguration(), SslMode y QSslConfiguration::defaultConfiguration().

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

QWebSocketServer Emite esta señal tras el protocolo de enlace SSL para indicar que se han producido uno o más errores al establecer la identidad del interlocutor.

Estos errores suelen indicar que QWebSocketServer no puede identificar de forma segura al interlocutor. A menos que se tome alguna medida, la conexión se interrumpirá tras la emisión de esta señal.

errors contiene uno o más errores que impiden que QSslSocket verifique la identidad del interlocutor.

Véase también « peerVerifyError()» y « sslErrorsOccurred()».

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

QWebSocketServer Emite esta señal tras el protocolo de enlace SSL para indicar que se han producido uno o más errores al establecer la identidad del interlocutor.

Estos errores suelen indicar que socket no puede identificar de forma segura al interlocutor. A menos que se tome alguna medida, la conexión se interrumpirá tras la emisión de esta señal.

errors contiene uno o más errores que impiden que QSslSocket verifique la identidad del interlocutor.

Si deseas continuar con la conexión a pesar de los errores que se han producido, debes llamar a ` QSslSocket::ignoreSslErrors()` desde el interior de una ranura conectada a esta señal. Si necesitas acceder a la lista de errores más adelante, puedes llamar a ` QSslSocket::sslHandshakeErrors()`.

Nota: Nose puede utilizar ` Qt::QueuedConnection ` al conectarse a esta señal, ya que, de lo contrario, llamar a ` QSslSocket::ignoreSslErrors()` no tendrá ningún efecto.

Esta función se introdujo en Qt 6.11.

Véase también peerVerifyError() y sslErrors().

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

Devuelve la lista de protocolos compatibles con el servidor.

Esta función se introdujo en Qt 6.4.

Véase también setSupportedSubprotocols().

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

Devuelve una lista de las versiones de WebSocket compatibles con este servidor.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.