Класс QNetworkDatagram

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

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

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

Открытые функции

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

Класс QNetworkDatagram может быть использован с классом QUdpSocket для представления всей информации, содержащейся в дейтаграмме UDP (User Datagram Protocol). 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 встречаются нечасто, поэтому адрес, который выберет операционная система, вероятно, будет понятен получателю.

    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, прежде чем он истечёт, и отправителю датаграммы будет отправлено сообщение об ошибке.

В IPv4 это значение обычно известно как «время жизни» (TTL).

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

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

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

uint QNetworkDatagram::interfaceIndex() const

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

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

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

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

bool QNetworkDatagram::isNull() const

Возвращает true, если этот объект QNetworkDatagram является нулевым. Эта функция противоположна 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 при приёме, поэтому нет необходимости вызывать эту функцию для полученной датаграммы.

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

См. также 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.