Класс QNetworkSession

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

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

Типы

Публичные функции

• 32 public functions inherited from QObject

Публичные слоты

• 1 public slot inherited from QObject

Сигналы

• 2 signals inherited from QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 11 статических public members, унаследованных от QObject
• 9 protected functions, унаследованных от QObject

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

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

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

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

Роуминг

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

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

Если платформа поддерживает оба режима роуминга, приложение указывает свои предпочтения, подключившись к сигналу 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 = Q_NULLPTR)

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

См. также QNetworkConfiguration.

[virtual] QNetworkSession::~QNetworkSession()

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

[slot] void QNetworkSession::accept()

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

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

quint64 QNetworkSession::activeTime() const

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

quint64 QNetworkSession::bytesReceived() const

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

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

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

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

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

quint64 QNetworkSession::bytesWritten() const

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

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

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

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

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

[slot] void QNetworkSession::close()

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

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

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

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

[signal] void QNetworkSession::closed()

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

QNetworkConfiguration QNetworkSession::configuration() const

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

См. также QNetworkConfiguration.

SessionError QNetworkSession::error() const

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

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

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

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

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

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

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

QString QNetworkSession::errorString() const

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

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

[slot] void QNetworkSession::ignore()

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

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

QNetworkInterface QNetworkSession::interface() const

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

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

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

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

bool QNetworkSession::isOpen() const

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

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

[slot] void QNetworkSession::migrate()

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

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

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

[signal] void QNetworkSession::newConfigurationActivated()

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

См. также 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().

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

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

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

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

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

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

Состояние QNetworkSession::state() const

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

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

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

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

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

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

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

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

[slot] void QNetworkSession::stop()

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

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

QNetworkSession::UsagePolicies QNetworkSession::usagePolicies() const

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

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

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

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

bool QNetworkSession::waitForOpened(int msecs = 30000)

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

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

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

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

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