内容

• 公共类型
• 公共函数
• 公共槽
• 信号
• 静态公共成员
• 详细描述
• 漫游

QNetworkSession Class

The QNetworkSession class provides control over the system's access points and enables session management for cases when multiple clients access the same access point. 更多...

• 所有成员列表，包括继承成员
• 过时成员

公共类型

公共函数

• 31 公共函数继承自 QObject

公共槽

• 1 公共槽继承自 QObject

信号

• 2 信号继承自 QObject

静态公共成员

• 9 静态公共成员继承自 QObject

额外继承成员

• 1 特性继承自 QObject
• 9 保护函数继承自 QObject

详细描述

The QNetworkSession class provides control over the system's access points and enables session management for cases when multiple clients access the same access point.

A QNetworkSession enables control over the system's network interfaces. The session's configuration parameter are determined via the QNetworkConfiguration object to which it is bound. Depending on the type of the session (single access point or service network) a session may be linked to one or more network interfaces. By means of opening and closing of network sessions a developer can start and stop the systems network interfaces. If the configuration represents multiple access points (see QNetworkConfiguration::ServiceNetwork ) more advanced features such as roaming may be supported.

QNetworkSession supports session management within the same process and depending on the platform's capabilities may support out-of-process sessions. If the same network configuration is used by multiple open sessions the underlying network interface is only terminated once the last session has been closed.

漫游

Applications may connect to the preferredConfigurationChanged () signal in order to receive notifications when a more suitable access point becomes available. In response to this signal the application must either initiate the roaming via migrate () 或 ignore () the new access point. Once the session has roamed the newConfigurationActivated () signal is emitted. The application may now test the carrier and must either accept () 或 reject () it. The session will return to the previous access point if the roaming was rejected. The subsequent state diagram depicts the required state transitions.

Some platforms may distinguish forced roaming and application level roaming (ALR). ALR implies that the application controls (via migrate (), ignore (), accept () 和 reject ()) whether a network session can roam from one access point to the next. Such control is useful if the application maintains stateful socket connections and wants to control the transition from one interface to the next. Forced roaming implies that the system automatically roams to the next network without consulting the application. This has the advantage that the application can make use of roaming features without actually being aware of it. It is expected that the application detects that the underlying socket is broken and automatically reconnects via the new network link.

If the platform supports both modes of roaming, an application indicates its preference by connecting to the preferredConfigurationChanged () signal. Connecting to this signal means that the application wants to take control over the roaming behavior and therefore implies application level roaming. If the client does not connect to the preferredConfigurationChanged (), forced roaming is used. If forced roaming is not supported the network session will not roam by default.

Some applications may want to suppress any form of roaming altogether. Possible use cases may be high priority downloads or remote services which cannot handle a roaming enabled client. Clients can suppress roaming by connecting to the preferredConfigurationChanged () signal and answer each signal emission with ignore ().

另请参阅 QNetworkConfiguration and QNetworkConfigurationManager .

成员类型文档编制

enum QNetworkSession:: SessionError

This enum describes the session errors that can occur.

enum QNetworkSession:: State

This enum describes the connectivity state of the session. If the session is based on a single access point configuration the state of the session is the same as the state of the associated network interface.

enum QNetworkSession:: UsagePolicy
flags QNetworkSession:: UsagePolicies

These flags allow the system to inform the application of network usage restrictions that may be in place.

该枚举在 Qt 5.0 引入或被修改。

The UsagePolicies type is a typedef for QFlags <UsagePolicy>. It stores an OR combination of UsagePolicy values.

成员函数文档编制

QNetworkSession:: QNetworkSession (const QNetworkConfiguration & connectionConfig , QObject * parent = nullptr)

Constructs a session based on connectionConfig 采用给定 parent .

另请参阅 QNetworkConfiguration .

[虚拟] QNetworkSession:: ~QNetworkSession ()

释放资源关联 QNetworkSession 对象。

[slot] void QNetworkSession:: accept ()

Instructs the session to permanently accept the new access point. Once this function has been called the session may not return to the old access point.

The old access point may be closed in the process if there are no other network sessions for it. Therefore any open socket that still uses the old access point may become unusable and should be closed before completing the migration.

