Класс QNetworkDatagram

Класс QNetworkDatagram предоставляет данные и метаданные UDP-датаграммы. Подробнее...

Этот класс был введён в Qt 5.8.

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Общедоступные функции

Подробное описание

Класс QNetworkDatagram может использоваться с классом QUdpSocket для представления полной информации, содержащейся в UDP-датаграмме (протокол пользователя датаграмм). QNetworkDatagram инкапсулирует следующую информацию о датаграмме:

• данные полезной нагрузки;
• адрес отправителя и номер порта;
• адрес получателя и номер порта;
• оставшийся предел количества пересылок (в IPv4 это поле обычно называется «время жизни» — TTL);
• индекс сетевого интерфейса, на котором была получена датаграмма или на котором она должна быть отправлена.

QUdpSocket будет стараться максимально соответствовать стандартному поведению на всех операционных системах, но не все вышеперечисленные метаданные могут быть получены на всех операционных системах. Метаданные, которые не могут быть установлены в датаграмме при отправке с помощью QUdpSocket::writeDatagram(), будут молча отброшены.

При приёме свойства senderAddress() и senderPort() содержат адрес и порт узла, отправившего датаграмму, а свойства destinationAddress() и destinationPort() содержат целевой адрес, который был в датаграмме. Обычно это адрес, локальный для текущей машины, но это также может быть адрес IPv4-вещания (такой как «255.255.255.255») или адрес IPv4 или IPv6-многоадресной рассылки. Приложениям может быть полезно определить, была ли датаграмма отправлена конкретно на эту машину с помощью одноадресной рассылки или она была отправлена нескольким получателям.

При отправке senderAddress() и senderPort() должны содержать локальный адрес, который будет использоваться при отправке. Адрес отправителя должен быть адресом, назначенным этой машине, который можно получить с помощью QNetworkInterface, а номер порта должен быть номером порта, к которому привязан сокет. Любое из этих полей можно оставить без значения, и операционная система заполнит их значениями по умолчанию. Поля destinationAddress() и destinationPort() могут быть установлены на целевой адрес, отличающийся от того, который в настоящее время связан с UDP-сокетом.

Обычно при отправке датаграммы в ответ на ранее полученную датаграмму устанавливается destinationAddress() равным senderAddress() входящей датаграммы и аналогично для номеров портов. Для облегчения этой распространённой задачи класс QNetworkDatagram предоставляет функцию makeReply().

Функция hopCount() содержит, для полученной датаграммы, оставшийся предел количества пересылок для пакета. При отправке она содержит предел количества пересылок, который должен быть установлен. Большинство протоколов оставляют это значение по умолчанию и позволяют операционной системе принять решение о наилучшем значении, которое следует использовать. Многоадресная рассылка по IPv4 часто использует это поле для указания области многоадресной группы (локальной, локальной для организации или глобальной).

Функция interfaceIndex() содержит индекс интерфейса операционной системы, на котором был получен пакет. Это значение такое же, которое можно установить в свойстве QHostAddress::scopeId(), и оно соответствует свойству QNetworkInterface::index(). При отправке пакетов на глобальные адреса нет необходимости устанавливать индекс интерфейса, так как операционная система выберет правильный с использованием таблицы маршрутизации системы. Это свойство важно при отправке датаграмм на локальные адреса, как одноадресные, так и многоадресные.

Поддержка функций

Некоторые функции класса QNetworkDatagram не поддерживаются во всех операционных системах. Только адрес и порты удалённого узла (отправителя в полученных пакетах и получателя для исходящих пакетов) поддерживаются во всех системах. В большинстве операционных систем другие функции поддерживаются только для IPv6. Программное обеспечение должно проверять во время выполнения, можно ли определить остальную информацию для адресов IPv4.

Текущая поддержка функций:

См. также QUdpSocket и QNetworkInterface.

Документация по функциям-членам

Создаёт новую QNetworkDatagram, представляющую ответ на эту входящую датаграмму, и устанавливает данные полезной нагрузки в payload. Эта функция является очень удобным способом ответа на датаграмму обратно исходному отправителю.

