QAbstractSocket类

成员函数文档

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)

绑定到地址上的端口号端口号，使用绑定模式 模式。

对于UDP套接字，在绑定后，每当在网络指定的地址和端口号上接收到UDP数据包时，都会发出信号QUdpSocket::readyRead。因此，这个函数对编写UDP服务器非常有用。

对于TCP套接字，此函数可以用来指定要使用哪个接口进行出站连接，这对于有多个网络接口的情况很有用。

默认情况下，套接字使用DefaultForPlatform 绑定模式进行绑定。如果没有指定端口号，将会选择一个随机端口号。

如果成功，函数返回true，套接字进入绑定状态；否则返回false。

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

这是一个重载函数。

绑定到特殊地址addr上的端口号端口号，使用绑定模式 模式。

默认情况下，套接字使用DefaultForPlatform 绑定模式进行绑定。如果没有指定端口号，将会选择一个随机端口号。

此函数首次在Qt 6.2中引入。

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

这是一个重载函数。

绑定到QHostAddress:Any上的端口号端口号，使用绑定模式 模式。

默认情况下，套接字使用DefaultForPlatform 绑定模式进行绑定。如果没有指定端口号，将会选择一个随机端口号。

[重写虚拟] qint64 QAbstractSocket::bytesAvailable() const

重写了QIODevice::bytesAvailable() const。

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

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

[重写虚拟] qint64 QAbstractSocket::bytesToWrite() const

重写了QIODevice::bytesToWrite() const。

返回等待写入的字节数。这些字节将在事件循环回来或调用flush()时写入。

另请参阅bytesAvailable()和flush。

[重写虚拟] void QAbstractSocket::close()

重写了QIODevice::close。

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

有关I/O设备关闭时发生的操作的描述，请参阅QIODevice::close。

另请参阅abort。

[虚拟] void QAbstractSocket::connectToHost(const QString &主机名, quint16 端口号, QIODeviceBase::OpenMode openMode = ReadWrite, QAbstractSocket::NetworkLayerProtocol 协议 = AnyIPProtocol)

尝试连接到给定 主机名 和 端口号。可以通过 协议 参数指定要使用的网络协议（例如，IPv4 或 IPv6）。

套接字以给定的 openMode 打开，首先进入 HostLookupState 状态，然后进行 主机名 查找。如果查找成功，将发出 hostFound() 信号，并使 QAbstractSocket 进入 ConnectingState 状态。然后尝试连接到查找返回的地址或地址。最后，如果建立了连接，QAbstractSocket 将进入 ConnectedState 并发出 connected() 信号。

在任何时候，套接字都可以发出 errorOccurred() 信号，以表示发生错误。

主机名 可能是字符串形式的 IP 地址（例如，"43.195.83.32"），也可能是主机名（例如，"example.com"）。QAbstractSocket 仅在有需要时进行查找。端口号 使用本地字节序。

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

void QAbstractSocket::connectToHost(const QHostAddress &地址, quint16 端口号, QIODeviceBase::OpenMode openMode = ReadWrite)

这是一个重载函数。

尝试连接到端口 端口号 的 地址。

[信号] void QAbstractSocket::connected()

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

另请参阅connectToHost() 和 disconnected。

[虚拟] void QAbstractSocket::disconnectFromHost()

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

另请参阅connectToHost。

[信号] void QAbstractSocket::disconnected()

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

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

QAbstractSocket::SocketError QAbstractSocket::error() const

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

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

[信号] void QAbstractSocket::errorOccurred(QAbstractSocket::SocketError socketError)

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

当此信号发出时，套接字可能不适合进行重连尝试。在这种情况下，应该从事件循环中进行重连尝试。例如，可以使用 0 作为超时的 QTimer::singleShot()。

QAbstractSocket::SocketError 不是一个已注册的元类型，因此对于队列连接，您必须使用 Q_DECLARE_METATYPE() 和 qRegisterMetaType() 进行注册。

另请参阅 error()、errorString() 和 创建自定义 Qt 类型。

bool QAbstractSocket::flush()

此函数将尽可能多的数据从内部写入缓冲区写入到底层网络套接字，而不阻塞。如果写入了数据，则此函数返回 true；否则返回 false。

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

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

[信号] void QAbstractSocket::hostFound()

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

另请参阅 connected()。

[重写虚拟] 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)

当使用需要认证的代理时，可能会触发此信号。此时，可以将认证对象填充所需详细信息，以允许认证并继续连接。

另请参阅：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()。

[保护] void QAbstractSocket::setLocalPort(quint16 port)

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

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

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

