En esta página

QNetworkDatagram Class

La clase QNetworkDatagram proporciona los datos y los metadatos de un datagrama UDP. Más información...

Encabezado: #include <QNetworkDatagram>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QNetworkDatagram()
QNetworkDatagram(const QByteArray &data, const QHostAddress &destinationAddress = QHostAddress(), quint16 port = 0)
QNetworkDatagram(const QNetworkDatagram &other)
void clear()
QByteArray data() const
QHostAddress destinationAddress() const
int destinationPort() const
int hopLimit() const
uint interfaceIndex() const
bool isNull() const
bool isValid() const
QNetworkDatagram makeReply(const QByteArray &payload) &&
QNetworkDatagram makeReply(const QByteArray &payload) const &
QHostAddress senderAddress() const
int senderPort() const
void setData(const QByteArray &data)
void setDestination(const QHostAddress &address, quint16 port)
void setHopLimit(int count)
void setInterfaceIndex(uint index)
void setSender(const QHostAddress &address, quint16 port = 0)
void swap(QNetworkDatagram &other)
QNetworkDatagram &operator=(const QNetworkDatagram &other)

Descripción detallada

QNetworkDatagram se puede utilizar junto con la clase ` QUdpSocket ` para representar toda la información contenida en un datagrama UDP (Protocolo de datagramas de usuario). QNetworkDatagram encapsula la siguiente información de un datagrama:

  • los datos de carga útil;
  • la dirección del remitente y el número de puerto;
  • la dirección de destino y el número de puerto;
  • el límite de saltos restantes (en IPv4, este campo suele denominarse «tiempo de vida» —TTL—);
  • el índice de la interfaz de red en la que se recibió el datagrama o a través de la cual se va a enviar.

QUdpSocket Se intentará mantener un comportamiento lo más uniforme posible en todos los sistemas operativos, pero en algunos de ellos no se pueden obtener todos los metadatos mencionados anteriormente. Los metadatos que no se puedan establecer en el datagrama al enviarlo con QUdpSocket::writeDatagram() se descartarán sin aviso.

Tras la recepción, las propiedades ` senderAddress()` y ` senderPort()` contienen la dirección y el puerto del interlocutor que envió el datagrama, mientras que ` destinationAddress()` y ` destinationPort()` contienen el destino que figuraba en el datagrama. Normalmente se trata de una dirección local de la máquina actual, pero también puede ser una dirección de difusión IPv4 (como «255.255.255.255») o una dirección de multidifusión IPv4 o IPv6. A las aplicaciones les puede resultar útil determinar si el datagrama se envió específicamente a esta máquina mediante direccionamiento de unidifusión o si se envió a varios destinos.

Al enviar, los campos ` senderAddress()` y ` senderPort()` deben contener la dirección local que se utilizará en el envío. La dirección del remitente debe ser una dirección asignada a esta máquina, que puede obtenerse mediante ` QNetworkInterface`, y el número de puerto debe ser el número de puerto al que está vinculado el socket. Cualquiera de los dos campos puede dejarse sin definir y el sistema operativo lo completará con valores por defecto. Los campos destinationAddress() y destinationPort() pueden establecerse en una dirección de destino diferente de aquella a la que está asociado actualmente el socket UDP.

Normalmente, al enviar un datagrama en respuesta a uno recibido previamente, se establecerá ` destinationAddress()` como ` senderAddress()` del datagrama entrante, y lo mismo se hará con los números de puerto. Para facilitar este proceso habitual, `QNetworkDatagram` proporciona la función ` makeReply()`.

La función hopCount() contiene, para un datagrama recibido, el límite de saltos restante para el paquete. Al enviar, contiene el límite de saltos que se va a establecer. La mayoría de los protocolos dejan este valor en su valor predeterminado y permiten que el sistema operativo decida cuál es el mejor valor a utilizar. La multidifusión sobre IPv4 suele utilizar este campo para indicar el alcance del grupo de multidifusión (local de enlace, local de una organización o global).

La función ` interfaceIndex()` contiene el índice de la interfaz del sistema operativo que recibió el paquete. Este valor es el mismo que se puede establecer en la propiedad ` QHostAddress::scopeId()` y coincide con la propiedad ` QNetworkInterface::index()`. Al enviar paquetes a direcciones globales, no es necesario establecer el índice de la interfaz, ya que el sistema operativo elegirá la correcta utilizando la tabla de enrutamiento del sistema. Esta propiedad es importante al enviar datagramas a destinos locales de enlace, ya sean de unidifusión o de multidifusión.

