Qt 4.8
Public Types | Public Slots | Signals | Public Functions | Protected Functions | Properties | Friends | List of all members
QNetworkSession Class Reference

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. More...

#include <qnetworksession.h>

Inheritance diagram for QNetworkSession:
QObject

Public Types

enum  SessionError {
  UnknownSessionError = 0, SessionAbortedError, RoamingError, OperationNotSupportedError,
  InvalidConfigurationError
}
 This enum describes the session errors that can occur. More...
 
enum  State {
  Invalid = 0, NotAvailable, Connecting, Connected,
  Closing, Disconnected, Roaming
}
 This enum describes the connectivity state of the session. More...
 

Public Slots

void accept ()
 Instructs the session to permanently accept the new access point. More...
 
void close ()
 Decreases the session counter on the associated network configuration. More...
 
void ignore ()
 This function indicates that the application does not wish to roam the session. More...
 
void migrate ()
 Instructs the session to roam to the new access point. More...
 
void open ()
 Creates an open session which increases the session counter on the underlying network interface. More...
 
void reject ()
 The new access point is not suitable for the application. More...
 
void stop ()
 Invalidates all open sessions against the network interface and therefore stops the underlying network interface. More...
 
- Public Slots inherited from QObject
void deleteLater ()
 Schedules this object for deletion. More...
 

Signals

void closed ()
 This signal is emitted when the network session has been closed. More...
 
void error (QNetworkSession::SessionError)
 This signal is emitted after an error occurred. More...
 
void newConfigurationActivated ()
 This signal is emitted once the session has roamed to the new access point. More...
 
void opened ()
 This signal is emitted when the network session has been opened. More...
 
void preferredConfigurationChanged (const QNetworkConfiguration &config, bool isSeamless)
 This signal is emitted when the preferred configuration/access point for the session changes. More...
 
void stateChanged (QNetworkSession::State)
 This signal is emitted whenever the state of the network session changes. More...
 
- Signals inherited from QObject
void destroyed (QObject *=0)
 This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...
 

Public Functions

quint64 activeTime () const
 Returns the number of seconds that the session has been active. More...
 
quint64 bytesReceived () const
 Returns the amount of data received in bytes; otherwise 0. More...
 
quint64 bytesWritten () const
 Returns the amount of data sent in bytes; otherwise 0. More...
 
QNetworkConfiguration configuration () const
 Returns the QNetworkConfiguration that this network session object is based on. More...
 
SessionError error () const
 Returns the type of error that last occurred. More...
 
QString errorString () const
 Returns a human-readable description of the last device error that occurred. More...
 
QNetworkInterface interface () const
 Returns the network interface that is used by this session. More...
 
bool isOpen () const
 Returns true if this session is open. More...
 
 QNetworkSession (const QNetworkConfiguration &connConfig, QObject *parent=0)
 Constructs a session based on connectionConfig with the given parent. More...
 
QVariant sessionProperty (const QString &key) const
 Returns the value for property key. More...
 
void setSessionProperty (const QString &key, const QVariant &value)
 Sets the property value on the session. More...
 
State state () const
 Returns the state of the session. More...
 
bool waitForOpened (int msecs=30000)
 Waits until the session has been opened, up to msecs milliseconds. More...
 
virtual ~QNetworkSession ()
 Frees the resources associated with the QNetworkSession object. More...
 
- Public Functions inherited from QObject
bool blockSignals (bool b)
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
 
const QObjectListchildren () const
 Returns a list of child objects. More...
 
bool connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
 
bool disconnect (const QObject *receiver, const char *member=0)
 
void dumpObjectInfo ()
 Dumps information about signal connections, etc. More...
 
void dumpObjectTree ()
 Dumps a tree of children to the debug output. More...
 
QList< QByteArraydynamicPropertyNames () const
 Returns the names of all properties that were dynamically added to the object using setProperty(). More...
 
