Класс QNetworkDatagram

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

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

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

Публичные функции

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

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

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()

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

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

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

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

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

QNetworkDatagram::QNetworkDatagram(const QNetworkDatagram &other)

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

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

QNetworkDatagram::QNetworkDatagram(QNetworkDatagram &&other)

Конструктор перемещения-копирования.

QNetworkDatagram::~QNetworkDatagram()

Уничтожает экземпляр QNetworkDatagram.

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.

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

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

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

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

Оператор присваивания перемещения.