Класс QNetworkSession

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

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

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

Открытые функции

• 31 открытая функция, унаследованная от QObject

Открытые слоты

• 1 открытый слот, унаследованный от QObject

Сигналы

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

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

• 1 свойство, унаследованное от QObject
• 11 статических открытых членов, унаследованных от 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 = 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 перегружен в этом классе. Чтобы подключиться к нему с помощью синтаксиса указателя функции, необходимо указать тип сигнала в статическом преобразовании, как показано в этом примере:

connect(networkSession, static_cast<void(QNetworkSession::*)(QNetworkSession::SessionError)>(&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() 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().