QAbstractSocket Class

成员函数文档

QAbstractSocket::QAbstractSocket(QAbstractSocket::SocketType socketType, QObject *parent)

创建一个类型为socketType 的新抽象套接字。参数parent 将传递给QObject 的构造函数。

另请参阅 socketType()、QTcpSocket 和QUdpSocket 。

[virtual noexcept] QAbstractSocket::~QAbstractSocket()

销毁该套接字。

void QAbstractSocket::abort()

终止当前连接并重置套接字。与disconnectFromHost()不同，该函数会立即关闭套接字，并丢弃写缓冲区中所有待处理的数据。

另请参阅 disconnectFromHost() 和close()。

[virtual] bool QAbstractSocket::bind(const QHostAddress &address, quint16 port = 0, QAbstractSocket::BindMode mode = DefaultForPlatform)

在端口port 上绑定到address ，使用BindMode mode 。

对于 UDP 套接字，绑定后，每当指定地址和端口的 UDP 数据报到达时，都会触发QUdpSocket::readyRead() 信号。因此，该函数对于编写 UDP 服务器非常有用。

对于 TCP 套接字，该函数可用于指定用于建立出站连接的接口，这在存在多个网络接口时非常有用。

默认情况下，套接字会绑定到DefaultForPlatform BindMode 。如果未指定端口，则会选择一个随机端口。

成功时，该函数返回true ，套接字进入BoundState 状态；否则返回false 。

bool QAbstractSocket::bind(quint16 port = 0, QAbstractSocket::BindMode mode = DefaultForPlatform)

在端口port 上绑定到QHostAddress:Any，使用BindMode mode 。

默认情况下，套接字使用DefaultForPlatform BindMode 进行绑定。如果未指定端口，则会选择一个随机端口。

[since 6.2] bool QAbstractSocket::bind(QHostAddress::SpecialAddress addr, quint16 port = 0, QAbstractSocket::BindMode mode = DefaultForPlatform)

使用BindMode mode 将套接字绑定到端口port 上的特殊地址addr 。

默认情况下，套接字会使用DefaultForPlatform BindMode 进行绑定。如果未指定端口，则会选择一个随机端口。

该函数在 Qt 6.2 中引入。

[override virtual] qint64 QAbstractSocket::bytesAvailable() const

重写：QIODevice::bytesAvailable() const。

返回等待读取的传入字节数。

另请参阅 bytesToWrite() 和read()。

[override virtual] qint64 QAbstractSocket::bytesToWrite() const

重新实现了：QIODevice::bytesToWrite() const。

返回待写入的字节数。当控制权返回事件循环或调用flush() 时，这些字节将被写入。

另请参阅 bytesAvailable() 和flush()。

[override virtual] void QAbstractSocket::close()

重写了：QIODevice::close()。

关闭套接字对应的 I/O 设备，并调用disconnectFromHost() 来关闭套接字的连接。

有关关闭 I/O 设备时执行的操作说明，请参阅QIODevice::close()。

另请参阅 abort()。

[virtual] void QAbstractSocket::connectToHost(const QString &hostName, quint16 port, QIODeviceBase::OpenMode openMode = ReadWrite, QAbstractSocket::NetworkLayerProtocol protocol = AnyIPProtocol)

尝试通过给定的port 连接到hostName 。可以使用protocol 参数指定要使用的网络协议（例如IPv4或IPv6）。

套接字在指定的openMode 中打开，首先进入HostLookupState 状态，然后对hostName 进行主机名查询。如果查询成功，将触发hostFound() 事件，且QAbstractSocket 进入ConnectingState 状态。随后，它将尝试连接查询返回的一个或多个地址。最后，如果建立连接，QAbstractSocket 进入ConnectedState 状态并触发connected() 事件。

在任何时候，套接字都可以发出errorOccurred() 来指示发生了错误。

