QNetworkDatagram Class

Documentation sur les fonctions membres

QNetworkDatagram::QNetworkDatagram()

Crée un objet `QNetworkDatagram` sans données de charge utile et avec une adresse de destination non définie.

La charge utile peut être modifiée à l'aide de la fonction ` setData()` et l'adresse de destination peut être définie à l'aide de la fonction ` setDestination()`.

Si l'adresse de destination n'est pas définie, la fonction ` QUdpSocket::writeDatagram()` tentera d'envoyer le datagramme à la dernière adresse associée à l'objet, à l'aide de la fonction ` QUdpSocket::connectToHost()`.

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

Crée un objet QNetworkDatagram et définit data comme données utiles, ainsi que destinationAddress et port comme adresses de destination du datagramme.

QNetworkDatagram::QNetworkDatagram(const QNetworkDatagram &other)

Crée une copie du datagramme other, y compris la charge utile et les métadonnées.

Pour créer un datagramme pouvant être envoyé en réponse, utilisez QNetworkDatagram::makeReply();

void QNetworkDatagram::clear()

Efface les données de charge utile et les métadonnées de cet objet « QNetworkDatagram », en les réinitialisant à leurs valeurs par défaut.

QByteArray QNetworkDatagram::data() const

Renvoie la charge utile de ce datagramme. Pour un datagramme reçu du réseau, elle contient la charge utile de ce datagramme. Pour un datagramme sortant, il s'agit du datagramme à envoyer.

Notez que les datagrammes peuvent être transmis sans données ; la fonction ` QByteArray ` renvoyée peut donc être vide.

Voir également setData().

QHostAddress QNetworkDatagram::destinationAddress() const

Renvoie l'adresse de destination associée à ce datagramme. Pour un datagramme reçu du réseau, il s'agit de l'adresse à laquelle le nœud homologue a envoyé le datagramme ; il peut s'agir soit d'une adresse locale de cette machine, soit d'une adresse de multidiffusion ou de diffusion générale. Pour un datagramme sortant, il s'agit de l'adresse à laquelle le datagramme doit être envoyé.

Si aucune adresse de destination n’a été définie sur ce datagramme, l’objet renvoyé indiquera « true » à la fonction ` QHostAddress::isNull()` ().

Voir également senderAddress(), destinationPort() et setDestination().

int QNetworkDatagram::destinationPort() const

Renvoie le numéro de port de la destination associée à ce datagramme. Pour un datagramme reçu du réseau, il s'agit du numéro de port local vers lequel le nœud homologue a envoyé le datagramme. Pour un datagramme sortant, il s'agit du port du nœud homologue vers lequel le datagramme doit être envoyé.

Si aucune adresse de destination n'était associée à ce datagramme, cette fonction renvoie -1.

Voir également destinationAddress(), senderPort() et setDestination().

int QNetworkDatagram::hopLimit() const

Renvoie la limite du nombre de sauts associée à ce datagramme. La limite du nombre de sauts correspond au nombre de nœuds autorisés à transférer le paquet IP avant que celui-ci n'expire et qu'une erreur ne soit renvoyée à l'expéditeur du datagramme. En IPv4, cette valeur est généralement appelée « time to live » (TTL).

Si ce datagramme a été reçu du réseau, il s'agit du nombre de sauts restants du datagramme après réception ; ce nombre a été décrémenté de 1 par chaque nœud ayant acheminé le paquet. Une valeur de -1 indique que le nombre maximal de sauts n'a pas pu être obtenu.

S’il s’agit d’un datagramme sortant, il s’agit de la valeur à définir dans l’en-tête IP lors de l’envoi. Une valeur de -1 indique que le système d’exploitation doit choisir la valeur.

Voir également setHopLimit().

uint QNetworkDatagram::interfaceIndex() const

Renvoie l'index de l'interface à laquelle ce datagramme est associé. L'index d'interface est un nombre positif qui identifie de manière unique l'interface réseau au sein du système d'exploitation. Ce nombre correspond à la valeur renvoyée par la fonction QNetworkInterface::index() pour cette interface.