virtual bool event (QEvent *)
 This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
 
virtual bool eventFilter (QObject *, QEvent *)
 Filters events if this object has been installed as an event filter for the watched object. More...
 
template<typename T >
findChild (const QString &aName=QString()) const
 Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
 
template<typename T >
QList< T > findChildren (const QString &aName=QString()) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
 
template<typename T >
QList< T > findChildren (const QRegExp &re) const
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
 
void installEventFilter (QObject *)
 Installs an event filter filterObj on this object. More...
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false. More...
 
void killTimer (int id)
 Kills the timer with timer identifier, id. More...
 
virtual const QMetaObjectmetaObject () const
 Returns a pointer to the meta-object of this object. More...
 
void moveToThread (QThread *thread)
 Changes the thread affinity for this object and its children. More...
 
QString objectName () const
 
QObjectparent () const
 Returns a pointer to the parent object. More...
 
QVariant property (const char *name) const
 Returns the value of the object's name property. More...
 
Q_INVOKABLE QObject (QObject *parent=0)
 Constructs an object with parent object parent. More...
 
void removeEventFilter (QObject *)
 Removes an event filter object obj from this object. More...
 
void setObjectName (const QString &name)
 
void setParent (QObject *)
 Makes the object a child of parent. More...
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value. More...
 
void setUserData (uint id, QObjectUserData *data)
 
bool signalsBlocked () const
 Returns true if signals are blocked; otherwise returns false. More...
 
int startTimer (int interval)
 Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
 
QThreadthread () const
 Returns the thread in which the object lives. More...
 
QObjectUserDatauserData (uint id) const
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects. More...
 

Protected Functions

virtual void connectNotify (const char *signal)
 This function is required to detect whether the client wants to control the roaming process. More...
 
virtual void disconnectNotify (const char *signal)
 This function is called when the client disconnects from the preferredConfigurationChanged() signal. More...
 
- Protected Functions inherited from QObject
virtual void childEvent (QChildEvent *)
 This event handler can be reimplemented in a subclass to receive child events. More...
 
virtual void customEvent (QEvent *)
 This event handler can be reimplemented in a subclass to receive custom events. More...
 
 QObject (QObjectPrivate &dd, QObject *parent=0)
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal. More...
 
QObjectsender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *)
 This event handler can be reimplemented in a subclass to receive timer events for the object. More...
 

Properties

QNetworkSessionPrivated
 

Friends

class QNetworkSessionPrivate
 

Additional Inherited Members

- Static Public Functions inherited from QObject
static bool connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
 
static bool connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 Disconnects signal in object sender from method in object receiver. More...
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static uint registerUserData ()
 
static QString tr (const char *sourceText, const char *comment=0, int n=-1)
 
static QString trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
 
- Static Public Variables inherited from QObject
static const QMetaObject staticMetaObject
 This variable stores the meta-object for the class. More...
 
- Protected Variables inherited from QObject
QScopedPointer< QObjectDatad_ptr
 
- Static Protected Variables inherited from QObject
static const QMetaObject staticQtMetaObject
 

Detailed Description

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.

Since
4.7
Attention
Module: QtNetwork

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.

Roaming

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() or 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() or 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.

roaming-states.png