quint64 QNetworkSession:: activeTime () const

Returns the number of seconds that the session has been active.

quint64 QNetworkSession:: bytesReceived () const

Returns the amount of data received in bytes; otherwise 0.

This field value includes the usage across all open network sessions which use the same network interface.

If the session is based on a service network configuration the number of sent bytes across all active member configurations are returned.

This function may not always be supported on all platforms and returns 0. The platform capability can be detected via QNetworkConfigurationManager::DataStatistics .

注意： On some platforms this function may run the main event loop.

quint64 QNetworkSession:: bytesWritten () const

Returns the amount of data sent in bytes; otherwise 0.

This field value includes the usage across all open network sessions which use the same network interface.

If the session is based on a service network configuration the number of sent bytes across all active member configurations are returned.

This function may not always be supported on all platforms and returns 0. The platform capability can be detected via QNetworkConfigurationManager::DataStatistics .

注意： On some platforms this function may run the main event loop.

[slot] void QNetworkSession:: close ()

Decreases the session counter on the associated network configuration. If the session counter reaches zero the active network interface is shut down. This also means that state () will only change from Connected to Disconnected if the current session was the last open session.

If the platform does not support out-of-process sessions calling this function does not stop the interface. In this case stop () has to be used to force a shut down. The platform capabilities can be detected via QNetworkConfigurationManager::capabilities ().

Note that this call is asynchronous. Depending on the outcome of this call the results can be enquired by connecting to the stateChanged (), opened () 或 error () 信号。

另请参阅 open (), stop ()，和 isOpen ().

[signal] void QNetworkSession:: closed ()

This signal is emitted when the network session has been closed.

QNetworkConfiguration QNetworkSession:: configuration () const

返回 QNetworkConfiguration that this network session object is based on.

另请参阅 QNetworkConfiguration .

QNetworkSession::SessionError QNetworkSession:: error () const

返回最后发生的错误类型。

另请参阅 state () 和 errorString ().

[signal] void QNetworkSession:: error ( QNetworkSession::SessionError error )

此信号发射，在发生错误后。 error parameter describes the error that occurred.

注意： 信号 error 在此类中被重载。通过使用函数指针句法连接到此信号，Qt 提供用于获得如此范例展示的函数指针的方便帮助程序：

connect(networkSession, QOverload<QNetworkSession::SessionError>::of(&QNetworkSession::error),
    [=](QNetworkSession::SessionError error){ /* ... */ });
					

另请参阅 error () 和 errorString ().

QString QNetworkSession:: errorString () const

返回人类可读的最后发生的设备错误描述。

另请参阅 error ().

[slot] void QNetworkSession:: ignore ()

This function indicates that the application does not wish to roam the session.

另请参阅 migrate ().

QNetworkInterface QNetworkSession:: interface () const

Returns the network interface that is used by this session.

This function only returns a valid QNetworkInterface when this session is Connected .

The returned interface may change as a result of a roaming process.

另请参阅 state ().

bool QNetworkSession:: isOpen () const

返回 true if this session is open. If the number of all open sessions is greater than zero the underlying network interface will remain connected/up.

The session can be controlled via open () 和 close ().

[slot] void QNetworkSession:: migrate ()

Instructs the session to roam to the new access point. The old access point remains active until the application calls accept ().

The newConfigurationActivated () signal is emitted once roaming has been completed.

另请参阅 accept ().

[signal] void QNetworkSession:: newConfigurationActivated ()

This signal is emitted once the session has roamed to the new access point. The application may reopen its socket and test the suitability of the new network link. Subsequently it must either accept () 或 reject () the new access point.

另请参阅 accept () 和 reject ().

[slot] void QNetworkSession:: open ()

Creates an open session which increases the session counter on the underlying network interface. The system will not terminate a network interface until the session reference counter reaches zero. Therefore an open session allows an application to register its use of the interface.

As a result of calling open() the interface will be started if it is not connected/up yet. Some platforms may not provide support for out-of-process sessions. On such platforms the session counter ignores any sessions held by another process. The platform capabilities can be detected via QNetworkConfigurationManager::capabilities ().

