[TOC]

QTcpServer Class

QTcpServer 类提供了一个基于 TCP 协议的服务器。

属性方法
头文件#include <QTcpServer>
qmakeQT += network
父类QObject
子类QSctpServer

注意: 该类的所有成员函数都是可重入的。

公共成员函数

类型函数名
QTcpServer(QObject *parent = nullptr)
virtual~QTcpServer()
voidclose()
QStringerrorString() const
virtual boolhasPendingConnections() const
boolisListening() const
boollisten(const QHostAddress &address = QHostAddress::Any, quint16 port = 0)
intmaxPendingConnections() const
virtual QTcpSocket *nextPendingConnection()
voidpauseAccepting()
QNetworkProxyproxy() const
voidresumeAccepting()
QHostAddressserverAddress() const
QAbstractSocket::SocketErrorserverError() const
quint16serverPort() const
voidsetMaxPendingConnections(int numConnections)
voidsetProxy(const QNetworkProxy &networkProxy)
boolsetSocketDescriptor(qintptr socketDescriptor)
qintptrsocketDescriptor() const
boolwaitForNewConnection(int msec = 0, bool *timedOut = nullptr)

信号

类型函数名
voidacceptError(QAbstractSocket::SocketError socketError)
voidnewConnection()

保护成员函数

类型函数名
voidaddPendingConnection(QTcpSocket *socket)
virtual voidincomingConnection(qintptr socketDescriptor)

详细介绍

这个类使“用Qt编写一个接受 TCP 链接的服务器”的构想成为可能。您可以为 QTcpServer 指定一个端口或者让它自动选一个。您也可以令 QTcpServer 仅监听一个指定的地址或者让它监听这台机器上的所有地址。

调用 listen() 函数来为到达的连接建立服务器监听。每次当有新的客户端连接到这个服务端时,QTcpServer 都会发出 newConnection() 信号。

调用 nextPendingConnection() 函数接受一个连接到 QTcpServer 的待处理连接。 该函数会返回一个处于已连接QAbstractSocket::ConnectedState )状态的 QTcpSocket ,您可以使用这个 QTcpSocket 与客户端进行通信。

如果发生错误,serverError() 函数会返回该错误的类型。 您可以调用 errorString() 函数来获取一个能让人看懂的错误描述。

当服务器正在监听连接时,服务器所监听的地址和端口可以通过 serverAddress() 和 serverPort() 函数来获取。

调用 close() 函数后 QTcpServer 会停止监听到达的连接。

另外您也可以在 QTcpSocket 类文档和Qt官方给出的 Fortune Server Example ,Threaded Fortune Server Example ,Loopback Example 和 Torrent Example 示例文档中找到相关信息。

成员函数文档

QTcpServer::QTcpServer(QObject *parent = nullptr)

构造函数。构造一个 QTcpServer 对象。

parent 参数将传递到 QObject 的构造函数中。

另外您也可以在 listen() 和 setSocketDescriptor() 函数介绍中找到相关介绍。


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

当接受一个新的连接时出错,QTcpServer 会发送此信号。 socketError 参数描述了该错误的类型。

该函数最早在Qt5.0版本引入。

另外您也可以在 pauseAccepting() 和 resumeAccepting() 函数介绍中找到相关信息。


[SIGNAL] void QTcpServer::newConnection()

每当有新的连接可用时,QTcpServer 都会发送该消息。

另外您也可以在 hasPendingConnections() 和 nextPendingConnection() 函数介绍中找到相关信息。


[virtual] QTcpServer::~QTcpServer()

析构函数。销毁 QTcpServer 对象。如果服务器正在监听连接,套接字会自动关闭。

在服务端删除之前,所有仍处于连接状态的客户端 QTcpSocket 都必须断开连接或者重新指定父类。

另外您也可以在 close() 函数介绍中找到相关信息。


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

该函数由 QTcpServer::incomingConnection() 函数调用,作用是添加 socket 到待处理连接列表中。

注意: 如果您不想破坏连接处理机制,请不要忘记从重新实现的 incomingConnection() 中调用此成员。

该函数最初在Qt4.7版本引入。

另外您也可以在 incomingConnection() 函数介绍中找到相关信息。


void QTcpServer::close()

关闭服务器。服务器将不再监听到达的连接。

另外您也可以在 listen() 函数介绍中找到相关信息。


QString QTcpServer::errorString() const

将最后一个出现的错误的相关信息按照适合人阅读的形式返回。

另外您也可以在 serverError() 函数介绍中找到相关信息。


[virtual] bool QTcpServer::hasPendingConnections() const

当服务端有待处理的连接时该函数返回 true ,否则返回 false 。

另外您也可以在 nextPendingConnection() 和 setMaxPendingConnections() 函数中找到相关信息。


[virtual protected] void QTcpServer::incomingConnection(qintptrsocketDescriptor)

当有新的连接到达时, QTcpServer 会调用该虚函数。 socketDescriptor 参数是为该连接指定的本机套接字描述符。

对该虚函数重写,您需要进行以下操作:

重写此函数,以在连接可用时更改服务器的行为。

如果该服务器使用了 QNetworkProxysocketDescriptor 可能并不能被本地套接字功能使用,应该仅被 QTcpSocket::setSocketDescriptor() 函数使用。

注意: 如果在这个方法中创建了另外一个套接字,该套接字需要通过调用 addPendingConnection() 函数添加到连接处理机制中。

