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)

使用BindMode mode 绑定port 端口上的address 。

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

对于 TCP 套接字，该函数可用于指定输出连接使用哪个接口，这在使用多个网络接口时非常有用。

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

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

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

这是一个重载函数。

使用BindMode mode 绑定到QHostAddress:Any on portport 。

默认情况下，套接字使用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() 常量。

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

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

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

重实现：QIODevice::bytesToWrite() 常量。

返回等待写入的字节数。当控制返回事件循环或调用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 QAbstractSocket 仅在需要时才会进行查找。 采用本机字节顺序。port

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

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

这是一个重载函数。

尝试与address （端口：port ）建立连接。

[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)。