hostName 可能是一个字符串形式的 IP 地址（例如，“43.195.83.32”），也可能是主机名（例如，“example.com”）。QAbstractSocket 仅在必要时才会进行查询。port 采用本机字节序。

另请参阅 state()、peerName()、peerAddress()、peerPort() 以及waitForConnected()。

void QAbstractSocket::connectToHost(const QHostAddress &address, quint16 port, QIODeviceBase::OpenMode openMode = ReadWrite)

正在尝试通过端口port 连接到address 。

[signal] void QAbstractSocket::connected()

在调用connectToHost()并成功建立连接后，会发出此信号。

另请参阅 connectToHost() 和disconnected()。

[virtual] void QAbstractSocket::disconnectFromHost()

尝试关闭套接字。如果存在待写入的数据，QAbstractSocket 将进入ClosingState 状态，并等待直至所有数据写入完毕。最终，它将进入UnconnectedState 状态，并发出disconnected()信号。

另请参阅 connectToHost()。

[signal] void QAbstractSocket::disconnected()

当套接字断开连接时，会发出此信号。

另请参阅 connectToHost()、disconnectFromHost() 和abort()。

QAbstractSocket::SocketError QAbstractSocket::error() const

返回上次发生的错误类型。

另请参阅 state() 和errorString()。

[signal] void QAbstractSocket::errorOccurred(QAbstractSocket::SocketError socketError)

该信号在发生错误后触发。socketError 参数描述了发生的错误类型。

当此信号被触发时，套接字可能尚未准备好进行重新连接尝试。在这种情况下，应从事件循环中进行重新连接尝试。例如，使用 QChronoTimer::singleShot() 并设置超时时间为 0ns。

QAbstractSocket::SocketError 并非已注册的元类型，因此对于队列连接，您必须通过Q_DECLARE_METATYPE() 和qRegisterMetaType() 对其进行注册。

另请参阅 error()、errorString() 以及《创建自定义 Qt 类型》。

bool QAbstractSocket::flush()

该函数会尽可能多地将内部写缓冲区中的数据写入底层网络套接字，且不会阻塞。如果成功写入了任何数据，该函数返回true ；否则返回false。

若需让QAbstractSocket 立即开始发送缓冲数据，请调用此函数。成功写入的字节数取决于操作系统。在大多数情况下，您无需调用此函数，因为一旦控制权返回事件循环，QAbstractSocket 将自动开始发送数据。若不存在事件循环，请改调用waitForBytesWritten()。

另请参阅 write() 和waitForBytesWritten()。

[signal] void QAbstractSocket::hostFound()

在调用connectToHost() 且主机查找成功后，会发出此信号。

另请参阅 connected()。

[override virtual] bool QAbstractSocket::isSequential() const

重新实现了：QIODevice::isSequential() const。

bool QAbstractSocket::isValid() const

如果套接字有效且已准备就绪，则返回true ；否则返回false 。

另请参阅 state()。

QHostAddress QAbstractSocket::localAddress() const

如果可用，则返回本地套接字的主机地址；否则返回QHostAddress::Null 。

这通常是主机的主 IP 地址，但在连接到本地主机时，可能会返回QHostAddress::LocalHost （127.0.0.1）。

另请参阅 localPort()、peerAddress() 和setLocalAddress()。

quint16 QAbstractSocket::localPort() const

如果可用，则返回本地套接字的主机端口号（以本机字节序表示）；否则返回 0。

另请参阅 localAddress()、peerPort() 和setLocalPort()。

QAbstractSocket::PauseModes QAbstractSocket::pauseMode() const

返回此套接字的暂停模式。

另请参阅 setPauseMode() 和resume()。

QHostAddress QAbstractSocket::peerAddress() const

如果套接字处于ConnectedState 状态，则返回已连接对等方的地址；否则返回QHostAddress::Null 。

另请参阅 peerName()、peerPort()、localAddress() 和setPeerAddress()。

QString QAbstractSocket::peerName() const