Si ce datagramme a été reçu du réseau, il s'agit de l'index de l'interface par laquelle le paquet a été reçu. S'il s'agit d'un datagramme sortant, il s'agit de l'index de l'interface par laquelle le datagramme doit être envoyé.

Une valeur égale à 0 indique que l’index de l’interface est inconnu.

Voir également la fonction ` setInterfaceIndex()`.

bool QNetworkDatagram::isNull() const

Renvoie « true » si cet objet « QNetworkDatagram » est nul. Cette fonction est l'opposé de « isValid() ».

bool QNetworkDatagram::isValid() const

Renvoie « true » si cet objet « QNetworkDatagram » est valide. Un objet « QNetworkDatagram » valide contient au moins une adresse d'expéditeur ou de destinataire. Les datagrammes valides peuvent contenir des charges utiles vides.

Crée un nouvel objet ` QNetworkDatagram ` représentant une réponse à ce datagramme entrant et définit les données de charge utile comme suit : ` payload`. Cette fonction constitue un moyen très pratique de renvoyer une réponse à l'expéditeur d'origine.

Exemple :

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

Cette fonction est particulièrement pratique car elle copie automatiquement les paramètres de ce datagramme vers le nouveau datagramme, le cas échéant :

• l'adresse et le port de l'expéditeur de ce datagramme sont copiés respectivement dans l'adresse et le port de destination du nouveau datagramme ;
• l’index d’interface de ce datagramme, le cas échéant, est copié dans l’index d’interface du nouveau datagramme ;
• l'adresse de destination et le port de ce datagramme sont copiés respectivement dans l'adresse d'expéditeur et le port du nouveau datagramme uniquement si l'adresse est une adresse IPv6 globale (non multidiffusion) ;
• la limite du nombre de sauts du nouveau datagramme est réinitialisée à la valeur par défaut (-1) ;

Si l’ QNetworkDatagram est modifiée dans une future version de Qt pour transporter des métadonnées supplémentaires, cette fonction copiera ces métadonnées en conséquence.

L'adresse de destination de ce datagramme n'est pas copiée s'il s'agit d'une adresse IPv4, car il est impossible de distinguer une adresse de diffusion IPv4 d'une adresse IPv4 classique sans effectuer une recherche exhaustive de toutes les adresses attribuées à cette machine. Tenter d'envoyer un datagramme dont l'adresse d'expéditeur est égale à l'adresse de diffusion risque d'échouer. Toutefois, cela ne devrait pas affecter la communication, car les interfaces réseau disposant de plusieurs adresses IPv4 sont rares ; l'adresse choisie par le système d'exploitation sera donc probablement comprise par le correspondant.

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

QHostAddress QNetworkDatagram::senderAddress() const

Renvoie l'adresse de l'expéditeur associée à ce datagramme. Pour un datagramme reçu du réseau, il s'agit de l'adresse du nœud pair qui a envoyé le datagramme. Pour un datagramme sortant, il s'agit de l'adresse locale à utiliser lors de l'envoi.

Si aucune adresse d'expéditeur n'a été définie sur ce datagramme, l'objet renvoyé indiquera « true » à la fonction ` QHostAddress::isNull()`.

Voir également destinationAddress(), senderPort() et setSender().

int QNetworkDatagram::senderPort() const

Renvoie le numéro de port de l'expéditeur associé à ce datagramme. Pour un datagramme reçu du réseau, il s'agit du numéro de port à partir duquel le nœud homologue a envoyé le datagramme. Pour un datagramme sortant, il s'agit du port local à partir duquel le datagramme doit être envoyé.

Si aucune adresse d'expéditeur n'était associée à ce datagramme, cette fonction renvoie -1.

Voir également senderAddress(), destinationPort() et setSender().

void QNetworkDatagram::setData(const QByteArray &data)

Définit la charge utile de ce datagramme sur data. Il n'est généralement pas nécessaire d'appeler cette fonction sur les datagrammes reçus. Pour les datagrammes sortants, cette fonction définit les données à envoyer sur le réseau.

