Класс QNetworkDatagram

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