Пример:

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

Эта функция особенно удобна, поскольку она автоматически копирует параметры из этого дейтаграммы в новую дейтаграмму, как это необходимо:

• адрес и порт отправителя этой дейтаграммы копируются в адрес и порт назначения новой дейтаграммы;
• индекс интерфейса этой дейтаграммы, если есть, копируется в индекс интерфейса новой дейтаграммы;
• адрес и порт назначения этой дейтаграммы копируются в адрес и порт отправителя новой дейтаграммы только в том случае, если адрес является глобальным IPv6-адресом (не многоадресным);
• предел количества переходов в новой дейтаграмме сбрасывается до значения по умолчанию (-1);

Если QNetworkDatagram будет модифицирован в будущей версии Qt, чтобы содержать дополнительные метаданные, эта функция будет копировать эти метаданные соответствующим образом.

Адрес назначения этой дейтаграммы не копируется, если это IPv4-адрес, поскольку невозможно отличить адрес IPv4-вещания от обычного IPv4-адреса без исчерпывающего поиска всех адресов, назначенных этому компьютеру. Попытка отправить дейтаграмму с адресом отправителя, равным адресу вещания, скорее всего, завершится неудачей. Однако это не должно повлиять на общение, так как сетевые интерфейсы с несколькими IPv4-адресами встречаются нечасто, поэтому адрес, который выберет операционная система, скорее всего, будет понятен партнеру.

Примечание: Эта функция имеет перегрузки с квалификаторами rvalue- и lvalue-ссылок, поэтому рекомендуется убедиться, что этот объект является rvalue, если это возможно, перед вызовом makeReply, чтобы эффективнее использовать семантику перемещения. Для этого в примере выше использовалось бы:

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

QNetworkDatagram::QNetworkDatagram(const QNetworkDatagram &other)

Создаёт копию дейтаграммы other, включая полезные данные и метаданные.

Для создания дейтаграммы, подходящей для отправки в ответ, используйте QNetworkDatagram::makeReply();

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

Создаёт объект QNetworkDatagram и устанавливает data в качестве полезных данных, а также destinationAddress и port в качестве адреса назначения дейтаграммы.

QNetworkDatagram::QNetworkDatagram()

Создаёт объект QNetworkDatagram без полезных данных и неопределённым адресом назначения.

Полезные данные можно изменить с помощью setData(), а адрес назначения можно установить с помощью setDestination().

Если адрес назначения оставлен неопределённым, QUdpSocket::writeDatagram() попытается отправить дейтаграмму по адресу, последний связанному с, с использованием QUdpSocket::connectToHost().

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

Копирует дейтаграмму other, включая полезные данные и метаданные.

Для создания дейтаграммы, подходящей для отправки в ответ, используйте QNetworkDatagram::makeReply();

void QNetworkDatagram::clear()

Очищает полезные данные и метаданные в этом объекте QNetworkDatagram, сбрасывая их до значений по умолчанию.

QByteArray QNetworkDatagram::data() const

Возвращает полезные данные этой дейтаграммы. Для дейтаграммы, полученной из сети, она содержит полезные данные дейтаграммы. Для исходящей дейтаграммы, это дейтаграмма, которая должна быть отправлена.

Обратите внимание, что дейтаграммы могут передаваться без данных, поэтому возвращаемый QByteArray может быть пустым.

См. также setData().

QHostAddress QNetworkDatagram::destinationAddress() const

Возвращает адрес назначения, связанный с этой дейтаграммой. Для дейтаграммы, полученной из сети, это адрес узла-партнёра, который отправил дейтаграмму, которая может быть локальным адресом этого компьютера или многоадресным или широковещательным адресом. Для исходящих дейтаграмм, это адрес, куда дейтаграмма должна быть отправлена.

Если адрес назначения не был установлен в этой дейтаграмме, возвращаемый объект сообщит о true для QHostAddress::isNull().

См. также senderAddress(), destinationPort() и setDestination().

int QNetworkDatagram::destinationPort() const

