QNetworkDatagram Class

Detailed Description

QNetworkDatagram can be used with the QUdpSocket class to represent the full information contained in a UDP (User Datagram Protocol) datagram. QNetworkDatagram encapsulates the following information of a datagram:

• the payload data;
• the sender address and port number;
• the destination address and port number;
• the remaining hop count limit (on IPv4, this field is usually called "time to live" - TTL);
• the network interface index the datagram was received on or to be sent on.

QUdpSocket will try to match a common behavior as much as possible on all operating systems, but not all of the metadata above can be obtained in some operating systems. Metadata that cannot be set on the datagram when sending with QUdpSocket::writeDatagram() will be silently discarded.

Upon reception, the senderAddress() and senderPort() properties contain the address and port of the peer that sent the datagram, while destinationAddress() and destinationPort() contain the target that was contained in the datagram. That is usually an address local to the current machine, but it can also be an IPv4 broadcast address (such as "255.255.255.255") or an IPv4 or IPv6 multicast address. Applications may find it useful to determine if the datagram was sent specifically to this machine via unicast addressing or whether it was sent to multiple destinations.

When sending, the senderAddress() and senderPort() should contain the local address to be used when sending. The sender address must be an address that is assigned to this machine, which can be obtained using QNetworkInterface, and the port number must be the port number that the socket is bound to. Either field can be left unset and will be filled in by the operating system with default values. The destinationAddress() and destinationPort() fields may be set to a target address different from the one the UDP socket is currently associated with.

Usually, when sending a datagram in reply to a datagram previously received, one will set the destinationAddress() to be the senderAddress() of the incoming datagram and similarly for the port numbers. To facilitate this common process, QNetworkDatagram provides the function makeReply().

The hopCount() function contains, for a received datagram, the remaining hop count limit for the packet. When sending, it contains the hop count limit to be set. Most protocols will leave this value set to the default and let the operating system decide on the best value to be used. Multicasting over IPv4 often uses this field to indicate the scope of the multicast group (link-local, local to an organization or global).

The interfaceIndex() function contains the index of the operating system's interface that received the packet. This value is the same one that can be set on a QHostAddress::scopeId() property and matches the QNetworkInterface::index() property. When sending packets to global addresses, it is not necessary to set the interface index as the operating system will choose the correct one using the system routing table. This property is important when sending datagrams to link-local destinations, whether unicast or multicast.

Feature support

Some features of QNetworkDatagram are not supported in all operating systems. Only the address and ports of the remote host (sender in received packets and destination for outgoing packets) are supported in all systems. On most operating systems, the other features are supported only for IPv6. Software should check at runtime whether the rest could be determined for IPv4 addresses.

The current feature support is as follows: