Класс QNetworkSession

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

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

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

Открытые типы

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

Открытые слоты

Сигналы

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

QNetworkSession позволяет управлять сетевыми интерфейсами системы. Параметры конфигурации сессии определяются через объект QNetworkConfiguration, к которому она привязана. В зависимости от типа сессии (одна точка доступа или сетевой сервис) сессия может быть связана с одним или несколькими сетевыми интерфейсами. С помощью открытия и закрытия сетевых сессий разработчик может запускать и останавливать сетевые интерфейсы системы. Если конфигурация представляет несколько точек доступа (см. QNetworkConfiguration::ServiceNetwork), могут поддерживаться более сложные функции, такие как роуминг.

QNetworkSession поддерживает управление сессиями в рамках одного процесса и, в зависимости от возможностей платформы, может поддерживать сессии вне процесса. Если одну и ту же сетевую конфигурацию используют несколько открытых сессий, подлежащий сетевой интерфейс закрывается только после закрытия последней сессии.

Роуминг

Приложения могут подключиться к сигналу preferredConfigurationChanged(), чтобы получать уведомления о доступности более подходящей точки доступа. В ответ на этот сигнал приложение должно либо инициировать роуминг через migrate(), либо ignore() новую точку доступа. После того, как сессия перешла на роуминг, генерируется сигнал newConfigurationActivated(). Приложение теперь может проверить носитель и либо accept() его, либо reject(). Сессия вернётся к предыдущей точке доступа, если роуминг был отклонен. Последующая диаграмма состояний демонстрирует необходимые переходы состояний.

Некоторые платформы могут различать принудительный роуминг и роуминг на уровне приложения (ALR). ALR подразумевает, что приложение управляет (через migrate(), ignore(), accept() и reject()), может ли сетевая сессия переходить с одной точки доступа на другую. Такой контроль полезен, если приложение поддерживает сокеты со состояниями и хочет управлять переходом с одного интерфейса на другой. Принудительный роуминг подразумевает, что система автоматически переходит на следующий сетевой ресурс, не консультируясь с приложением. Преимущество этого в том, что приложение может использовать возможности роуминга, не зная об этом. Ожидается, что приложение обнаружит, что подлежащий сокет разорван, и автоматически переподключится к новому сетевому соединению.

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

Некоторые приложения могут захотеть подавить любую форму роуминга. Возможными случаями использования могут быть загрузочные файлы высокой приоритетности или удалённые службы, которые не могут обработать клиент с включённым роумингом. Клиенты могут подавить роуминг, подключившись к сигналу preferredConfigurationChanged() и отвечая на каждое срабатывание сигнала с помощью ignore().

См. также QNetworkConfiguration и QNetworkConfigurationManager.

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

enum QNetworkSession::SessionError

Этот перечисление описывает ошибки сессии, которые могут возникнуть.

enum QNetworkSession::State

Это перечисление описывает состояние подключения сессии. Если сессия основана на конфигурации единственной точки доступа, состояние сессии совпадает с состоянием соответствующего сетевого интерфейса.

enum QNetworkSession::UsagePolicyflags QNetworkSession::UsagePolicies

Эти флаги позволяют системе сообщать приложению о ограничениях использования сети, которые могут быть введены.

Это перечисление было добавлено или изменено в Qt 5.0.

Тип UsagePolicies является псевдонимом для QFlags<UsagePolicy>. Он хранит логическое ИЛИ сочетание значений UsagePolicy.

Документация функций членов

QNetworkSession::QNetworkSession(const QNetworkConfiguration &connectionConfig, QObject *parent = nullptr)

Создаёт сессию, основанную на connectionConfig с заданным parent.

См. также QNetworkConfiguration.

[slot] void QNetworkSession::accept()

Инструктирует сессию постоянно принять новую точку доступа. После вызова этой функции сессия не может вернуться к старой точке доступа.

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

[slot] void QNetworkSession::close()

Уменьшает счётчик сессий в связанной сетевой конфигурации. Если счётчик сессий достигнет нуля, активный сетевой интерфейс будет выключен. Это также означает, что state() изменится только с Connected на Disconnected, если текущая сессия была последней открытой сессией.

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

Обратите внимание, что этот вызов асинхронный. В зависимости от результата этого вызова, результаты можно запросить, подключившись к сигналам stateChanged(), opened() или error().

См. также open(), stop() и isOpen().

[signal] void QNetworkSession::closed()

Этот сигнал испускается, когда сетевая сессия была закрыта.

[signal] void QNetworkSession::error(QNetworkSession::SessionError error)

Этот сигнал испускается после возникновения ошибки. Параметр error описывает произошедшую ошибку.

Примечание: Сигнал error перегружен в этом классе. Для подключения к этому сигналу с помощью синтаксиса указателя функции Qt предоставляет удобную вспомогательную функцию для получения указателя функции, как показано в этом примере:

connect(networkSession, QOverload<QNetworkSession::SessionError>::of(&QNetworkSession::error),
    [=](QNetworkSession::SessionError error){ /* ... */ });

См. также error() и errorString().

[slot] void QNetworkSession::ignore()

Эта функция указывает, что приложение не хочет перемещать сессию.

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

[slot] void QNetworkSession::migrate()

Инструктирует сессию перейти на новую точку доступа. Старая точка доступа остаётся активной до тех пор, пока приложение не вызовет accept().

Сигнал newConfigurationActivated() испускается после завершения перемещения.

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

[signal] void QNetworkSession::newConfigurationActivated()

Этот сигнал испускается, когда сессия переместилась на новую точку доступа. Приложение может повторно открыть свой сокет и проверить пригодность нового сетевого подключения. Впоследствии оно должно либо accept(), либо reject() новую точку доступа.

См. также accept() и reject().

[slot] void QNetworkSession::open()

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

В результате вызова open() интерфейс будет запущен, если он ещё не подключен/не активен. Некоторые платформы могут не поддерживать сессии вне процесса. На таких платформах счётчик сессий игнорирует любые сессии, удерживаемые другим процессом. Возможности платформы можно определить с помощью QNetworkConfigurationManager::capabilities().

Обратите внимание, что этот вызов асинхронный. В зависимости от результата этого вызова, результаты можно запросить, подключившись к сигналам stateChanged(), opened() или error().

Открытие сессии не является обязательным для мониторинга базового сетевого интерфейса.

См. также close(), stop() и isOpen().

[signal] void QNetworkSession::opened()

Этот сигнал испускается, когда сетевая сессия была открыта.

Базовый сетевой интерфейс не будет закрыт до тех пор, пока сессия остаётся открытой. Обратите внимание, что эта функция зависит от поддержки сессий на уровне всей системы.

[signal] void QNetworkSession::preferredConfigurationChanged(const QNetworkConfiguration &config, bool isSeamless)

Этот сигнал испускается при изменении предпочтительной конфигурации/точки доступа для сессии. Только сессии, основанные на конфигурациях сетевых сервисов, могут испускать этот сигнал. config может использоваться для определения деталей, специфичных для точки доступа, таких как настройки прокси, а isSeamless указывает, будет ли разрыв подключения при роуминге влиять на IP-адрес сессии.

Вследствие этого сигнала приложение должно либо начать процесс роуминга, вызвав migrate(), либо выбрать ignore() новую точку доступа.

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

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

См. также migrate(), ignore(), и QNetworkConfiguration::isRoamingAvailable().

[slot] void QNetworkSession::reject()

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

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

[signal] void QNetworkSession::stateChanged(QNetworkSession::State state)

Этот сигнал испускается всякий раз, когда состояние сетевой сессии изменяется. Параметр state — это новое состояние.

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

[slot] void QNetworkSession::stop()

Аннулирует все открытые сессии по отношению к сетевому интерфейсу и, следовательно, останавливает работу базового сетевого интерфейса. Эта функция всегда изменяет флаг состояния сессии state() на Disconnected.

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

[signal] void QNetworkSession::usagePoliciesChanged(QNetworkSession::UsagePolicies usagePolicies)

Этот сигнал испускается, когда система изменяет действующие политики использования.

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

[virtual] QNetworkSession::~QNetworkSession()

Освобождает ресурсы, связанные с объектом QNetworkSession.

quint64 QNetworkSession::activeTime() const

Возвращает количество секунд, в течение которых сессия была активна.

quint64 QNetworkSession::bytesReceived() const

Возвращает объем полученных данных в байтах; иначе 0.

Это значение включает использование по всем открытым сетевым сессиям, которые используют один и тот же сетевой интерфейс.

