Класс QNetworkDatagram

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

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

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

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

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

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

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

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

Если адрес назначения не был установлен в этом датаграмме, возвращаемый объект будет сообщать 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.