Класс QNetworkSession

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

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

Типы Public

Функции Public

• 34 public functions inherited from QObject

Слот Public

• 1 public slot inherited from QObject

Сигналы

• 2 signals inherited from QObject

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

• 1 свойство, унаследованное от QObject
• 1 public переменная, унаследованная от QObject
• 10 static public членов, унаследованных от QObject
• 9 protected функций, унаследованных от QObject
• 2 protected переменных, унаследованных от 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 );
}

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

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

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

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

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

QNetworkSession::State QNetworkSession::state() const

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

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

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

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

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