Класс QUdpSocket

Класс QUdpSocket предоставляет сокет UDP. Подробнее...

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

Примечание: Все функции в этом классе являются перевходящими.

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

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

UDP (протокол пользовательских датаграмм) — лёгкий, ненадежный, ориентированный на датаграммы, бессоединительный протокол. Он может использоваться, когда надёжность не важна. QUdpSocket — подкласс QAbstractSocket, который позволяет отправлять и получать UDP-датаграммы.

Наиболее распространённый способ использования этого класса — привязка к адресу и порту с помощью bind(), а затем вызов writeDatagram() и readDatagram() / receiveDatagram() для передачи данных. Если вы хотите использовать стандартные функции QIODevice read(), readLine(), write() и т. д., вы должны сначала подключить сокет напрямую к узлу, вызвав connectToHost().

Сокет излучает сигнал bytesWritten() каждый раз, когда датаграмма записывается в сеть. Если вы просто хотите отправлять датаграммы, вам не нужно вызывать bind().

Сигнал readyRead() излучается всякий раз, когда прибывают датаграммы. В этом случае hasPendingDatagrams() возвращает true. Вызовите pendingDatagramSize() для получения размера первой ожидающей датаграммы и readDatagram() или receiveDatagram() для её чтения.

Примечание: Входящую датаграмму следует прочитать при получении сигнала readyRead(), в противном случае этот сигнал не будет излучен для следующей датаграммы.

Пример:

void Server::initSocket()
{
    udpSocket = new QUdpSocket(this);
    udpSocket->bind(QHostAddress::LocalHost, 7755);

    connect(udpSocket, &QUdpSocket::readyRead,
            this, &Server::readPendingDatagrams);
}

void Server::readPendingDatagrams()
{
    while (udpSocket->hasPendingDatagrams()) {
        QNetworkDatagram datagram = udpSocket->receiveDatagram();
        processTheDatagram(datagram);
    }
}

QUdpSocket также поддерживает UDP-мультипоток. Используйте joinMulticastGroup() и leaveMulticastGroup() для управления членством в группе, а также QAbstractSocket::MulticastTtlOption и QAbstractSocket::MulticastLoopbackOption для установки опций TTL и обратной петли сокета. Используйте setMulticastInterface() для управления исходящим интерфейсом для мультипотоковых датаграмм и multicastInterface() для его запроса.

С помощью QUdpSocket вы также можете установить виртуальное соединение с UDP-сервером, используя connectToHost(), а затем использовать read() и write() для обмена датаграммами без указания получателя для каждой датаграммы.

Примеры Отправителя широковещательных сообщений, Приёмника широковещательных сообщений, Отправителя групповых сообщений и Приёмника групповых сообщений демонстрируют, как использовать QUdpSocket в приложениях.

См. также QTcpSocket и QNetworkDatagram.

Документация по функциям-членам

QUdpSocket::QUdpSocket(QObject *parent = nullptr)

Создаёт объект QUdpSocket.

parent передаётся конструктору QObject.

См. также socketType().

[virtual] QUdpSocket::~QUdpSocket()

Уничтожает сокет, закрывая соединение при необходимости.

См. также close().

bool QUdpSocket::hasPendingDatagrams() const

Возвращает true true, если хотя бы одна датаграмма ожидает чтения; в противном случае возвращает false false.

См. также pendingDatagramSize() и readDatagram().

bool QUdpSocket::joinMulticastGroup(const QHostAddress &groupAddress)

Подключается к группе мультипотока, заданной groupAddress, на интерфейсе по умолчанию, выбранном операционной системой. Сокет должен находиться в состоянии BoundState, в противном случае возникает ошибка.

Обратите внимание, что если вы пытаетесь присоединиться к IPv4-группе, ваш сокет не должен быть привязан с использованием IPv6 (или в двойном режиме с использованием QHostAddress::Any). Вместо этого необходимо использовать QHostAddress::AnyIPv4.

Эта функция возвращает true при успехе; в противном случае она возвращает false и устанавливает ошибку сокета соответственно.

Примечание: Подключение к IPv6-группам мультипотока без выбора интерфейса не поддерживается во всех операционных системах. Рассмотрите использование перегрузки, где интерфейс указан.

См. также leaveMulticastGroup().

bool QUdpSocket::joinMulticastGroup(const QHostAddress &groupAddress, const QNetworkInterface &iface)

Это перегруженная функция.

Подключается к адресу мультипотока groupAddress на интерфейсе iface.

См. также leaveMulticastGroup().

bool QUdpSocket::leaveMulticastGroup(const QHostAddress &groupAddress)

Выходит из группы мультипотока, заданной groupAddress, на интерфейсе по умолчанию, выбранном операционной системой. Сокет должен находиться в состоянии BoundState, в противном случае возникает ошибка.

Эта функция возвращает true при успехе; в противном случае она возвращает false и устанавливает ошибку сокета соответственно.

Примечание: Эта функция должна вызываться с теми же аргументами, что и были переданы в joinMulticastGroup().

См. также joinMulticastGroup().

bool QUdpSocket::leaveMulticastGroup(const QHostAddress &groupAddress, const QNetworkInterface &iface)

Это перегруженная функция.

