Класс 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::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, прежде чем он истечёт и отправителю дейтаграммы будет отправлено сообщение об ошибке. В IPv4 это значение обычно известно как «время жизни» (TTL).

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

QNetworkDatagram QNetworkDatagram::makeReply(const QByteArray &data) const

Создаёт новый QNetworkDatagram, представляющий ответ на эту входящую дейтаграмму, и устанавливает данные загрузки в data. Эта функция является очень удобным способом ответа дейтаграмме обратно исходному отправителю.

Пример:

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

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)

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

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

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

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

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