Класс 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)

Этот сигнал испускается, когда система изменяет действующие 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().