Les datagrammes pouvant être vides, un QByteArray vide est une valeur valide pour data.

Voir également ` data()`.

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

Définit l'adresse de destination associée à ce datagramme comme étant l'adresse address et le numéro de port port. L'adresse de destination et le numéro de port sont généralement définis par la fonction QUdpSocket lors de la réception ; il n'est donc pas nécessaire d'appeler cette fonction sur un datagramme reçu.

Pour les datagrammes sortants, cette fonction peut être utilisée pour définir l’adresse à laquelle le datagramme doit être envoyé. Il peut s’agir de l’adresse unicast utilisée pour communiquer avec le pair, ou d’une adresse de diffusion ou de multidiffusion permettant d’envoyer le datagramme à un groupe de périphériques.

Voir également QUdpSocket::writeDatagram(), destinationAddress(), destinationPort() et setSender().

void QNetworkDatagram::setHopLimit(int count)

Définit la limite du nombre de sauts associée à ce datagramme à count. La limite du nombre de sauts correspond au nombre de nœuds autorisés à transférer le paquet IP avant que celui-ci n'expire et qu'une erreur ne soit renvoyée à l'expéditeur du datagramme. En IPv4, cette valeur est généralement appelée « time to live » (TTL).

Il n’est généralement pas nécessaire d’appeler cette fonction sur les datagrammes reçus du réseau.

S'il s'agit d'un paquet sortant, c'est la valeur à définir dans l'en-tête IP lors de l'envoi. La plage de valeurs valides est comprise entre 1 et 255. Cette fonction accepte également la valeur -1 pour indiquer que le système d'exploitation doit choisir la valeur.

Voir également hopLimit().

void QNetworkDatagram::setInterfaceIndex(uint index)

Définit l'index d'interface associé à ce datagramme sur index. L'index d'interface est un nombre positif qui identifie de manière unique l'interface réseau au sein du système d'exploitation. Ce nombre correspond à la valeur renvoyée par la fonction QNetworkInterface::index() pour cette interface.

Il n’est généralement pas nécessaire d’appeler cette fonction sur les datagrammes reçus du réseau.

S'il s'agit d'un paquet sortant, il s'agit de l'index de l'interface par laquelle le datagramme doit être envoyé. Une valeur de 0 indique que le système d'exploitation doit choisir l'interface en fonction d'autres facteurs.

Notez que l’index d’interface peut également être défini à l’aide de ` QHostAddress::setScopeId()` pour les adresses de destination IPv6, puis à l’aide de ` setDestination()`. Si l’ID de portée défini dans l’adresse de destination et celui de ` index ` sont différents et qu’aucun des deux n’est égal à zéro, l’interface sur laquelle le système d’exploitation enverra le datagramme n’est pas définie.

Voir également interfaceIndex().

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

Définit l'adresse de l'expéditeur associée à ce datagramme comme étant l'adresse address et le numéro de port port. L'adresse de l'expéditeur et les numéros de port sont généralement définis par la fonction QUdpSocket lors de la réception ; il n'est donc pas nécessaire d'appeler cette fonction sur un datagramme reçu.

Pour les datagrammes sortants, cette fonction peut être utilisée pour définir l’adresse que le datagramme doit transporter. L’adresse address doit généralement être l’une des adresses locales attribuées à cette machine, qui peuvent être obtenues à l’aide de QNetworkInterface. Si elle n’est pas définie, le système d’exploitation choisira l’adresse la plus appropriée en fonction de la destination en question.

Le numéro de port port doit correspondre au numéro de port associé au socket, s’il en existe un. La valeur 0 peut être utilisée pour indiquer que le système d’exploitation doit choisir le numéro de port.

Voir également QUdpSocket::writeDatagram(), senderAddress(), senderPort() et setDestination().

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

Permet d'échanger ce datagramme contre celui de other. Cette opération est très rapide et ne rate jamais.

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

Copie le datagramme other, y compris la charge utile et les métadonnées.

Pour créer un datagramme adapté à l'envoi d'une réponse, utilisez QNetworkDatagram::makeReply();