Compatibilidad con funciones

Algunas características de `QNetworkDatagram` no son compatibles con todos los sistemas operativos. Solo la dirección y los puertos del host remoto (remitente en los paquetes recibidos y destino de los paquetes salientes) son compatibles en todos los sistemas. En la mayoría de los sistemas operativos, el resto de características solo son compatibles con IPv6. El software debe comprobar en tiempo de ejecución si el resto de datos se pueden determinar para direcciones IPv4.

La compatibilidad actual con las funciones es la siguiente:

Sistema operativoDirección localRecuento de saltosÍndice de interfaz
FreeBSDCompatibleCompatibleSolo para IPv6
LinuxCompatibleCompatibleCompatible
OS XCompatibleCompatibleSolo para IPv6
Otros sistemas Unix compatibles con RFC 3542Solo para IPv6Solo para IPv6Solo para IPv6
Windows (escritorio)CompatibleCompatibleCompatible
Windows RTNo compatibleNo compatibleNo compatible

Véase también QUdpSocket y QNetworkInterface.

Documentación de funciones de miembro

QNetworkDatagram::QNetworkDatagram()

Crea un objeto QNetworkDatagram sin datos de carga útil y con una dirección de destino indefinida.

La carga útil se puede modificar mediante ` setData()` y la dirección de destino se puede establecer con ` setDestination()`.

Si la dirección de destino no se define, QUdpSocket::writeDatagram() intentará enviar el datagrama a la última dirección asociada mediante QUdpSocket::connectToHost().

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

Crea un objeto QNetworkDatagram y establece data como datos de carga útil, junto con destinationAddress y port como direcciones de destino del datagrama.

QNetworkDatagram::QNetworkDatagram(const QNetworkDatagram &other)

Crea una copia del datagrama other, incluyendo la carga útil y los metadatos.

Para crear un datagrama adecuado para enviar una respuesta, utiliza QNetworkDatagram::makeReply();

void QNetworkDatagram::clear()

Borra los datos de carga útil y los metadatos de este objeto « QNetworkDatagram », restableciéndolos a sus valores predeterminados.

QByteArray QNetworkDatagram::data() const

Devuelve la carga útil de este datagrama. En el caso de un datagrama recibido de la red, contiene la carga útil del datagrama. En el caso de un datagrama saliente, se trata del datagrama que se va a enviar.

Ten en cuenta que los datagramas pueden transmitirse sin datos, por lo que el objeto ` QByteArray ` devuelto puede estar vacío.

Véase también setData().

QHostAddress QNetworkDatagram::destinationAddress() const

Devuelve la dirección de destino asociada a este datagrama. En el caso de un datagrama recibido de la red, se trata de la dirección a la que el nodo homólogo envió el datagrama, que puede ser una dirección local de esta máquina o una dirección de multidifusión o de difusión. En el caso de los datagramas salientes, se trata de la dirección a la que debe enviarse el datagrama.

Si no se ha establecido ninguna dirección de destino en este datagrama, el objeto devuelto devolverá «true» a QHostAddress::isNull().

Véanse también senderAddress(), destinationPort() y setDestination().

int QNetworkDatagram::destinationPort() const

Devuelve el número de puerto del destino asociado a este datagrama. En el caso de un datagrama recibido de la red, se trata del número de puerto local al que el nodo homólogo envió el datagrama. En el caso de un datagrama saliente, se trata del puerto del nodo homólogo al que debe enviarse el datagrama.

Si no se ha asociado ninguna dirección de destino a este datagrama, esta función devuelve -1.

Véanse también destinationAddress(), senderPort() y setDestination().

int QNetworkDatagram::hopLimit() const

Devuelve el límite de saltos asociado a este datagrama. El límite de saltos es el número de nodos que pueden reenviar el paquete IP antes de que caduque y se envíe un error al remitente del datagrama. En IPv4, este valor se conoce habitualmente como «tiempo de vida» (TTL).