Some platforms may distinguish forced roaming and application level roaming (ALR). ALR implies that the application controls (via migrate(), ignore(), accept() and 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().

See also
QNetworkConfiguration, QNetworkConfigurationManager

Definition at line 71 of file qnetworksession.h.

Enumerations

◆ SessionError

This enum describes the session errors that can occur.

  • UnknownSessionError An unidentified error occurred.
  • SessionAbortedError The session was aborted by the user or system.
  • RoamingError The session cannot roam to a new configuration.
  • OperationNotSupportedError The operation is not supported for current configuration.
  • InvalidConfigurationError The operation cannot currently be performed for the current configuration.
Enumerator
UnknownSessionError 
SessionAbortedError 
RoamingError 
OperationNotSupportedError 
InvalidConfigurationError 

Definition at line 86 of file qnetworksession.h.

◆ 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.

  • Invalid The session is invalid due to an invalid configuration. This may happen due to a removed access point or a configuration that was invalid to begin with.
  • NotAvailable The session is based on a defined but not yet discovered QNetworkConfiguration (see QNetworkConfiguration::StateFlag ).
  • Connecting The network session is being established.
  • Connected The network session is connected. If the current process wishes to use this session it has to register its interest by calling open(). A network session is considered to be ready for socket operations if it isOpen() and connected.
  • Closing The network session is in the process of being shut down.
  • Disconnected The network session is not connected. The associated QNetworkConfiguration has the state QNetworkConfiguration::Discovered.
  • Roaming The network session is roaming from one access point to another access point.
Enumerator
Invalid 
NotAvailable 
Connecting 
Connected 
Closing 
Disconnected 
Roaming 

Definition at line 76 of file qnetworksession.h.

Constructors and Destructors

◆ QNetworkSession()

QNetworkSession::QNetworkSession ( const QNetworkConfiguration connectionConfig,
QObject parent = 0 
)
explicit

Constructs a session based on connectionConfig with the given parent.

See also
QNetworkConfiguration

Definition at line 261 of file qnetworksession.cpp.

Referenced by QSharedNetworkSessionManager::getSession().

262  : QObject(parent), d(0)
263 {
264  // invalid configuration
265  if (!connectionConfig.identifier().isEmpty()) {
267  if (engine->hasIdentifier(connectionConfig.identifier())) {
268  d = engine->createSessionBackend();
269  d->q = this;
270  d->publicConfig = connectionConfig;
272  connect(d, SIGNAL(quitPendingWaitsForOpened()), this, SIGNAL(opened()));
277  connect(d, SIGNAL(closed()), this, SIGNAL(closed()));
282  break;
283  }
284  }
285  }
286 
287  qRegisterMetaType<QNetworkSession::State>();
288  qRegisterMetaType<QNetworkSession::SessionError>();
289 }
virtual void syncStateWithInterface()=0
QNetworkSessionPrivate * d
void stateChanged(QNetworkSession::State)
This signal is emitted whenever the state of the network session changes.
State
This enum describes the connectivity state of the session.
void opened()
This signal is emitted when the network session has been opened.
SessionError error() const
Returns the type of error that last occurred.
virtual QNetworkSessionPrivate * createSessionBackend()=0
#define SIGNAL(a)
Definition: qobjectdefs.h:227
SessionError
This enum describes the session errors that can occur.
The QNetworkConfiguration class provides an abstraction of one or more access point configurations...
void preferredConfigurationChanged(const QNetworkConfiguration &config, bool isSeamless)
This signal is emitted when the preferred configuration/access point for the session changes...
static bool connect(const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
Creates a connection of the given type from the signal in the sender object to the method in the rece...
Definition: qobject.cpp:2580
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
QNetworkConfigurationManagerPrivate * qNetworkConfigurationManagerPrivate()
QNetworkConfiguration publicConfig
QString identifier() const
Returns the unique and platform specific identifier for this network configuration; otherwise an empt...
Q_INVOKABLE QObject(QObject *parent=0)
Constructs an object with parent object parent.
Definition: qobject.cpp:753
virtual bool hasIdentifier(const QString &id)=0
QList< QBearerEngine * > engines() const
void closed()
This signal is emitted when the network session has been closed.
void newConfigurationActivated()
This signal is emitted once the session has roamed to the new access point.

◆ ~QNetworkSession()

QNetworkSession::~QNetworkSession ( )
virtual

Frees the resources associated with the QNetworkSession object.

Definition at line 294 of file qnetworksession.cpp.

295 {
296  delete d;
297 }
QNetworkSessionPrivate * d

Functions

◆ accept

void QNetworkSession::accept ( )
slot

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.

Definition at line 630 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

631 {
632  if (d)
633  d->accept();
634 }
QNetworkSessionPrivate * d
virtual void accept()=0

◆ activeTime()

quint64 QNetworkSession::activeTime ( ) const

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

Definition at line 691 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

692 {
693  return d ? d->activeTime() : Q_UINT64_C(0);
694 }
QNetworkSessionPrivate * d
virtual quint64 activeTime() const =0
#define Q_UINT64_C(c)
Definition: qglobal.h:941

◆ bytesReceived()

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.

Note
On some platforms this function may run the main event loop.

Definition at line 683 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

684 {
685  return d ? d->bytesReceived() : Q_UINT64_C(0);
686 }
QNetworkSessionPrivate * d
virtual quint64 bytesReceived() const =0
#define Q_UINT64_C(c)
Definition: qglobal.h:941

◆ bytesWritten()

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.

Note
On some platforms this function may run the main event loop.

Definition at line 664 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

665 {
666  return d ? d->bytesWritten() : Q_UINT64_C(0);
667 }
QNetworkSessionPrivate * d
virtual quint64 bytesWritten() const =0
#define Q_UINT64_C(c)
Definition: qglobal.h:941

◆ close

void QNetworkSession::close ( )
slot

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() or error() signals.

See also
open(), stop(), isOpen()

Definition at line 381 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::~QNetworkSessionPrivate().

382 {
383  if (d)
384  d->close();
385 }
QNetworkSessionPrivate * d
virtual void close()=0

◆ closed

void QNetworkSession::closed ( )
signal

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

Referenced by QNetworkSession(), and QNetworkSessionPrivate::setPrivateConfiguration().

◆ configuration()

QNetworkConfiguration QNetworkSession::configuration ( ) const

Returns the QNetworkConfiguration that this network session object is based on.

See also
QNetworkConfiguration

Definition at line 408 of file qnetworksession.cpp.

Referenced by QNetworkAccessManagerPrivate::_q_networkSessionClosed(), QNetworkAccessManager::configuration(), and QNetworkAccessBackend::start().

409 {
410  return d ? d->publicConfig : QNetworkConfiguration();
411 }
QNetworkSessionPrivate * d
The QNetworkConfiguration class provides an abstraction of one or more access point configurations...
QNetworkConfiguration publicConfig

◆ connectNotify()

void QNetworkSession::connectNotify ( const char *  signal)
protectedvirtual

This function is required to detect whether the client wants to control the roaming process.

Warning
This function is not part of the public interface.

If he connects to preferredConfigurationChanged() signal he intends to influence it. Otherwise QNetworkSession always roams without registering this session as a stakeholder in the roaming process.

For more details check the Forced vs ALR roaming section in the QNetworkSession class description.

Reimplemented from QObject.

Definition at line 710 of file qnetworksession.cpp.

711 {
712  QObject::connectNotify(signal);
713 
714  if (!d)
715  return;
716 
717  //check for preferredConfigurationChanged() signal connect notification
718  //This is not required on all platforms
720  d->setALREnabled(true);
721 }
QNetworkSessionPrivate * d
virtual void connectNotify(const char *signal)
This virtual function is called when something has been connected to signal in this object...
Definition: qobject.cpp:3142
virtual void setALREnabled(bool)
#define SIGNAL(a)
Definition: qobjectdefs.h:227
The QNetworkConfiguration class provides an abstraction of one or more access point configurations...
void preferredConfigurationChanged(const QNetworkConfiguration &config, bool isSeamless)
This signal is emitted when the preferred configuration/access point for the session changes...
int qstrcmp(const QByteArray &str1, const char *str2)
Definition: qbytearray.cpp:336

◆ disconnectNotify()

void QNetworkSession::disconnectNotify ( const char *  signal)
protectedvirtual

This function is called when the client disconnects from the preferredConfigurationChanged() signal.

Warning
This function is not part of the public interface.
See also
connectNotify()

Reimplemented from QObject.

Definition at line 734 of file qnetworksession.cpp.

735 {
737 
738  if (!d)
739  return;
740 
741  //check for preferredConfigurationChanged() signal disconnect notification
742  //This is not required on all platforms
744  d->setALREnabled(false);
745 }
QNetworkSessionPrivate * d
virtual void setALREnabled(bool)
#define SIGNAL(a)
Definition: qobjectdefs.h:227
The QNetworkConfiguration class provides an abstraction of one or more access point configurations...
void preferredConfigurationChanged(const QNetworkConfiguration &config, bool isSeamless)
This signal is emitted when the preferred configuration/access point for the session changes...
virtual void disconnectNotify(const char *signal)
This virtual function is called when something has been disconnected from signal in this object...
Definition: qobject.cpp:3162
int qstrcmp(const QByteArray &str1, const char *str2)
Definition: qbytearray.cpp:336

◆ error() [1/2]

QNetworkSession::SessionError QNetworkSession::error ( ) const

Returns the type of error that last occurred.

See also
state(), errorString()

Definition at line 470 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivateImpl::errorString(), open(), QNetworkSession(), and waitForOpened().

471 {
472  return d ? d->error() : InvalidConfigurationError;
473 }
QNetworkSessionPrivate * d
virtual QNetworkSession::SessionError error() const =0

◆ error [2/2]

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

This signal is emitted after an error occurred.

The error parameter describes the error that occurred.

See also
error(), errorString()

◆ errorString()

QString QNetworkSession::errorString ( ) const

Returns a human-readable description of the last device error that occurred.

See also
error()

Definition at line 481 of file qnetworksession.cpp.

482 {
483  return d ? d->errorString() : tr("Invalid configuration.");
484 }
QNetworkSessionPrivate * d
static QString tr(const char *sourceText, const char *comment=0, int n=-1)
virtual QString errorString() const =0

◆ ignore

void QNetworkSession::ignore ( )
slot

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

See also
migrate()

Definition at line 614 of file qnetworksession.cpp.

615 {
616  // Needed on at least Symbian platform: the roaming must be explicitly
617  // ignore()'d or migrate()'d
618  if (d)
619  d->ignore();
620 }
QNetworkSessionPrivate * d
virtual void ignore()=0

◆ interface()

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.

Note: this function does not work in Symbian emulator due to the way the connectivity is emulated on Windows.

See also
state()

Definition at line 426 of file qnetworksession.cpp.

427 {
428  return d ? d->currentInterface() : QNetworkInterface();
429 }
virtual QNetworkInterface currentInterface() const =0
QNetworkSessionPrivate * d
The QNetworkInterface class provides a listing of the host&#39;s IP addresses and network interfaces...

◆ isOpen()

bool QNetworkSession::isOpen ( ) const

Returns 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() and close().

Definition at line 438 of file qnetworksession.cpp.

439 {
440  return d ? d->isOpen : false;
441 }
QNetworkSessionPrivate * d

◆ migrate

void QNetworkSession::migrate ( )
slot

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.

See also
accept()

Definition at line 603 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

604 {
605  if (d)
606  d->migrate();
607 }
QNetworkSessionPrivate * d
virtual void migrate()=0

◆ newConfigurationActivated

void QNetworkSession::newConfigurationActivated ( )
signal

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() or reject() the new access point.

See also
accept(), reject()

Referenced by QNetworkSession(), and QNetworkSessionPrivate::setPrivateConfiguration().

◆ open

void QNetworkSession::open ( )
slot

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() or error() signals.

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

See also
close(), stop(), isOpen()

Definition at line 316 of file qnetworksession.cpp.

317 {
318  if (d)
319  d->open();
320  else
322 }
QNetworkSessionPrivate * d
SessionError error() const
Returns the type of error that last occurred.
virtual void open()=0
#define emit
Definition: qobjectdefs.h:76

◆ opened

void QNetworkSession::opened ( )
signal

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.

Referenced by QNetworkSession().

◆ preferredConfigurationChanged

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

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.

See also
migrate(), ignore(), QNetworkConfiguration::isRoamingAvailable()

Referenced by connectNotify(), disconnectNotify(), QNetworkSession(), and QNetworkSessionPrivate::setPrivateConfiguration().

◆ reject

void QNetworkSession::reject ( )
slot

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.

See also
accept()

Definition at line 643 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::setALREnabled().

644 {
645  if (d)
646  d->reject();
647 }
QNetworkSessionPrivate * d
virtual void reject()=0

◆ sessionProperty()

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:

Key Description
ActiveConfiguration

If the session isOpen() this property returns the identifier of the QNetworkConfiguration that is used by this session; otherwise an empty string.

The main purpose of this key is to determine which Internet access point is used if the session is based on a ServiceNetwork. The following code snippet highlights the difference:

QNetworkSession *session = new QNetworkSession(ap);
... //code activates session
QString ident = session->sessionProperty("ActiveConfiguration").toString();
Q_ASSERT( ap.identifier() != ident );
Q_ASSERT( ap.children().contains( mgr.configurationFromIdentifier(ident) ) );
Q_ASSERT( ap.identifier() == ident );
}
UserChoiceConfiguration