Оставляет мультивещательную группу, указанную groupAddress, на интерфейсе iface.

Примечание: Эта функция должна вызываться с теми же аргументами, что и были переданы в joinMulticastGroup().

См. также joinMulticastGroup().

QNetworkInterface QUdpSocket::multicastInterface() const

Возвращает интерфейс для исходящего интерфейса для мультивещательных пакетов. Это соответствует опции сокета IP_MULTICAST_IF для сокетов IPv4 и опции сокета IPV6_MULTICAST_IF для сокетов IPv6. Если ранее не был задан интерфейс, эта функция возвращает недействительный QNetworkInterface. Сокет должен быть в состоянии BoundState, в противном случае возвращается недействительный QNetworkInterface.

См. также setMulticastInterface().

qint64 QUdpSocket::pendingDatagramSize() const

Возвращает размер первого ожидающего UDP пакета. Если пакет недоступен, эта функция возвращает -1.

См. также hasPendingDatagrams() и readDatagram().

qint64 QUdpSocket::readDatagram(char *data, qint64 maxSize, QHostAddress *address = nullptr, quint16 *port = nullptr)

Принимает пакет размером не более maxSize байтов и сохраняет его в data. Адрес хоста и порт отправителя сохраняются в *address и *port (если указатели не nullptr).

Возвращает размер пакета при успехе; в противном случае возвращает -1.

Если maxSize слишком мал, остальная часть пакета будет потеряна. Чтобы избежать потери данных, вызовите pendingDatagramSize() для определения размера ожидающего пакета перед его чтением. Если maxSize равен 0, пакет будет отброшен.

См. также writeDatagram(), hasPendingDatagrams() и pendingDatagramSize().

[since 5.8] QNetworkDatagram QUdpSocket::receiveDatagram(qint64 maxSize = -1)

Принимает пакет размером не более maxSize байтов и возвращает его в объекте QNetworkDatagram, вместе с адресом хоста и портом отправителя. Если возможно, эта функция также попытается определить адрес назначения пакета, порт и количество переходов во время приема.

При ошибке возвращает QNetworkDatagram, который сообщает о недействительности.

Если maxSize слишком мал, остальная часть пакета будет потеряна. Если maxSize равен 0, пакет будет отброшен. Если maxSize равен -1 (по умолчанию), эта функция попытается прочитать весь пакет.

Эта функция была добавлена в Qt 5.8.

См. также writeDatagram(), hasPendingDatagrams() и pendingDatagramSize().

void QUdpSocket::setMulticastInterface(const QNetworkInterface &iface)

Устанавливает исходящий интерфейс для мультивещательных пакетов на интерфейс iface. Это соответствует опции сокета IP_MULTICAST_IF для сокетов IPv4 и опции сокета IPV6_MULTICAST_IF для сокетов IPv6. Сокет должен быть в состоянии BoundState, в противном случае эта функция ничего не делает.

См. также multicastInterface(), joinMulticastGroup() и leaveMulticastGroup().

qint64 QUdpSocket::writeDatagram(const char *data, qint64 size, const QHostAddress &address, quint16 port)

Отправляет пакет из data размером size хосту address на порт port. Возвращает количество отправленных байтов при успехе; в противном случае возвращает -1.

Пакеты всегда отправляются как один блок. Максимальный размер пакета сильно зависит от платформы, но может быть до 8192 байтов. Если пакет слишком большой, эта функция вернёт -1, а error() вернёт DatagramTooLargeError.

Отправка пакетов размером больше 512 байтов, как правило, не рекомендуется, так как даже если они отправлены успешно, они, вероятно, будут фрагментированы слоем IP перед прибытием к конечному пункту назначения.

Предупреждение: Вызов этой функции для подключенного UDP сокета может привести к ошибке и отсутствию отправленного пакета. Если вы используете подключённый сокет, используйте write() для отправки пакетов.

См. также readDatagram() и write().

[since 5.8] qint64 QUdpSocket::writeDatagram(const QNetworkDatagram &datagram)

Это перегруженная функция.

Отправляет пакет datagram на хост и номер порта, указанные в datagram, используя сетевой интерфейс и ограничения количества переходов, также установленные там. Если адрес назначения и номера портов не заданы, эта функция отправит на адрес, который был передан в connectToHost().

Если адрес назначения IPv6 с ненулевым идентификатором области, но отличается от индекса интерфейса в datagram, не определено, какой интерфейс выберет операционная система для отправки.

Функция возвращает количество отправленных байтов при успехе или -1 при возникновении ошибки.

Предупреждение: Вызов этой функции для подключенного UDP сокета может привести к ошибке и отсутствию отправленного пакета. Если вы используете подключённый сокет, используйте write() для отправки пакетов.

Эта функция была добавлена в Qt 5.8.

См. также QNetworkDatagram::setDestination(), QNetworkDatagram::setHopLimit() и QNetworkDatagram::setInterfaceIndex().

qint64 QUdpSocket::writeDatagram(const QByteArray &datagram, const QHostAddress &host, quint16 port)

Это перегруженная функция.

Отправляет пакет datagram на хост host на порт port.

Функция возвращает количество отправленных байтов при успехе или -1 при возникновении ошибки.