返回由connectToHost() 指定的对等方名称；如果尚未调用connectToHost()，则返回空的QString 。

另请参阅 peerAddress()、peerPort() 和setPeerName()。

quint16 QAbstractSocket::peerPort() const

如果套接字处于ConnectedState 状态，则返回已连接对端的端口；否则返回0。

另请参阅 peerAddress()、localPort() 和setPeerPort()。

QString QAbstractSocket::protocolTag() const

返回此套接字的协议标记。如果设置了协议标记，则在内部创建QNetworkProxyQuery 时，该标记会被传递给它，以指示应使用的协议标记。

另请参阅 setProtocolTag() 和QNetworkProxyQuery 。

QNetworkProxy QAbstractSocket::proxy() const

返回此套接字的网络代理。默认情况下使用QNetworkProxy::DefaultProxy ，这意味着该套接字将查询应用程序的默认代理设置。

另请参阅 setProxy()、QNetworkProxy 以及QNetworkProxyFactory 。

[signal] void QAbstractSocket::proxyAuthenticationRequired(const QNetworkProxy &proxy, QAuthenticator *authenticator)

当使用需要身份验证的proxy 时，可能会触发此信号。此时，可向authenticator 对象填充所需的详细信息，以完成身份验证并继续建立连接。

另请参阅 QAuthenticator 和QNetworkProxy 。

qint64 QAbstractSocket::readBufferSize() const

返回内部读取缓冲区的大小。这限制了在调用read()或readAll()之前，客户端可接收的数据量。

读取缓冲区大小为 0（默认值）表示缓冲区没有大小限制，从而确保不会丢失任何数据。

另请参阅 setReadBufferSize() 和read()。

[override virtual protected] qint64 QAbstractSocket::readData(char *data, qint64 maxSize)

重写了：QIODevice::readData （char *data, qint64 maxSize）。

[override virtual protected] qint64 QAbstractSocket::readLineData(char *data, qint64 maxlen)

重写了：QIODevice::readLineData(char *data, qint64 maxSize)。

[virtual] void QAbstractSocket::resume()

继续通过套接字传输数据。仅当套接字已被设置为在收到通知时暂停，且已收到通知后，才应使用此方法。目前唯一支持的通知是QSslSocket::sslErrors()。如果套接字未处于暂停状态而调用此方法，将导致未定义的行为。

另请参阅 pauseMode() 和setPauseMode()。

[protected] void QAbstractSocket::setLocalAddress(const QHostAddress &address)

将连接本地端的地址设置为address 。

您可以在QAbstractSocket 的子类中调用此函数，以在连接建立后更改localAddress() 函数的返回值。此功能通常用于代理连接中的虚拟连接设置。

请注意，此函数不会在建立连接之前（例如，QAbstractSocket::bind()）绑定套接字的本地地址。

另请参阅 localAddress()、setLocalPort() 和setPeerAddress()。

[protected] void QAbstractSocket::setLocalPort(quint16 port)

将连接本地端的端口设置为port 。

您可以在QAbstractSocket 的子类中调用此函数，以在连接建立后修改localPort() 函数的返回值。此功能通常用于代理连接中的虚拟连接设置。

请注意，此函数不会在建立连接之前（例如，QAbstractSocket::bind()) 绑定套接字的本地端口。

另请参阅 localPort()、localAddress()、setLocalAddress() 和setPeerPort()。

void QAbstractSocket::setPauseMode(QAbstractSocket::PauseModes pauseMode)

控制在收到通知时是否暂停。pauseMode 参数指定了应暂停套接字的条件。 当前仅支持QSslSocket::sslErrors()这一种通知。若设置为PauseOnSslErrors ，套接字上的数据传输将被暂停，需通过调用resume()显式重新启用。默认情况下，此选项设置为PauseNever 。必须在连接到服务器之前调用此选项，否则将导致未定义行为。

另请参阅 pauseMode() 和resume()。