If the session isOpen() and is bound to a QNetworkConfiguration of type UserChoice, this property returns the identifier of the QNetworkConfiguration that the configuration resolved to when open() was called; otherwise an empty string.

The purpose of this key is to determine the real QNetworkConfiguration that the session is using. This key is different from ActiveConfiguration in that this key may return an identifier for either a QNetworkConfiguration::ServiceNetwork{service network} or a QNetworkConfiguration::InternetAccessPoint{Internet access points} configurations, whereas ActiveConfiguration always returns identifiers to QNetworkConfiguration::InternetAccessPoint{Internet access points} configurations.

ConnectInBackground

Setting this property to true before calling open() implies that the connection attempt is made but if no connection can be established, the user is not connsulted and asked to select a suitable connection. This property is not set by default and support for it depends on the platform.

AutoCloseSessionTimeout

If the session requires polling to keep its state up to date, this property holds the timeout in milliseconds before the session will automatically close. If the value of this property is -1 the session will not automatically close. This property is set to -1 by default.

The purpose of this property is to minimize resource use on platforms that use polling to update the state of the session. Applications can set the value of this property to the desired timeout before the session is closed. In response to the closed() signal the network session should be deleted to ensure that all polling is stopped. The session can then be recreated once it is required again. This property has no effect for sessions that do not require polling.