Note that this call is asynchronous. Depending on the outcome of this call the results can be enquired by connecting to the stateChanged (), opened () 或 error () 信号。

It is not a requirement to open a session in order to monitor the underlying network interface.

另请参阅 close (), stop ()，和 isOpen ().

[signal] void QNetworkSession:: opened ()

This signal is emitted when the network session has been opened.

The underlying network interface will not be shut down as long as the session remains open. Note that this feature is dependent on system wide session support .

[signal] void QNetworkSession:: preferredConfigurationChanged (const QNetworkConfiguration & config , bool isSeamless )

This signal is emitted when the preferred configuration/access point for the session changes. Only sessions which are based on service network configurations may emit this signal. config can be used to determine access point specific details such as proxy settings and isSeamless indicates whether roaming will break the sessions IP address.

As a consequence to this signal the application must either start the roaming process by calling migrate () or choose to ignore () the new access point.

If the roaming process is non-seamless the IP address will change which means that a socket becomes invalid. However seamless mobility can ensure that the local IP address does not change. This is achieved by using a virtual IP address which is bound to the actual link address. During the roaming process the virtual address is attached to the new link address.

Some platforms may support the concept of Forced Roaming and Application Level Roaming (ALR). Forced roaming implies that the platform may simply roam to a new configuration without consulting applications. It is up to the application to detect the link layer loss and reestablish its sockets. In contrast ALR provides the opportunity to prevent the system from roaming. If this session is based on a configuration that supports roaming the application can choose whether it wants to be consulted (ALR use case) by connecting to this signal. For as long as this signal connection remains the session remains registered as a roaming stakeholder; otherwise roaming will be enforced by the platform.

另请参阅 migrate (), ignore ()，和 QNetworkConfiguration::isRoamingAvailable ().

[slot] void QNetworkSession:: reject ()

The new access point is not suitable for the application. By calling this function the session returns to the previous access point/configuration. This action may invalidate any socket that has been created via the not desired access point.

另请参阅 accept ().

QVariant QNetworkSession:: sessionProperty (const QString & key ) const

Returns the value for property key .

A network session can have properties attached which may describe the session in more details. This function can be used to gain access to those properties.

The following property keys are guaranteed to be specified on all platforms:

    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 on the session. The property is identified using key . Removing an already set property can be achieved by passing an invalid QVariant .

注意， UserChoiceConfiguration and ActiveConfiguration properties are read only and cannot be changed using this method.

另请参阅 sessionProperty ().

QNetworkSession::State QNetworkSession:: state () const

Returns the state of the session.

If the session is based on a single access point configuration the state of the session is the same as the state of the associated network interface. Therefore a network session object can be used to monitor network interfaces.

A QNetworkConfiguration::ServiceNetwork based session summarizes the state of all its children and therefore returns the Connected state if at least one of the service network's children() configurations is active.

Note that it is not required to hold an open session in order to obtain the network interface state. A connected but closed session may be used to monitor network interfaces whereas an open and connected session object may prevent the network interface from being shut down.

另请参阅 error () 和 stateChanged ().

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

This signal is emitted whenever the state of the network session changes. The state 参数是新状态。

另请参阅 state ().

[slot] void QNetworkSession:: stop ()

Invalidates all open sessions against the network interface and therefore stops the underlying network interface. This function always changes the session's state () flag to Disconnected .

另请参阅 open () 和 close ().

QNetworkSession::UsagePolicies QNetworkSession:: usagePolicies () const

Returns the network usage policies currently in force by the system.

[signal] void QNetworkSession:: usagePoliciesChanged ( QNetworkSession::UsagePolicies usagePolicies )

此信号发射当 usagePolicies in force are changed by the system.

该函数在 Qt 5.0 引入。

bool QNetworkSession:: waitForOpened ( int msecs = 30000)

Waits until the session has been opened, up to msecs milliseconds. If the session has been opened, this function returns true ；否则，返回 false 。若它返回 false ，可以调用 error () 以确定错误的原因。

The following example waits up to one second for the session to be opened:

    session->open();
    if (session->waitForOpened(1000))
        qDebug("Open!");
					

若 msecs 是 -1，此函数不会超时。

另请参阅 open () 和 error ().