Возвращает номер порта назначения, связанный с этой дейтаграммой. Для дейтаграммы, полученной из сети, это номер локального порта, которому узел-партнёр отправил дейтаграмму. Для исходящей дейтаграммы, это порт партнёра, куда дейтаграмма должна быть отправлена.

Если адрес назначения не был связан с этой дейтаграммой, эта функция возвращает -1.

См. также destinationAddress(), senderPort() и setDestination().

int QNetworkDatagram::hopLimit() const

Возвращает предел количества переходов, связанный с этой дейтаграммой. Предел количества переходов — это количество узлов, которым разрешено пересылать IP-пакет, прежде чем он истечёт, и отправителю дейтаграммы будет отправлено сообщение об ошибке.

Если эта дейтаграмма была получена из сети, это оставшееся количество переходов дейтаграммы после получения, и каждый узел, который пересылал пакет, уменьшил его на 1. Значение -1 указывает на то, что количество переходов не может быть получено.

Если это исходящая дейтаграмма, это значение, которое должно быть установлено в заголовке IP при отправке. Значение -1 указывает, что операционная система должна выбрать значение.

См. также setHopLimit().

uint QNetworkDatagram::interfaceIndex() const

Возвращает индекс интерфейса, с которым связана эта дейтаграмма. Индекс интерфейса — это положительное число, которое однозначно идентифицирует сетевой интерфейс в операционной системе. Это число совпадает со значением, возвращаемым QNetworkInterface::index() для интерфейса.

Если эта дейтаграмма была получена из сети, это индекс интерфейса, с которого был получен пакет. Если это исходящая дейтаграмма, это индекс интерфейса, на котором дейтаграмма должна быть отправлена.

Значение 0 указывает, что индекс интерфейса неизвестен.

См. также setInterfaceIndex().

bool QNetworkDatagram::isNull() const

Возвращает true, если этот объект QNetworkDatagram равен null. Эта функция является противоположностью isValid().

bool QNetworkDatagram::isValid() const

Возвращает true, если этот объект QNetworkDatagram действителен. Действительный объект QNetworkDatagram содержит по крайней мере один адрес отправителя или получателя. Действительные дейтаграммы могут содержать пустые полезные данные.

QHostAddress QNetworkDatagram::senderAddress() const

Возвращает адрес отправителя, связанный с этой дейтаграммой. Для дейтаграммы, полученной из сети, это адрес узла-партнёра, который отправил дейтаграмму. Для исходящих дейтаграмм, это локальный адрес, который будет использован при отправке.

Если адрес отправителя не был установлен в этой дейтаграмме, возвращаемый объект сообщит о true для QHostAddress::isNull().

См. также 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 указывает, что операционная система должна выбрать интерфейс на основе других факторов.

Обратите внимание, что индекс интерфейса также можно установить с помощью QHostAddress::setScopeId() для IPv6 адресов назначения, а затем с помощью setDestination(). Если идентификатор области, установленный в адресе назначения и index, отличаются и ни один из них не равен нулю, то неопределённо, по какому интерфейсу операционная система отправит дейтаграмму.

См. также interfaceIndex() и setInterfaceIndex().

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

Устанавливает адрес отправителя, связанный с этой дейтаграммой, в адрес address и номер порта port. Адрес отправителя и номера портов обычно устанавливаются QUdpSocket при приёме, поэтому нет необходимости вызывать эту функцию для полученной дейтаграммы.

Для исходящих дейтаграмм эту функцию можно использовать для установки адреса, который должна содержать дейтаграмма. Адрес address обычно должен быть одним из локальных адресов, назначенных этому компьютеру, которые можно получить с помощью QNetworkInterface. Если адрес не задан, операционная система выберет наиболее подходящий адрес, учитывая целевой адрес.

Номер порта port должен быть номером порта, связанным с сокетом, если он есть. Значение 0 можно использовать, чтобы указать, что операционная система должна выбрать номер порта.

См. также QUdpSocket::writeDatagram(), senderAddress(), senderPort() и setDestination().

void QNetworkDatagram::swap(QNetworkDatagram &other)

Обменивается этой экземпляром с other.