Класс QNetworkSession

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

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

Типы публичного доступа

Функции публичного доступа

• 31 функция публичного доступа унаследована от QObject

Слот публичного доступа

• 1 слот публичного доступа унаследован от QObject

Сигналы

• 2 сигнала унаследованы от QObject

Статические члены публичного доступа

• 9 статических членов публичного доступа унаследованы от QObject

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

• 1 свойство унаследовано от QObject
• 9 защищенных функций унаследованы от QObject

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

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

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.

[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.

QNetworkSession::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 только когда эта сессия находится в состоянии Connected.

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

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

bool QNetworkSession::isOpen() const

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

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

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

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

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

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

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

[slot] void QNetworkSession::stop()

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

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