Класс QUdpSocket

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

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

Примечание: Все функции в этом классе являются реентерабельными.

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

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

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

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

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

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

Пример:

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 и loopback сокета. Используйте 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 если по крайней мере одна датаграмма ожидает чтения; в противном случае возвращает false.

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

bool QUdpSocket::joinMulticastGroup(const QHostAddress &groupAddress)

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

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

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

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

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

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

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

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

bool QUdpSocket::leaveMulticastGroup(const QHostAddress &groupAddress)

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

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

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

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

Это перегруженный метод.

Выходит из мультигруппового канала, указанного groupAddress, на интерфейсе iface.

См. также 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 перед прибытием в пункт назначения.

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

qint64 QUdpSocket::writeDatagram(const QNetworkDatagram &datagram)

Это перегруженный метод.

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

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

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

Этот метод был представлен в Qt 5.8.

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

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

Это перегруженный метод.

Отправляет дейтаграмму datagram на хост host по порту port.

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