Si este datagrama se ha recibido de la red, este es el recuento de saltos restante del datagrama tras la recepción, y se ha reducido en 1 por cada nodo que ha reenviado el paquete. Un valor de -1 indica que no se ha podido obtener el límite de saltos.

Si se trata de un datagrama saliente, este es el valor que debe establecerse en la cabecera IP al enviarlo. Un valor de -1 indica que el sistema operativo debe elegir el valor.

Véase también setHopLimit().

uint QNetworkDatagram::interfaceIndex() const

Devuelve el índice de la interfaz a la que está asociado este datagrama. El índice de la interfaz es un número positivo que identifica de forma única la interfaz de red en el sistema operativo. Este número coincide con el valor devuelto por la función ` QNetworkInterface::index()` para dicha interfaz.

Si este datagrama se ha recibido de la red, este es el índice de la interfaz desde la que se recibió el paquete. Si se trata de un datagrama saliente, este es el índice de la interfaz a través de la cual debe enviarse el datagrama.

Un valor de 0 indica que se desconoce el índice de la interfaz.

Véase también setInterfaceIndex().

bool QNetworkDatagram::isNull() const

Devuelve «true» si este objeto ` QNetworkDatagram ` es nulo. Esta función es la inversa de ` isValid()`.

bool QNetworkDatagram::isValid() const

Devuelve «true» si este objeto ` QNetworkDatagram ` es válido. Un objeto ` QNetworkDatagram ` válido contiene al menos una dirección de remitente o de destinatario. Los datagramas válidos pueden contener cargas útiles vacías.

QNetworkDatagram QNetworkDatagram::makeReply(const QByteArray &payload) &&

QNetworkDatagram QNetworkDatagram::makeReply(const QByteArray &payload) const &

Crea un nuevo objeto ` QNetworkDatagram ` que representa una respuesta a este datagrama entrante y establece los datos de la carga útil en ` payload`. Esta función es una forma muy práctica de responder a un datagrama reenviándolo al remitente original.

Ejemplo:

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

Esta función resulta especialmente práctica, ya que copia automáticamente los parámetros de este datagrama al nuevo datagrama según corresponda:

  • la dirección y el puerto del remitente de este datagrama se copian en la dirección y el puerto de destino del nuevo datagrama;
  • el índice de interfaz de este datagrama, si lo hay, se copia en el índice de interfaz del nuevo datagrama;
  • la dirección de destino y el puerto de este datagrama se copian a la dirección de remitente y al puerto del nuevo datagrama solo si la dirección es una dirección IPv6 global (no de multidifusión);
  • el límite del recuento de saltos del nuevo datagrama se restablece al valor predeterminado (-1);

Si en una futura versión de Qt se modifica ` QNetworkDatagram ` para que transporte más metadatos, esta función copiará dichos metadatos según corresponda.

La dirección de destino de este datagrama no se copia si se trata de una dirección IPv4, ya que no es posible distinguir una dirección de difusión IPv4 de una dirección IPv4 normal sin realizar una búsqueda exhaustiva de todas las direcciones asignadas a este equipo. Es probable que falle cualquier intento de enviar un datagrama con la dirección del remitente igual a la dirección de difusión. Sin embargo, esto no debería afectar a la comunicación, ya que las interfaces de red con varias direcciones IPv4 son poco comunes, por lo que es probable que la dirección que seleccione el sistema operativo sea una que el interlocutor pueda interpretar.

Nota: Esta función incluye sobrecargas tanto para el calificador de referencia de valor de derecha como para el de valor de izquierda, por lo que es recomendable asegurarse de que este objeto sea de valor de derecha, si es posible, antes de llamar a ` makeReply`, con el fin de aprovechar mejor la semántica de movimiento. Para lograrlo, en el ejemplo anterior se utilizaría:

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

QHostAddress QNetworkDatagram::senderAddress() const

Devuelve la dirección del remitente asociada a este datagrama. En el caso de un datagrama recibido de la red, se trata de la dirección del nodo homólogo que envió el datagrama. En el caso de los datagramas salientes, se trata de la dirección local que se utilizará al enviarlos.

Si no se ha establecido ninguna dirección de remitente en este datagrama, el objeto devuelto devolverá «true» a QHostAddress::isNull().

Véase también destinationAddress(), senderPort() y setSender().

int QNetworkDatagram::senderPort() const