Если сессия основана на конфигурации сетевого сервиса, возвращается количество отправленных байтов по всем активным конфигурациям-членам.

Эта функция может не поддерживаться на всех платформах и возвращает 0. Возможность платформы может быть определена с помощью QNetworkConfigurationManager::DataStatistics.

Примечание: На некоторых платформах эта функция может запустить основной цикл событий.

quint64 QNetworkSession::bytesWritten() const

Возвращает объем отправленных данных в байтах; иначе 0.

Это значение включает использование по всем открытым сетевым сессиям, которые используют один и тот же сетевой интерфейс.

Если сессия основана на конфигурации сетевого сервиса, возвращается количество отправленных байтов по всем активным конфигурациям-членам.

Эта функция может не поддерживаться на всех платформах и возвращает 0. Возможность платформы может быть определена с помощью QNetworkConfigurationManager::DataStatistics.

Примечание: На некоторых платформах эта функция может запустить основной цикл событий.

QNetworkConfiguration QNetworkSession::configuration() const

Возвращает QNetworkConfiguration, на которой основана эта сетевая сессия.

См. также QNetworkConfiguration.

QNetworkSession::SessionError QNetworkSession::error() const

Возвращает тип последней произошедшей ошибки.

См. также state() и errorString().

QString QNetworkSession::errorString() const

Возвращает удобочитаемое описание последней ошибки устройства.

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

QNetworkInterface QNetworkSession::interface() const

Возвращает сетевой интерфейс, используемый этой сессией.

Эта функция возвращает допустимый QNetworkInterface только тогда, когда эта сессия находится в состоянии Connected.

Возвращенный интерфейс может измениться в результате процесса роуминга.

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

bool QNetworkSession::isOpen() const

Возвращает true , если эта сессия открыта. Если количество всех открытых сессий больше нуля, базовый сетевой интерфейс останется подключенным/включенным.

Сессию можно контролировать с помощью open() и close().

QVariant QNetworkSession::sessionProperty(const QString &key) const

Возвращает значение свойства key.

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

Следующие ключи свойств гарантированно будут заданы на всех платформах:

    QNetworkConfigurationManager mgr;
    QNetworkConfiguration ap = mgr.defaultConfiguration();
    QNetworkSession *session = new QNetworkSession(ap);
    ... //code activates session

    QString ident = session->sessionProperty("ActiveConfiguration").toString();
    if ( ap.type() == QNetworkConfiguration::ServiceNetwork ) {
        Q_ASSERT( ap.identifier() != ident );
        Q_ASSERT( ap.children().contains( mgr.configurationFromIdentifier(ident) ) );
    } else if ( ap.type() == QNetworkConfiguration::InternetAccessPoint ) {
        Q_ASSERT( ap.identifier() == ident );
    }
                \endcode

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

void QNetworkSession::setSessionProperty(const QString &key, const QVariant &value)

Устанавливает свойство value для сеанса. Свойство идентифицируется с помощью key. Удаление уже установленного свойства может быть выполнено путём передачи недопустимого значения QVariant.

Обратите внимание, что свойства UserChoiceConfiguration и ActiveConfiguration являются только для чтения и не могут быть изменены с помощью этого метода.

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

QNetworkSession::State QNetworkSession::state() const

Возвращает состояние сеанса.

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

Сеанс, основанный на QNetworkConfiguration::ServiceNetwork, суммирует состояние всех его дочерних элементов и, следовательно, возвращает состояние Connected, если хотя бы одна из конфигураций дочерних элементов сетевой службы активна.

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

См. также error() и stateChanged().

QNetworkSession::UsagePolicies QNetworkSession::usagePolicies() const

Возвращает сетевые политики использования, действующие в системе в данный момент.

bool QNetworkSession::waitForOpened(int msecs = 30000)

Ожидает открытия сеанса в течение msecs миллисекунд. Если сеанс открыт, эта функция возвращает true; в противном случае она возвращает false. В случае возврата false, вы можете вызвать error() для определения причины ошибки.

Следующий пример ожидает открытия сеанса в течение одной секунды:

    session->open();
    if (session->waitForOpened(1000))
        qDebug("Open!");

Если msecs равно -1, эта функция не будет ожидать истечения времени.

См. также open() и error().