QNetworkDatagram Class

成员函数文档

QNetworkDatagram::QNetworkDatagram()

创建一个不包含有效载荷数据且目标地址未定义的 QNetworkDatagram 对象。

可以通过调用setData()来修改有效载荷，并通过setDestination()设置目标地址。

如果目标地址未定义，QUdpSocket::writeDatagram() 将尝试将数据报发送至上次通过QUdpSocket::connectToHost() 关联的地址。

QNetworkDatagram::QNetworkDatagram(const QByteArray &data, const QHostAddress &destinationAddress = QHostAddress(), quint16 port = 0)

创建一个 QNetworkDatagram 对象，并将data 设置为有效载荷数据，同时将destinationAddress 和port 分别设置为数据报的目的地地址。

QNetworkDatagram::QNetworkDatagram(const QNetworkDatagram &other)

创建other 数据报的副本，包括有效载荷和元数据。

若要创建一个适合用于发送回复的数据报，请使用QNetworkDatagram::makeReply();

void QNetworkDatagram::clear()

清除此QNetworkDatagram 对象中的有效载荷数据和元数据，并将它们重置为默认值。

QByteArray QNetworkDatagram::data() const

返回此数据报的数据有效载荷。对于从网络接收到的数据报，该参数包含该数据报的有效载荷；对于待发送的数据报，该参数即为待发送的数据报本身。

请注意，数据报可能不包含任何数据，因此返回的QByteArray 可能为空。

另请参阅 setData()。

QHostAddress QNetworkDatagram::destinationAddress() const

返回与该数据报关联的目的地地址。对于从网络接收到的数据报，该地址是对等节点发送该数据报的目标地址，可以是本机的本地地址，也可以是组播或广播地址。对于出站数据报，该地址则是数据报应发送到的地址。

如果该数据报未设置目标地址，则返回的对象在调用 `QHostAddress::isNull()` 时将返回 `true`。

另请参阅 senderAddress()、destinationPort() 和setDestination()。

int QNetworkDatagram::destinationPort() const

返回与该数据报关联的目的地端口号。对于从网络接收到的数据报，该端口号即为对等节点发送该数据报所针对的本地端口号；对于发出的数据报，该端口号即为数据报应发送到的对等端口。

如果该数据报未关联任何目标地址，则此函数返回 -1。

另请参阅 destinationAddress()、senderPort()，以及setDestination()。

int QNetworkDatagram::hopLimit() const

返回与该数据报相关联的跃点数限制。跃点数限制是指在IP数据包过期并向数据报发送方返回错误之前，允许该数据包被转发经过的节点数量。在IPv4中，该值通常被称为“生存时间”（TTL）。

如果该数据报是从网络接收的，则此值为接收后数据报的剩余跳数，且该值在数据报被每个中继节点转发时都会减 1。值为 -1 表示无法获取该跳数限制。

如果是出站数据报，则此值将在发送时设置在 IP 报头中。值为 -1 表示应由操作系统选择该值。

另请参阅 setHopLimit()。

uint QNetworkDatagram::interfaceIndex() const

返回该数据报关联的接口索引。接口索引是一个正数，用于在操作系统中唯一标识网络接口。该数字与QNetworkInterface::index() 函数针对该接口返回的值相匹配。

如果该数据报是从网络接收的，则此索引即为接收该数据包的接口索引；如果是出站数据报，则此索引即为应通过该接口发送数据报的接口索引。

值为 0 表示接口索引未知。

另请参阅 setInterfaceIndex()。

bool QNetworkDatagram::isNull() const

如果该QNetworkDatagram 对象为空，则返回true。该函数与isValid()的功能相反。

bool QNetworkDatagram::isValid() const

如果该QNetworkDatagram 对象有效，则返回true。一个有效的QNetworkDatagram 对象至少包含一个发送方或接收方地址。有效的数据报可以包含空有效载荷。

创建一个新的QNetworkDatagram ，表示对此传入数据报的回复，并将有效载荷数据设置为payload 。此函数是一种非常便捷的方式，用于向原始发送方回复数据报。

示例：

    void Server::readPendingDatagrams()
    {
        while (udpSocket->hasPendingDatagrams()) {
            QNetworkDatagram datagram = udpSocket->receiveDatagram();
            QByteArray replyData = processThePayload(datagram.data());
            udpSocket->writeDatagram(datagram.makeReply(replyData));
        }
    }

该函数特别方便，因为它会根据实际情况自动将此数据报中的参数复制到新数据报中：

• 将该数据报的发送方地址和端口复制到新数据报的目的地地址和端口；
• 该数据报的接口索引（如有）将复制到新数据报的接口索引中；
• 仅当该数据报的目标地址和端口为 IPv6 全局（非组播）地址时，才会被复制到新数据报的发送方地址和端口；
• 新数据报的跳数限制将重置为默认值（-1）；

