QTcpServer Class

成员函数文档

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

创建一个 QTcpServer 对象。

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

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

[virtual noexcept] QTcpServer::~QTcpServer()

销毁QTcpServer 对象。如果服务器正在监听连接，则会自动关闭套接字。

在删除服务器之前，任何仍处于连接状态的客户端 `QTcpSocket` 对象必须先断开连接，或者将其父对象重新设置。

另请参阅 close()。

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

当接受新连接时发生错误，将发出此信号。socketError 参数描述了发生的错误类型。

另请参阅 pauseAccepting() 和resumeAccepting()。

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

该函数由QTcpServer::incomingConnection()调用，用于将socket 添加到待处理的传入连接列表中。

另请参阅 incomingConnection() 和pendingConnectionAvailable()。

void QTcpServer::close()

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

另请参阅 listen()。

QString QTcpServer::errorString() const

返回最近发生的错误的通俗易懂的描述。

另请参阅 serverError()。

[virtual] bool QTcpServer::hasPendingConnections() const

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

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

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

当有新连接可用时，QTcpServer 会调用此虚拟函数。参数socketDescriptor 是已接受连接的原生套接字描述符。

基础实现会创建一个 `QTcpSocket`，设置套接字描述符，然后将 `QTcpSocket ` 存储到待处理连接的内部列表中。最后触发 `newConnection()`。

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

如果该服务器使用的是QNetworkProxy ，则socketDescriptor 可能无法与本机套接字函数配合使用，而应仅与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，则自动选择端口。如果address 为QHostAddress::Any ，服务器将在所有网络接口上监听。

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

另请参阅 isListening()。

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

返回待接受连接的积压队列大小。

该函数在 Qt 6.3 中引入。

另请参阅 setListenBacklogSize()。

int QTcpServer::maxPendingConnections() const

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

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

[signal] void QTcpServer::newConnection()

每当有新的连接可用时，都会触发此信号，无论该连接是否已被添加到待处理连接队列中。

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

[virtual] QTcpSocket *QTcpServer::nextPendingConnection()

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

该套接字作为服务器的子节点创建，这意味着当QTcpServer 对象被销毁时，它会自动被删除。但建议在使用完毕后显式删除该对象，以避免浪费内存。

nullptr 若在无待处理连接时调用此函数，则返回。

另请参阅 hasPendingConnections()。

void QTcpServer::pauseAccepting()

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

另请参阅 resumeAccepting()。

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

每当有新的连接被添加到待处理连接队列中时，都会发出此信号。

该函数在 Qt 6.4 中引入。

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

QNetworkProxy QTcpServer::proxy() const

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

另请参阅 setProxy() 和QNetworkProxy 。

void QTcpServer::resumeAccepting()

恢复接受新连接。

另请参阅 pauseAccepting()。

QHostAddress QTcpServer::serverAddress() const

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

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

QAbstractSocket::SocketError QTcpServer::serverError() const

返回最近一次发生的错误的错误代码。

另请参阅 errorString()。

quint16 QTcpServer::serverPort() const

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

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

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

将待接受连接的积压队列大小设置为size 。操作系统可能会缩减或忽略此值。默认情况下，队列大小为50。

该函数于 Qt 6.3 中引入。

另请参阅 listenBacklogSize()。

void QTcpServer::setMaxPendingConnections(int numConnections)

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

即使服务器已达到最大待处理连接数，客户端仍可能能够连接（即QTcpSocket 仍可能发出 connected() 信号）。QTcpServer 将停止接受新连接，但操作系统仍可能将它们保留在队列中。

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

void QTcpServer::setProxy(const QNetworkProxy &networkProxy)

将此套接字的显式网络代理设置为networkProxy 。

若要禁用此套接字的代理功能，请使用QNetworkProxy::NoProxy 代理类型：

server->setProxy(QNetworkProxy::NoProxy);

另请参阅 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 。如果操作超时且timedOut 不为nullptr ，则*timedOut 将被设置为true。

这是一个阻塞式函数调用。不建议在单线程 GUI 应用程序中使用该函数，因为整个应用程序将停止响应，直到该函数返回为止。waitForNewConnection() 主要在没有可用事件循环时才派上用场。

非阻塞的替代方案是订阅newConnection()信号。

如果 msec 为 -1，则此函数不会超时。

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