Класс QNetworkDatagram

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

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

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

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

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

Класс 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 встречаются нечасто, поэтому адрес, который выберет операционная система, скорее всего, будет понятен для участника.

Примечание: Эта функция имеет перегрузки с квалификаторами ссылки с 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)

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