Класс 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() для обмена дейтаграммами без указания получателя для каждой дейтаграммы.

Примеры Broadcast Sender, Broadcast Receiver, Multicast Sender и Multicast Receiver иллюстрируют, как использовать QUdpSocket в приложениях.

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

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

QUdpSocket::QUdpSocket(QObject *parent = nullptr)

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

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

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

[virtual] QUdpSocket::~QUdpSocket()

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

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

bool QUdpSocket::hasPendingDatagrams() const

Возвращает true если хотя бы одна дейтаграмма ожидает чтения; в противном случае возвращает 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().

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

qint64 QUdpSocket::writeDatagram(const QNetworkDatagram &datagram)

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

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

Если адрес назначения IPv6 с ненулевым scope id, но отличается от индекса интерфейса в 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 в случае ошибки.