注意: 如果您想在另外一个线程中将到达的连接当作一个新的 QTcpSocket 进行处理,您需要将套接字描述符传递到那个线程中并在那个线程中创建一个 QTcpSocket 对象并使用该该对象的 setSocketDescriptor() 方法。

另外您也可以在 newConnection() ,nextPendingConnection() 和 addPendingConnection() 函数介绍中找到相关信息。


bool QTcpServer::isListening() const

当服务端正在监听连接时返回 true ,否则返回 false 。

另外您也可以在 listen() 函数介绍中找到相关信息。


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

令服务端监听在 address 指定的地址和 port 指定的端口上到达的连接。如果 port 参数为0 ,QTcpServer 会自动选择一个端口。 如果 address 参数为 QHostAddress::Any ,服务端会监听所有的网络接口。

操作成功该函数返回 true ,否则返回 false 。

另外您也可以在 isListening() 函数介绍中找到相关信息。


int QTcpServer::maxPendingConnections() const

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

另外您也可以在 setMaxPendingConnections() 和 hasPendingConnections() 函数介绍中找到相关信息。


[virtual] QTcpSocket *QTcpServer::nextPendingConnection()

将下一个待处理的连接作为已连接的 QTcpSocket 对象返回。

该套接字将作为该服务端的子对象创建,这就意味着当 QTcpServer 对象销毁后,该套接字对象也会被销毁。最好在完成处理后显式删除该对象,以避免浪费内存。

如果没有待处理的连接,该函数会返回 nullptr

注意: 返回的 QTcpSocket 对象不能在其他线程中使用。如果您想在其他的线程中使用到达的连接,您需要重写 incomingConnection() 函数。

另外您也可以在 hasPendingConnections() 函数介绍中找到相关信息。


void QTcpServer::pauseAccepting()

暂停接收新连接。队列连接会保留在队列中。

该函数最初在Qt5.0版本引入。

另外您也可以在 resumeAccepting() 函数介绍中找到相关信息。


QNetworkProxy QTcpServer::proxy() const

返回该套接字的网络代理。默认将使用 QNetworkProxy::DefaultProxy 。

该函数最初在Qt4.1版本引入。

另外您也可以在 setProxy() 函数介绍和 QNetworkProxy 文档中找到相关信息。


void QTcpServer::resumeAccepting()

恢复接收新连接。

该函数最初在Qt5.0版本引入。

另外您也可以在 pauseAccepting() 函数介绍中找到相关信息。


QHostAddress QTcpServer::serverAddress() const

如果服务端正在监听,则返回服务端的地址,否则返回 QHostAddress::Null 。

另外您也可以在 serverPort() 和 listen() 函数介绍中找到相关信息。


QAbstractSocket::SocketError QTcpServer::serverError() const

返回最后出现的错误的代码。

另外您也可以在 errorString() 函数介绍中找到相关信息。


quint16 QTcpServer::serverPort() const

如果服务端正在监听,则返回服务端的端口,否则返回 0 。

另外您也可以在 serverAddress() 和 listen() 函数介绍中找到相关信息。


void QTcpServer::setMaxPendingConnections(int numConnections)

设置待处理的已接受连接的数目最大值为 numConnections 。超过该数目后,在调用 nextPendingConnection() 函数之前, QTcpServer 将不会再接收到达的连接。默认情况下,QTcpServer接收连接的最大值为30。

服务器达到其最大待处理连接数后,客户端仍然可以连接(即 QTcpSocket 仍可以发出 connected() 信号)。 QTcpServer 将停止接受新连接,但是操作系统仍可以将它们保持在队列中。

另外您也可以在 maxPendingConnections() 和 hasPendingConnections() 函数介绍中找到相关信息。


void QTcpServer::setProxy(const QNetworkProxy &networkProxy)

显式设置该套接字的网络代理为 networkProxy

您通过设置使用 QNetworkProxy::NoProxy 代理类型来禁止套接字使用代理:

 server->setProxy(QNetworkProxy::NoProxy);

该函数最初在Qt4.1版本时引入。

另外您也可以在 proxy() 函数介绍和 QNetworkProxy 文档中找到相关信息。


bool QTcpServer::setSocketDescriptor(qintptr socketDescriptor)

设置该服务端监听连接时使用的套接字描述符为 socketDescriptor 。当操作成功时返回 true ,否则返回 false 。

调用该函数时,服务端应该处于正在监听的状态。

另外您也可以在 socketDescriptor() 和 isListening() 函数介绍中找到相关信息。


qintptr QTcpServer::socketDescriptor() const

返回服务端监听连接时使用的套接字描述符,如果该服务器未处于监听状态返回-1。

如果服务器正在使用 QNetworkProxy ,返回的套接字描述符可能并不能在本地套接字函数中使用。

另外您也可以在 setSocketDescriptor()() 和 isListening() 函数介绍中找到相关信息。


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

等待 msec 毫秒或者直到有新的连接接入。如果有新的连接,该函数返回 true , 否则返回 false 。如果 timeOut 参数不为 nullptr 并且操作超时, *timeOut 将被设置为 true 。

这是一个可以引起阻塞的函数。不推荐在一个单线程的 GUI 程序中使用该函数,因为使用该函数后直到该函数返回之前整个应用程序会停止响应。 waitForNewConnection() 函数通常在没有事件循环的情况下使用。

不阻塞应用程序的可选方案是使用 newConnection() 信号。

如果 msec 参数设置为-1,该函数将不会超时。

另外您也可以在 hasPendingConnections() 和 nextPendingConnection() 函数介绍中找到相关信息。