如果未来版本的 Qt XML 中修改了 `QNetworkDatagram ` 以承载更多元数据，则本函数将酌情复制该元数据。

如果该数据报的目的地地址是 IPv4 地址，则不会被复制，因为如果不遍历该机器上分配的所有地址，就无法区分 IPv4 广播地址和普通 IPv4 地址。尝试发送发件人地址等于广播地址的数据报很可能会失败。 不过，这不应影响通信，因为具有多个 IPv4 地址的网络接口并不常见，因此操作系统选择的地址很可能为对端所能识别的地址。

    udpSocket->writeDatagram(std::move(datagram).makeReply(replyData));

QHostAddress QNetworkDatagram::senderAddress() const

返回与该数据报关联的发送方地址。对于从网络接收到的数据报，该地址即为发送该数据报的对等节点的地址；对于传出的数据报，该地址即为发送时将使用的本地地址。

如果该数据报未设置发件人地址，则返回的对象在调用 `QHostAddress::isNull()` 时将返回 `true`。

另请参阅 destinationAddress()、senderPort() 和setSender()。

int QNetworkDatagram::senderPort() const

返回与该数据报关联的发送方端口号。对于从网络接收的数据报，该端口号即为对等节点发送该数据报时所使用的端口号；对于出站数据报，该端口号即为应发送该数据报的本地端口号。

如果该数据报未关联任何发送方地址，则该函数返回 -1。

另请参阅 senderAddress()、destinationPort() 和setSender()。

void QNetworkDatagram::setData(const QByteArray &data)

将此数据报的数据负载设置为data 。对于已接收的数据报，通常无需调用此函数。对于待发送的数据报，此函数用于设置将在网络上发送的数据。

由于数据报可以为空，因此空的QByteArray 是data 的有效值。

另请参阅 data()。

void QNetworkDatagram::setDestination(const QHostAddress &address, quint16 port)

将与该数据报关联的目的地地址设置为地址address 和端口号port 。目的地地址和端口号通常由QUdpSocket 在接收时设置，因此无需对已接收的数据报调用此函数。

对于传出数据报，可使用此函数设置数据报应发送到的地址。该地址可以是用于与对等方通信的单播地址，也可以是用于向一组设备发送数据的广播或组播地址。

另请参阅 QUdpSocket::writeDatagram()、destinationAddress()、destinationPort() 以及setSender()。

void QNetworkDatagram::setHopLimit(int count)

将与该数据报相关的跳数限制设置为count 。跳数限制是指在IP数据包过期并向数据报发送方返回错误之前，允许该数据包被转发经过的节点数量。在IPv4中，该值通常被称为“生存时间”（TTL）。

对于从网络接收的数据报，通常无需调用此函数。

如果是出站数据包，则该值将在发送时设置到 IP 报头中。该值的有效范围为 1 到 255。此函数也接受值 -1，表示应由操作系统选择该值。

另请参阅 hopLimit()。

void QNetworkDatagram::setInterfaceIndex(uint index)

将该数据报关联的接口索引设置为index 。接口索引是一个正数，用于在操作系统中唯一标识网络接口。该数值与QNetworkInterface::index()函数针对该接口返回的值相匹配。

对于从网络接收的数据报，通常无需调用此函数。

如果是出站数据包，则该值即为应用于发送该数据报的接口索引。值为 0 表示操作系统应根据其他因素选择接口。

请注意，对于 IPv6 目的地址，也可以先通过 `QHostAddress::setScopeId()` 设置接口索引，然后使用 `setDestination()`。如果目的地址中设置的范围 ID 与 `index ` 不同，且两者均不为零，则操作系统将通过哪个接口发送数据报是未定义的。

另请参阅 interfaceIndex()。

void QNetworkDatagram::setSender(const QHostAddress &address, quint16 port = 0)

将与该数据报关联的发送方地址设置为地址address 和端口号port 。发送方地址和端口号通常由QUdpSocket 在接收时设置，因此无需对已接收的数据报调用此函数。

对于出站数据报，可使用此函数设置数据报应携带的地址。地址address 通常必须是分配给本机的本地地址之一，可通过QNetworkInterface 获取。若未设置，操作系统将根据目标地址选择最合适的地址。

端口号port 必须是与该套接字关联的端口号（如果存在）。使用值 0 表示应由操作系统选择端口号。

另请参阅 QUdpSocket::writeDatagram()、senderAddress()、senderPort() 以及setDestination()。

[noexcept] void QNetworkDatagram::swap(QNetworkDatagram &other)

将该数据报与other 互换。此操作速度极快，且绝不会失败。

QNetworkDatagram &QNetworkDatagram::operator=(const QNetworkDatagram &other)

复制other 数据报，包括有效载荷和元数据。

要创建一个适合用于回复的数据报，请使用QNetworkDatagram::makeReply();