Devuelve el número de puerto del remitente asociado a este datagrama. En el caso de un datagrama recibido de la red, se trata del número de puerto desde el que el nodo homólogo envió el datagrama. En el caso de un datagrama saliente, se trata del puerto local desde el que debe enviarse el datagrama.

Si no se ha asociado ninguna dirección de remitente a este datagrama, esta función devuelve -1.

Véase también senderAddress(), destinationPort() y setSender().

void QNetworkDatagram::setData(const QByteArray &data)

Establece la carga útil de datos de este datagrama en data. Por lo general, no es necesario llamar a esta función en los datagramas recibidos. En el caso de los datagramas salientes, esta función establece los datos que se van a enviar a la red.

Dado que los datagramas pueden estar vacíos, un QByteArray vacío es un valor válido para data.

Véase también ` data()`.

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

Establece la dirección de destino asociada a este datagrama como la dirección address y el número de puerto port. La dirección de destino y los números de puerto suelen ser establecidos por QUdpSocket en el momento de la recepción, por lo que no es necesario llamar a esta función en un datagrama recibido.

En el caso de los datagramas salientes, esta función se puede utilizar para establecer la dirección a la que se debe enviar el datagrama. Puede ser la dirección de unidifusión utilizada para comunicarse con el interlocutor o una dirección de difusión o multidifusión para enviarlo a un grupo de dispositivos.

Véanse también QUdpSocket::writeDatagram(), destinationAddress(), destinationPort() y setSender().

void QNetworkDatagram::setHopLimit(int count)

Establece el límite de recuento de saltos asociado a este datagrama en count. El límite de recuento de saltos es el número de nodos que pueden reenviar el paquete IP antes de que caduque y se envíe un error al remitente del datagrama. En IPv4, este valor se conoce habitualmente como «tiempo de vida» (TTL).

Normalmente no es necesario llamar a esta función en los datagramas recibidos de la red.

Si se trata de un paquete saliente, este es el valor que debe establecerse en la cabecera IP al enviarlo. El rango válido para el valor es de 1 a 255. Esta función también acepta el valor -1 para indicar que el sistema operativo debe elegir el valor.

Véase también hopLimit().

void QNetworkDatagram::setInterfaceIndex(uint index)

Establece el índice de interfaz al que está asociado este datagrama en « index ». El índice de interfaz es un número positivo que identifica de forma única la interfaz de red en el sistema operativo. Este número coincide con el valor devuelto por la función « QNetworkInterface::index()» para dicha interfaz.

Normalmente no es necesario llamar a esta función en los datagramas recibidos de la red.

Si se trata de un paquete saliente, este es el índice de la interfaz por la que debe enviarse el datagrama. Un valor de 0 indica que el sistema operativo debe elegir la interfaz en función de otros factores.

Tenga en cuenta que el índice de la interfaz también se puede establecer con QHostAddress::setScopeId() para direcciones de destino IPv6 y, a continuación, con setDestination(). Si el identificador de ámbito establecido en la dirección de destino y el de index son diferentes y ninguno de ellos es cero, no está definido a través de qué interfaz enviará el sistema operativo el datagrama.

Véase también interfaceIndex().

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

Establece la dirección del remitente asociada a este datagrama en la dirección address y el número de puerto port. La dirección del remitente y los números de puerto suelen ser establecidos por QUdpSocket en el momento de la recepción, por lo que no es necesario llamar a esta función en un datagrama recibido.

En el caso de los datagramas salientes, esta función puede utilizarse para establecer la dirección que debe llevar el datagrama. La dirección address suele tener que ser una de las direcciones locales asignadas a esta máquina, que puede obtenerse mediante QNetworkInterface. Si no se establece, el sistema operativo elegirá la dirección más adecuada en función del destino en cuestión.

El número de puerto port debe ser el número de puerto asociado al socket, si lo hay. Se puede utilizar el valor 0 para indicar que el sistema operativo debe elegir el número de puerto.

Véanse también QUdpSocket::writeDatagram(), senderAddress(), senderPort() y setDestination().

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

Intercambia este datagrama con other. Esta operación es muy rápida y nunca falla.

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

Copia el datagrama other, incluyendo la carga útil y los metadatos.

Para crear un datagrama adecuado para enviar en una respuesta, utiliza QNetworkDatagram::makeReply();

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.