[protected] void QAbstractSocket::setPeerAddress(const QHostAddress &address)

将连接远端的地址设置为address 。

您可以在QAbstractSocket 的子类中调用此函数，以在连接建立后修改peerAddress() 函数的返回值。此功能通常用于代理连接中的虚拟连接设置。

另请参阅 peerAddress()、setPeerPort() 和setLocalAddress()。

[protected] void QAbstractSocket::setPeerName(const QString &name)

将远程对等方的主机名设置为name 。

您可以在QAbstractSocket 的子类中调用此函数，以便在建立连接后更改peerName() 函数的返回值。此功能通常用于代理连接中的虚拟连接设置。

另请参阅 peerName()。

[protected] void QAbstractSocket::setPeerPort(quint16 port)

将连接远程端的端口设置为port 。

您可以在 `QAbstractSocket ` 的子类中调用此函数，以在建立连接后更改 `peerPort()` 函数的返回值。此功能通常用于代理连接中的虚拟连接设置。

另请参阅 peerPort()、setPeerAddress() 和setLocalPort()。

void QAbstractSocket::setProtocolTag(const QString &tag)

将此套接字的协议标签设置为tag 。

另请参阅 protocolTag()。

void QAbstractSocket::setProxy(const QNetworkProxy &networkProxy)

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

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

socket->setProxy(QNetworkProxy::NoProxy);

代理的默认值为QNetworkProxy::DefaultProxy ，这意味着该套接字将使用应用程序设置：如果已通过QNetworkProxy::setApplicationProxy 设置了代理，则使用该代理；否则，如果已通过QNetworkProxyFactory::setApplicationProxyFactory 设置了工厂，则会以QNetworkProxyQuery::TcpSocket 类型查询该工厂。

另请参阅 proxy()、QNetworkProxy 和QNetworkProxyFactory::queryProxy()。

[virtual] void QAbstractSocket::setReadBufferSize(qint64 size)

将QAbstractSocket 的内部读取缓冲区大小设置为size 字节。

如果缓冲区大小被限制在某个值，QAbstractSocket 不会缓冲超过该大小数据。例外情况是，缓冲区大小为 0 时，表示读取缓冲区无限制，所有传入数据都会被缓冲。这是默认行为。

如果仅在特定时间点读取数据（例如在实时流媒体应用中），或者希望保护套接字免于接收过多数据（这最终可能导致应用程序内存不足），则此选项非常有用。

只有 `QTcpSocket ` 会使用 `QAbstractSocket` 的内部缓冲区；而 `QUdpSocket ` 则完全不使用任何缓冲，而是依赖操作系统提供的隐式缓冲。因此，在 `QUdpSocket ` 上调用此函数不会产生任何效果。

另请参阅 readBufferSize() 和read()。

[virtual] bool QAbstractSocket::setSocketDescriptor(qintptr socketDescriptor, QAbstractSocket::SocketState socketState = ConnectedState, QIODeviceBase::OpenMode openMode = ReadWrite)

使用本机套接字描述符socketDescriptor 初始化抽象套接字QAbstractSocket 。如果socketDescriptor 被接受为有效的套接字描述符，则返回true ；否则返回false 。套接字将以openMode 指定的模式打开，并进入socketState 指定的套接字状态。读写缓冲区将被清空，并丢弃任何待处理的数据。

注意：无法使用同一个本机套接字描述符初始化两个抽象套接字。

另请参阅 socketDescriptor()。

[protected] void QAbstractSocket::setSocketError(QAbstractSocket::SocketError socketError)

将上次发生的错误类型设置为socketError 。

另请参阅 setSocketState() 和setErrorString()。

[virtual] void QAbstractSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)

将给定的option 设置为value 中描述的值。

另请参阅 socketOption()。

[protected] void QAbstractSocket::setSocketState(QAbstractSocket::SocketState state)

将套接字的状态设置为state 。

另请参阅 state()。

