Класс 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

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

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