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