[override virtual protected] qint64 QAbstractSocket::skipData(qint64 maxSize)

重实现了：QIODevice::skipData （qint64 maxSize）。

[virtual] qintptr QAbstractSocket::socketDescriptor() const

如果QAbstractSocket 对象的本地套接字描述符可用，则返回该描述符；否则返回-1。

如果该套接字正在使用QNetworkProxy ，则返回的描述符可能无法与本机套接字函数一起使用。

当 `QAbstractSocket ` 处于 `UnconnectedState` 状态时，该套接字描述符不可用。

另请参阅 setSocketDescriptor()。

[virtual] QVariant QAbstractSocket::socketOption(QAbstractSocket::SocketOption option)

返回option 选项的值。

另请参阅 setSocketOption()。

QAbstractSocket::SocketType QAbstractSocket::socketType() const

返回套接字类型（TCP、UDP 或其他）。

另请参阅 QTcpSocket 和QUdpSocket 。

QAbstractSocket::SocketState QAbstractSocket::state() const

返回套接字的状态。

另请参阅 error()。

[signal] void QAbstractSocket::stateChanged(QAbstractSocket::SocketState socketState)

每当QAbstractSocket 的状态发生变化时，都会触发此信号。socketState 参数表示新状态。

QAbstractSocket::SocketState 并非已注册的元类型，因此对于队列连接，您必须通过Q_DECLARE_METATYPE() 和qRegisterMetaType() 对其进行注册。

另请参阅 state() 以及《创建自定义 Qt 类型》。

[override virtual] bool QAbstractSocket::waitForBytesWritten(int msecs = 30000)

重写了：QIODevice::waitForBytesWritten(int msecs)。

该函数将阻塞，直到套接字上至少写入了一个字节且触发了bytesWritten()信号。该函数将在msecs 毫秒后超时；默认超时时间为30000毫秒。

如果触发了bytesWritten() 信号，该函数返回true ；否则返回false （表示发生错误或操作超时）。

另请参阅 waitForReadyRead()。

[virtual] bool QAbstractSocket::waitForConnected(int msecs = 30000)

等待套接字建立连接，最长等待时间为msecs 毫秒。如果已建立连接，该函数返回true ；否则返回false 。若返回false ，可调用error()来确定错误原因。

以下示例最多等待一秒钟以建立连接：

socket->connectToHost("imap", 143);
if(socket->waitForConnected(1000))
    qDebug("Connected!");

如果 msecs 的值为 -1，则该函数不会超时。

另请参阅 connectToHost() 和connected()。

[virtual] bool QAbstractSocket::waitForDisconnected(int msecs = 30000)

等待套接字断开连接，最长等待msecs 毫秒。如果连接成功断开，该函数返回true ；否则返回false （如果操作超时、发生错误，或者该QAbstractSocket 已断开连接）。如果返回false ，可以调用error()来确定错误原因。

以下示例将等待最多一秒钟，直到连接关闭：

socket->disconnectFromHost();
if(socket->state()==QAbstractSocket::UnconnectedState
    || socket->waitForDisconnected(1000)) {
        qDebug("Disconnected!");
}

如果 msecs 的值为 -1，则该函数不会超时。

另请参阅 disconnectFromHost() 和close()。

[override virtual] bool QAbstractSocket::waitForReadyRead(int msecs = 30000)

重写自：QIODevice::waitForReadyRead(int msecs)。

该函数将阻塞，直到有新数据可供读取且已发出readyRead()信号为止。该函数将在msecs 毫秒后超时；默认超时时间为30000毫秒。

如果触发了readyRead() 信号且有新数据可供读取，该函数将返回true ；否则将返回false （表示发生错误或操作超时）。

另请参阅 waitForBytesWritten()。

[override virtual protected] qint64 QAbstractSocket::writeData(const char *data, qint64 size)

重新实现了：QIODevice::writeData(const char *data, qint64 maxSize)。