Definition at line 553 of file qnetworksession.cpp.

Referenced by QNetworkAccessBackend::start(), and QNetworkSessionPrivate::~QNetworkSessionPrivate().

554 {
555  if (!d || !d->publicConfig.isValid())
556  return QVariant();
557 
558  if (key == QLatin1String("ActiveConfiguration"))
559  return d->isOpen ? d->activeConfig.identifier() : QString();
560 
561  if (key == QLatin1String("UserChoiceConfiguration")) {
563  return QString();
564 
565  if (d->serviceConfig.isValid())
566  return d->serviceConfig.identifier();
567  else
568  return d->activeConfig.identifier();
569  }
570 
571  return d->sessionProperty(key);
572 }
The QVariant class acts like a union for the most common Qt data types.
Definition: qvariant.h:92
QNetworkSessionPrivate * d
QNetworkConfiguration serviceConfig
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
The QString class provides a Unicode character string.
Definition: qstring.h:83
virtual QVariant sessionProperty(const QString &key) const =0
QNetworkConfiguration activeConfig
bool isValid() const
Returns true if this QNetworkConfiguration object is valid.
QNetworkConfiguration publicConfig
QString identifier() const
Returns the unique and platform specific identifier for this network configuration; otherwise an empt...
Type type() const
Returns the type of the configuration.

