En esta página

QTcpServer Class

La clase QTcpServer proporciona un servidor basado en TCP. Más información...

Encabezado: #include <QTcpServer>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Heredado de: QObject
Heredado por:

QSctpServer y QSslServer

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QTcpServer(QObject *parent = nullptr)
virtual ~QTcpServer()
void close()
QString errorString() const
virtual bool hasPendingConnections() const
bool isListening() const
bool listen(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
(since 6.3) int listenBacklogSize() const
int maxPendingConnections() const
virtual QTcpSocket *nextPendingConnection()
void pauseAccepting()
QNetworkProxy proxy() const
void resumeAccepting()
QHostAddress serverAddress() const
QAbstractSocket::SocketError serverError() const
quint16 serverPort() const
(since 6.3) void setListenBacklogSize(int size)
void setMaxPendingConnections(int numConnections)
void setProxy(const QNetworkProxy &networkProxy)
bool setSocketDescriptor(qintptr socketDescriptor)
qintptr socketDescriptor() const
bool waitForNewConnection(int msec = 0, bool *timedOut = nullptr)

Señales

void acceptError(QAbstractSocket::SocketError socketError)
void newConnection()
(since 6.4) void pendingConnectionAvailable()

Funciones protegidas

void addPendingConnection(QTcpSocket *socket)
virtual void incomingConnection(qintptr socketDescriptor)

Descripción detallada

Esta clase permite aceptar conexiones TCP entrantes. Puedes especificar el puerto o dejar que QTcpServer elija uno automáticamente. Puedes escuchar en una dirección específica o en todas las direcciones del equipo.

Llama 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. Cuando la conexión del cliente se ha añadido a la cola de conexiones pendientes mediante la función ` addPendingConnection()`, se emite la señal ` pendingConnectionAvailable()`.

Llama a ` nextPendingConnection()` para aceptar la conexión pendiente como una conexión ` QTcpSocket` establecida. La función devuelve un puntero a un ` QTcpSocket ` 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 estar a la escucha de 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() se hace que QTcpServer deje de escuchar conexiones entrantes.

Aunque QTcpServer está diseñado principalmente para utilizarse con un bucle de eventos, es posible utilizarlo sin él. En ese caso, debes utilizar waitForNewConnection(), que se bloquea hasta que haya una conexión disponible o se agote el tiempo de espera.

Véase también QTcpSocket, Fortune Server, Threaded Fortune Server y el ejemplo de Torrent.

Documentación de las funciones de miembro

[explicit] QTcpServer::QTcpServer(QObject *parent = nullptr)

Crea un objeto QTcpServer.

parent Se pasa al constructor de QObject.

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

[virtual noexcept] QTcpServer::~QTcpServer()

Elimina el objeto QTcpServer. Si el servidor está a la espera de conexiones, el socket se cierra automáticamente.

Cualquier objeto ` QTcpSocket` de cliente que siga conectado deberá desconectarse o cambiarse de padre antes de que se elimine el servidor.

Véase también close().

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

Esta señal se emite cuando se produce un error al aceptar una nueva conexión. El parámetro « socketError » describe el tipo de error que se ha producido.

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

[protected] void QTcpServer::addPendingConnection(QTcpSocket *socket)

Esta función es llamada por ` QTcpServer::incomingConnection()` para añadir el ` socket ` a la lista de conexiones entrantes pendientes.

Nota: No olvides llamar a este miembro desde la función ` incomingConnection()` reimplementada si no quieres alterar el funcionamiento del mecanismo de conexiones pendientes. Esta función emite la señal ` pendingConnectionAvailable()` una vez que se ha añadido el socket.

Véase también incomingConnection() y pendingConnectionAvailable().

void QTcpServer::close()

Cierra el servidor. El servidor dejará de estar a la escucha de conexiones entrantes.

Véase también listen().

QString QTcpServer::errorString() const

Devuelve una descripción comprensible para el usuario del último error que se ha producido.

Véase también serverError().

[virtual] bool QTcpServer::hasPendingConnections() const

Devuelve ` true ` si el servidor tiene una conexión pendiente; en caso contrario, devuelve ` false`.

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

[virtual protected] void QTcpServer::incomingConnection(qintptr socketDescriptor)

QTcpServer llama a esta función virtual cuando hay una nueva conexión disponible. El argumento socketDescriptor es el descriptor de socket nativo de la conexión aceptada.

La implementación básica crea un objeto ` QTcpSocket`, establece el descriptor de socket y, a continuación, almacena el ` QTcpSocket ` en una lista interna de conexiones pendientes. Por último, se emite ` newConnection()`.

Reimplementa esta función para modificar el comportamiento del servidor cuando haya una conexión disponible.

Si este servidor utiliza QNetworkProxy, es posible que el socketDescriptor no sea compatible con las funciones de socket nativas, por lo que solo debería utilizarse con QTcpSocket::setSocketDescriptor().

Nota: Si se crea otro socket en la reimplementación de este método, es necesario añadirlo al mecanismo de conexiones pendientes llamando a ` addPendingConnection()`.

Nota: Si se desea gestionar una conexión entrante como un nuevo objeto ` QTcpSocket ` en otro hilo, hay que pasar ` socketDescriptor ` a ese otro hilo, crear allí el objeto ` QTcpSocket ` y utilizar su método ` setSocketDescriptor()`.

Véase también newConnection(), nextPendingConnection() y addPendingConnection().

bool QTcpServer::isListening() const

Devuelve « true » si el servidor está actualmente a la escucha de conexiones entrantes; en caso contrario, devuelve « false ».

Véase también listen().

bool QTcpServer::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 se realiza correctamente; en caso contrario, devuelve false.

Véase también isListening().

[since 6.3] int QTcpServer::listenBacklogSize() const

Devuelve el tamaño de la cola de conexiones pendientes de aceptación.

Esta función se introdujo en Qt 6.3.

Véase también setListenBacklogSize().

int QTcpServer::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 QTcpServer::newConnection()

Esta señal se emite cada vez que hay una nueva conexión disponible, independientemente de si se ha añadido o no a la cola de conexiones pendientes.

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

[virtual] QTcpSocket *QTcpServer::nextPendingConnection()

Devuelve la siguiente conexión pendiente como un objeto ` QTcpSocket ` conectado.

El socket se crea como un elemento secundario del servidor, lo que significa que se elimina automáticamente cuando se destruye el objeto ` QTcpServer `. No obstante, es recomendable eliminar el objeto de forma explícita cuando ya no se necesite, para evitar el desperdicio de memoria.

nullptr Se devuelve si se llama a esta función cuando no hay conexiones pendientes.

Nota: El objeto ` QTcpSocket ` devuelto no se puede utilizar desde otro hilo. Si se desea utilizar una conexión entrante desde otro hilo, es necesario sobrescribir ` incomingConnection()`.

Véase también hasPendingConnections().

void QTcpServer::pauseAccepting()

Suspende la aceptación de nuevas conexiones. Las conexiones en cola permanecerán en la cola.

Véase también resumeAccepting().

[private signal, since 6.4] void QTcpServer::pendingConnectionAvailable()

Esta señal se emite cada vez que se añade una nueva conexión a la cola de conexiones pendientes.

Nota: Se trata de una señal privada. Se puede utilizar en conexiones de señales, pero el usuario no puede emitirla.

Esta función se introdujo en Qt 6.4.

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

QNetworkProxy QTcpServer::proxy() const

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

Véase también setProxy() y QNetworkProxy.

void QTcpServer::resumeAccepting()

Se reanuda la aceptación de nuevas conexiones.

Véase también pauseAccepting().

QHostAddress QTcpServer::serverAddress() const

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

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

QAbstractSocket::SocketError QTcpServer::serverError() const

Devuelve un código de error correspondiente al último error que se ha producido.

Véase también errorString().

quint16 QTcpServer::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().

[since 6.3] void QTcpServer::setListenBacklogSize(int size)

Establece el tamaño de la cola de conexiones pendientes que se van a aceptar en size. Es posible que el sistema operativo reduzca o ignore este valor. Por defecto, el tamaño de la cola es 50.

Nota: Esta propiedad debe configurarse antes de llamar a listen().

Esta función se introdujo en Qt 6.3.

Véase también ` listenBacklogSize()`.

void QTcpServer::setMaxPendingConnections(int numConnections)

Establece el número máximo de conexiones aceptadas pendientes en numConnections. QTcpServer 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.

Es posible que los clientes sigan pudiendo conectarse después de que el servidor haya alcanzado su número máximo de conexiones pendientes (es decir, QTcpSocket aún puede emitir la señal connected()). QTcpServer dejará de aceptar nuevas conexiones, pero es posible que el sistema operativo las mantenga en la cola.

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

void QTcpServer::setProxy(const QNetworkProxy &networkProxy)

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

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

server->setProxy(QNetworkProxy::NoProxy);

Véase también proxy() y QNetworkProxy.

bool QTcpServer::setSocketDescriptor(qintptr socketDescriptor)

Establece el descriptor de socket que este servidor debe utilizar al escuchar conexiones entrantes en socketDescriptor. Devuelve true si el socket se ha establecido correctamente; en caso contrario, devuelve false.

Se da por hecho que el socket se encuentra en estado de escucha.

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

qintptr QTcpServer::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 nativas de sockets.

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

bool QTcpServer::waitForNewConnection(int msec = 0, bool *timedOut = nullptr)

Espera un máximo de msec milisegundos o hasta que haya una conexión entrante disponible. Devuelve true si hay una conexión disponible; en caso contrario, devuelve false. Si la operación ha agotado el tiempo de espera y timedOut no es nullptr, *timedOut se establecerá en true.

Se trata de una llamada a función bloqueante. No se recomienda su uso en una aplicación GUI de un solo hilo, ya que toda la aplicación dejará de responder hasta que la función devuelva un resultado. waitForNewConnection() resulta especialmente útil cuando no hay ningún bucle de eventos disponible.

La alternativa no bloqueante es conectarse a la señal « newConnection()».

Si msec es -1, esta función no tendrá tiempo de espera.

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

© 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.