另请参见 localPort()，localAddress()，setLocalAddress()以及setPeerPort()。

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

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

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

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

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

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

另请参见 peerAddress()，setPeerPort()以及setLocalAddress()。

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

将远程对端的主机名设置为名称。

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

另请参见 peerName()。

[受保护] void QAbstractSocket::setPeerPort(quint16 端口号)

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

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

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

void QAbstractSocket::setProtocolTag(const QString &标签)

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

另请参阅 protocolTag()。

void QAbstractSocket::setProxy(const QNetworkProxy &网络代理)

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

要禁用此套接字使用代理，请使用QNetworkProxy::NoProxy代理类型

socket->setProxy(QNetworkProxy::NoProxy);

代理的默认值为QNetworkProxy::DefaultProxy，这意味着套接字将使用应用程序设置：如果使用QNetworkProxy::setApplicationProxy设置了代理，它将使用该代理；如果没有设置工厂，将与QNetworkProxyFactory::setApplicationProxyFactory设置的生产厂查询，类型为QNetworkProxyQuery::TcpSocket。

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

[虚函数] void QAbstractSocket::setReadBufferSize(qint64 大小)

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

如果缓冲区大小限制为特定大小，QAbstractSocket不会缓冲超过此大小的数据。例外情况下，缓冲区大小为0意味着读取缓冲区无限大，所有传入数据都会被缓冲。这是默认情况。

此选项对于仅在特定时间点读取数据（例如，在实时流应用程序中）或想要防止套接字接收过多数据，这些数据最终可能导致应用程序内存不足非常有用。

只有QTcpSocket使用QAbstractSocket的内部缓冲区；《QUdpSocket》不使用任何缓冲区，而是依赖于操作系统提供的隐式缓冲。正因为如此，在QUdpSocket上调用此函数没有任何效果。

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

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

初始化使用本地套接字描述符 socketDescriptor 的 QAbstractSocket。如果 socketDescriptor 被接受为一个有效的套接字描述符，则返回 true；否则返回 false。套接字将以 openMode 指定的模式打开，并进入由 socketState 指定的套接字状态。清除读取和写入缓冲区，丢弃任何挂起数据。

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

另请参阅：socketDescriptor()。

[保护] void QAbstractSocket::setSocketError(QAbstractSocket::SocketError socketError)

设置最后一次发生的错误类型为 socketError。

另请参阅：setSocketState() 和 setErrorString).

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

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

另请参阅：socketOption().

[保护] void QAbstractSocket::setSocketState(QAbstractSocket::SocketState state)

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

另请参阅 state()。

[重写虚拟保护] qint64 QAbstractSocket::skipData(qint64 maxSize)

重新实现: QIODevice::skipData(qint64 maxSize)。

[虚拟] qintptr QAbstractSocket::socketDescriptor() const

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

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

QAbstractSocket 在 UnconnectedState 时不可访问套接字描述符。

另请参阅：setSocketDescriptor().

[虚拟] QVariant QAbstractSocket::socketOption(QAbstractSocket::SocketOption option)

返回 option 选项的值。

另请参阅：setSocketOption().

QAbstractSocket::SocketType QAbstractSocket::socketType() const

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

另请参阅 QTcpSocket和QUdpSocket。

QAbstractSocket::SocketState QAbstractSocket::state() const

返回套接字的状态。

另请参阅 error()。

[信号] void QAbstractSocket::stateChanged(QAbstractSocket::SocketState socketState)

当QAbstractSocket的状态发生变化时，会发出此信号。参数socketState是新状态。

QAbstractSocket::SocketState 不是一个已注册的元类型，所以对于延迟连接，您必须使用Q_DECLARE_METATYPE() 和 qRegisterMetaType() 来注册它。

另请参阅 state() 和 创建自定义 Qt 类型。

[重写虚函数] bool QAbstractSocket::waitForBytesWritten(int msecs = 30000)

重新实现了: QIODevice::waitForBytesWritten(int msecs)

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

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

另请参阅 waitForReadyRead。

[虚函数] 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。

[虚拟] 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。

[覆盖虚函数] bool QAbstractSocket::waitForReadyRead( int msecs = 30000)

重实现： QIODevice::waitForReadyRead (int msecs).

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

如果发出 readyRead () 信号且存在可读的新数据，则此函数返回 true ；否则返回 false （如果发生错误或操作超时）。

另请参阅 waitForBytesWritten ().

[覆盖虚保护] qint64 QAbstractSocket::writeData(const char *data, qint64 size)

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