◆ setSessionProperty()

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

Sets the property value on the session.

The property is identified using key. Removing an already set property can be achieved by passing an invalid QVariant.

Note that the UserChoiceConfiguration and ActiveConfiguration properties are read only and cannot be changed using this method.

Definition at line 582 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::~QNetworkSessionPrivate().

583 {
584  if (!d)
585  return;
586 
587  if (key == QLatin1String("ActiveConfiguration") ||
588  key == QLatin1String("UserChoiceConfiguration")) {
589  return;
590  }
591 
592  d->setSessionProperty(key, value);
593 }
QNetworkSessionPrivate * d
QLatin1String(DBUS_INTERFACE_DBUS))) Q_GLOBAL_STATIC_WITH_ARGS(QString
virtual void setSessionProperty(const QString &key, const QVariant &value)=0

◆ state()

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 QNetworkConfiguration::children(){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.

See also
error(), stateChanged()

Definition at line 460 of file qnetworksession.cpp.

Referenced by QNetworkReplyImplPrivate::_q_networkSessionConnected(), and QNetworkSessionPrivate::setPrivateConfiguration().

461 {
462  return d ? d->state : QNetworkSession::Invalid;
463 }
QNetworkSessionPrivate * d
QNetworkSession::State state

◆ stateChanged

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

This signal is emitted whenever the state of the network session changes.

The state parameter is the new state.

See also
state()

Referenced by QNetworkSession(), and QNetworkSessionPrivate::setPrivateConfiguration().

◆ stop

void QNetworkSession::stop ( )
slot

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 .

On Symbian platform, a 'NetworkControl' capability is required for full interface-level stop (without the capability, only the current session is stopped).

See also
open(), close()

Definition at line 397 of file qnetworksession.cpp.

Referenced by QNetworkSessionPrivate::~QNetworkSessionPrivate().

398 {
399  if (d)
400  d->stop();
401 }
virtual void stop()=0
QNetworkSessionPrivate * d

◆ waitForOpened()

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; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

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

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

If msecs is -1, this function will not time out.

See also
open(), error()

Definition at line 341 of file qnetworksession.cpp.

342 {
343  if (!d)
344  return false;
345 
346  if (d->isOpen)
347  return true;
348 
349  if (!(d->state == Connecting || d->state == Connected)) {
350  return false;
351  }
352 
353  QEventLoop loop;
354  QObject::connect(d, SIGNAL(quitPendingWaitsForOpened()), &loop, SLOT(quit()));
356 
357  //final call
358  if (msecs >= 0)
359  QTimer::singleShot(msecs, &loop, SLOT(quit()));
360 
361  // enter the event loop and wait for opened/error/timeout
363 
364  return d->isOpen;
365 }
#define SLOT(a)
Definition: qobjectdefs.h:226
QNetworkSessionPrivate * d
SessionError error() const
Returns the type of error that last occurred.
#define SIGNAL(a)
Definition: qobjectdefs.h:227
SessionError
This enum describes the session errors that can occur.
The QEventLoop class provides a means of entering and leaving an event loop.
Definition: qeventloop.h:55
static bool connect(const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
Creates a connection of the given type from the signal in the sender object to the method in the rece...
Definition: qobject.cpp:2580
QNetworkSession::State state
bool singleShot
This static function calls a slot after a given time interval.
Definition: qtimer.h:59
int exec(ProcessEventsFlags flags=AllEvents)
Enters the main event loop and waits until exit() is called.
Definition: qeventloop.cpp:181

Friends and Related Functions

◆ QNetworkSessionPrivate

Definition at line 139 of file qnetworksession.h.

Properties

◆ d

QNetworkSessionPrivate* QNetworkSession::d
private

The documentation for this class was generated from the following files: