<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QNetworkSession Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QNetworkSession Class Reference<br /><sup><sup>[<a href="qtnetwork.html">QtNetwork</a> module]</sup></sup></h1><p>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 href="#details">More...</a></p>
<p>Inherits <a href="qobject.html">QObject</a>.</p><h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qnetworksession.html#SessionError-enum">SessionError</a></b> { UnknownSessionError, SessionAbortedError, RoamingError, OperationNotSupportedError, InvalidConfigurationError }</li><li><div class="fn" />enum <b><a href="qnetworksession.html#State-enum">State</a></b> { Invalid, NotAvailable, Connecting, Connected, ..., Roaming }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qnetworksession.html#QNetworkSession">__init__</a></b> (<i>self</i>, QNetworkConfiguration <i>connConfig</i>, QObject <i>parent</i> = None)</li><li><div class="fn" /><b><a href="qnetworksession.html#accept">accept</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qnetworksession.html#activeTime">activeTime</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qnetworksession.html#bytesReceived">bytesReceived</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qnetworksession.html#bytesWritten">bytesWritten</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#close">close</a></b> (<i>self</i>)</li><li><div class="fn" />QNetworkConfiguration <b><a href="qnetworksession.html#configuration">configuration</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#connectNotify">connectNotify</a></b> (<i>self</i>, SIGNAL() <i>signal</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#disconnectNotify">disconnectNotify</a></b> (<i>self</i>, SIGNAL() <i>signal</i>)</li><li><div class="fn" />SessionError <b><a href="qnetworksession.html#error">error</a></b> (<i>self</i>)</li><li><div class="fn" />QString <b><a href="qnetworksession.html#errorString">errorString</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#ignore">ignore</a></b> (<i>self</i>)</li><li><div class="fn" />QNetworkInterface <b><a href="qnetworksession.html#interface">interface</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qnetworksession.html#isOpen">isOpen</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#migrate">migrate</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#open">open</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#reject">reject</a></b> (<i>self</i>)</li><li><div class="fn" />QVariant <b><a href="qnetworksession.html#sessionProperty">sessionProperty</a></b> (<i>self</i>, QString <i>key</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#setSessionProperty">setSessionProperty</a></b> (<i>self</i>, QString <i>key</i>, QVariant <i>value</i>)</li><li><div class="fn" />State <b><a href="qnetworksession.html#state">state</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qnetworksession.html#stop">stop</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qnetworksession.html#waitForOpened">waitForOpened</a></b> (<i>self</i>, int <i>msecs</i> = 30000)</li></ul><h3>Qt Signals</h3><ul><li><div class="fn" />void <b><a href="qnetworksession.html#closed">closed</a></b> ()</li><li><div class="fn" />void <b><a href="qnetworksession.html#error-2">error</a></b> (QNetworkSession::SessionError)</li><li><div class="fn" />void <b><a href="qnetworksession.html#newConfigurationActivated">newConfigurationActivated</a></b> ()</li><li><div class="fn" />void <b><a href="qnetworksession.html#opened">opened</a></b> ()</li><li><div class="fn" />void <b><a href="qnetworksession.html#preferredConfigurationChanged">preferredConfigurationChanged</a></b> (const QNetworkConfiguration&,bool)</li><li><div class="fn" />void <b><a href="qnetworksession.html#stateChanged">stateChanged</a></b> (QNetworkSession::State)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>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.</p>
<p>A QNetworkSession enables control over the system's network
interfaces. The session's configuration parameter are determined
via the <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> 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 <a href="qnetworksession.html#open">opening</a> and <a href="qnetworksession.html#close">closing</a> of network sessions a
developer can start and stop the systems network interfaces. If the
configuration represents multiple access points (see <a href="qnetworkconfiguration.html#Type-enum">QNetworkConfiguration.ServiceNetwork</a>)
more advanced features such as roaming may be supported.</p>
<p>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.</p>
<a id="roaming" name="roaming" />
<h3>Roaming</h3>
<p>Applications may connect to the <a href="qnetworksession.html#preferredConfigurationChanged">preferredConfigurationChanged</a>()
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 <a href="qnetworksession.html#migrate">migrate</a>() or <a href="qnetworksession.html#ignore">ignore</a>() the new access point.
Once the session has roamed the <a href="qnetworksession.html#newConfigurationActivated">newConfigurationActivated</a>()
signal is emitted. The application may now test the carrier and
must either <a href="qnetworksession.html#accept">accept</a>() or
<a href="qnetworksession.html#reject">reject</a>() it. The session
will return to the previous access point if the roaming was
rejected. The subsequent state diagram depicts the required state
transitions.</p>
<p class="centerAlign"><img alt="" src="images/roaming-states.png" /></p>
<p>Some platforms may distinguish forced roaming and application
level roaming (ALR). ALR implies that the application controls (via
<a href="qnetworksession.html#migrate">migrate</a>(), <a href="qnetworksession.html#ignore">ignore</a>(), <a href="qnetworksession.html#accept">accept</a>() and <a href="qnetworksession.html#reject">reject</a>()) 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.</p>
<p>If the platform supports both modes of roaming, an application
indicates its preference by connecting to the <a href="qnetworksession.html#preferredConfigurationChanged">preferredConfigurationChanged</a>()
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
<a href="qnetworksession.html#preferredConfigurationChanged">preferredConfigurationChanged</a>(),
forced roaming is used. If forced roaming is not supported the
network session will not roam by default.</p>
<p>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 <a href="qnetworksession.html#preferredConfigurationChanged">preferredConfigurationChanged</a>()
signal and answer each signal emission with <a href="qnetworksession.html#ignore">ignore</a>().</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="SessionError-enum" />QNetworkSession.SessionError</h3><p>This enum describes the session errors that can occur.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign">
<tt>QNetworkSession.UnknownSessionError</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">An unidentified error occurred.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QNetworkSession.SessionAbortedError</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The session was aborted by the user or
system.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.RoamingError</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The session cannot roam to a new
configuration.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QNetworkSession.OperationNotSupportedError</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">The operation is not supported for current
configuration.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QNetworkSession.InvalidConfigurationError</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">The operation cannot currently be performed
for the current configuration.</td>
</tr>
</table>
<h3 class="fn"><a name="State-enum" />QNetworkSession.State</h3><p>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.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Invalid</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">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.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.NotAvailable</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The session is based on a defined but not yet
discovered <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> (see
<a href="qnetworkconfiguration.html#StateFlag-enum">QNetworkConfiguration.StateFlag</a>).</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Connecting</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The network session is being established.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Connected</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">The network session is connected. If the
current process wishes to use this session it has to register its
interest by calling <a href="qnetworksession.html#open">open</a>().
A network session is considered to be ready for socket operations
if it <a href="qnetworksession.html#isOpen">isOpen</a>() and
connected.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Closing</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">The network session is in the process of being
shut down.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Disconnected</tt></td>
<td class="topAlign"><tt>5</tt></td>
<td class="topAlign">The network session is not connected. The
associated <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> has the
state <a href="qnetworkconfiguration.html#StateFlag-enum">QNetworkConfiguration.Discovered</a>.</td>
</tr>
<tr>
<td class="topAlign"><tt>QNetworkSession.Roaming</tt></td>
<td class="topAlign"><tt>6</tt></td>
<td class="topAlign">The network session is roaming from one access
point to another access point.</td>
</tr>
</table>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QNetworkSession" />QNetworkSession.__init__ (<i>self</i>, <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> <i>connConfig</i>, <a href="qobject.html">QObject</a> <i>parent</i> = None)</h3><p>The <i>parent</i> argument, if not None, causes <i>self</i> to be owned by Qt instead of PyQt.</p><p>Constructs a session based on <i>connectionConfig</i> with the
given <i>parent</i>.</p>
<p><b>See also</b> <a href="qnetworkconfiguration.html">QNetworkConfiguration</a>.</p>
<h3 class="fn"><a name="accept" />QNetworkSession.accept (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void accept()</tt>.</p><p>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.</p>
<p>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.</p>
<h3 class="fn"><a name="activeTime" />int QNetworkSession.activeTime (<i>self</i>)</h3><p>Returns the number of seconds that the session has been
active.</p>
<h3 class="fn"><a name="bytesReceived" />int QNetworkSession.bytesReceived (<i>self</i>)</h3><p>Returns the amount of data received in bytes; otherwise 0.</p>
<p>This field value includes the usage across all open network
sessions which use the same network interface.</p>
<p>If the session is based on a service network configuration the
number of sent bytes across all active member configurations are
returned.</p>
<p>This function may not always be supported on all platforms and
returns 0. The platform capability can be detected via <a href="qnetworkconfigurationmanager.html#Capability-enum">QNetworkConfigurationManager.DataStatistics</a>.</p>
<p><b>Note:</b> On some platforms this function may run the main
event loop.</p>
<h3 class="fn"><a name="bytesWritten" />int QNetworkSession.bytesWritten (<i>self</i>)</h3><p>Returns the amount of data sent in bytes; otherwise 0.</p>
<p>This field value includes the usage across all open network
sessions which use the same network interface.</p>
<p>If the session is based on a service network configuration the
number of sent bytes across all active member configurations are
returned.</p>
<p>This function may not always be supported on all platforms and
returns 0. The platform capability can be detected via <a href="qnetworkconfigurationmanager.html#Capability-enum">QNetworkConfigurationManager.DataStatistics</a>.</p>
<p><b>Note:</b> On some platforms this function may run the main
event loop.</p>
<h3 class="fn"><a name="close" />QNetworkSession.close (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void close()</tt>.</p><p>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 <a href="qnetworksession.html#state">state</a>() will only change from
<a href="qnetworksession.html#State-enum">Connected</a> to <a href="qnetworksession.html#State-enum">Disconnected</a> if the current
session was the last open session.</p>
<p>If the platform does not support out-of-process sessions calling
this function does not stop the interface. In this case <a href="qnetworksession.html#stop">stop</a>() has to be used to force a
shut down. The platform capabilities can be detected via <a href="qnetworkconfigurationmanager.html#capabilities">QNetworkConfigurationManager.capabilities</a>().</p>
<p>Note that this call is asynchronous. Depending on the outcome of
this call the results can be enquired by connecting to the <a href="qnetworksession.html#stateChanged">stateChanged</a>(), <a href="qnetworksession.html#opened">opened</a>() or <a href="qnetworksession.html#error">error</a>() signals.</p>
<p><b>See also</b> <a href="qnetworksession.html#open">open</a>(),
<a href="qnetworksession.html#stop">stop</a>(), and <a href="qnetworksession.html#isOpen">isOpen</a>().</p>
<h3 class="fn"><a name="configuration" /><a href="qnetworkconfiguration.html">QNetworkConfiguration</a> QNetworkSession.configuration (<i>self</i>)</h3><p>Returns the <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> that this
network session object is based on.</p>
<p><b>See also</b> <a href="qnetworkconfiguration.html">QNetworkConfiguration</a>.</p>
<h3 class="fn"><a name="connectNotify" />QNetworkSession.connectNotify (<i>self</i>, SIGNAL() <i>signal</i>)</h3><h3 class="fn"><a name="disconnectNotify" />QNetworkSession.disconnectNotify (<i>self</i>, SIGNAL() <i>signal</i>)</h3><h3 class="fn"><a name="error" /><a href="qnetworksession.html#SessionError-enum">SessionError</a> QNetworkSession.error (<i>self</i>)</h3><p>Returns the type of error that last occurred.</p>
<p><b>See also</b> <a href="qnetworksession.html#state">state</a>()
and <a href="qnetworksession.html#errorString">errorString</a>().</p>
<h3 class="fn"><a name="errorString" />QString QNetworkSession.errorString (<i>self</i>)</h3><p>Returns a human-readable description of the last device error
that occurred.</p>
<p><b>See also</b> <a href="qnetworksession.html#error">error</a>().</p>
<h3 class="fn"><a name="ignore" />QNetworkSession.ignore (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void ignore()</tt>.</p><p>This function indicates that the application does not wish to
roam the session.</p>
<p><b>See also</b> <a href="qnetworksession.html#migrate">migrate</a>().</p>
<h3 class="fn"><a name="interface" /><a href="qnetworkinterface.html">QNetworkInterface</a> QNetworkSession.interface (<i>self</i>)</h3><p>Returns the network interface that is used by this session.</p>
<p>This function only returns a valid <a href="qnetworkinterface.html">QNetworkInterface</a> when this session is
<a href="qnetworksession.html#State-enum">Connected</a>.</p>
<p>The returned interface may change as a result of a roaming
process.</p>
<p>Note: this function does not work in Symbian emulator due to the
way the connectivity is emulated on Windows.</p>
<p><b>See also</b> <a href="qnetworksession.html#state">state</a>().</p>
<h3 class="fn"><a name="isOpen" />bool QNetworkSession.isOpen (<i>self</i>)</h3><p>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.</p>
<p>The session can be controlled via <a href="qnetworksession.html#open">open</a>() and <a href="qnetworksession.html#close">close</a>().</p>
<h3 class="fn"><a name="migrate" />QNetworkSession.migrate (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void migrate()</tt>.</p><p>Instructs the session to roam to the new access point. The old
access point remains active until the application calls <a href="qnetworksession.html#accept">accept</a>().</p>
<p>The <a href="qnetworksession.html#newConfigurationActivated">newConfigurationActivated</a>()
signal is emitted once roaming has been completed.</p>
<p><b>See also</b> <a href="qnetworksession.html#accept">accept</a>().</p>
<h3 class="fn"><a name="open" />QNetworkSession.open (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void open()</tt>.</p><p>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.</p>
<p>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 <a href="qnetworkconfigurationmanager.html#capabilities">QNetworkConfigurationManager.capabilities</a>().</p>
<p>Note that this call is asynchronous. Depending on the outcome of
this call the results can be enquired by connecting to the <a href="qnetworksession.html#stateChanged">stateChanged</a>(), <a href="qnetworksession.html#opened">opened</a>() or <a href="qnetworksession.html#error">error</a>() signals.</p>
<p>It is not a requirement to open a session in order to monitor
the underlying network interface.</p>
<p><b>See also</b> <a href="qnetworksession.html#close">close</a>(), <a href="qnetworksession.html#stop">stop</a>(), and <a href="qnetworksession.html#isOpen">isOpen</a>().</p>
<h3 class="fn"><a name="reject" />QNetworkSession.reject (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void reject()</tt>.</p><p>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.</p>
<p><b>See also</b> <a href="qnetworksession.html#accept">accept</a>().</p>
<h3 class="fn"><a name="sessionProperty" />QVariant QNetworkSession.sessionProperty (<i>self</i>, QString <i>key</i>)</h3><p>Returns the value for property <i>key</i>.</p>
<p>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.</p>
<p>The following property keys are guaranteed to be specified on
all platforms:</p>
<table class="generic">
<thead>
<tr class="qt-style">
<th>Key</th>
<th>Description</th>
</tr>
</thead>
<tr class="odd" valign="top">
<td>ActiveConfiguration</td>
<td>If the session <a href="qnetworksession.html#isOpen">isOpen</a>() this property returns
the identifier of the <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> that is used
by this session; otherwise an empty string.
<p>The main purpose of this key is to determine which Internet
access point is used if the session is based on a <a href="qnetworkconfiguration.html#Type-enum">ServiceNetwork</a>. The
following code snippet highlights the difference:</p>
<pre class="cpp">
<span class="type"><a href="qnetworkconfigurationmanager.html">QNetworkConfigurationManager</a></span> mgr;
<span class="type"><a href="qnetworkconfiguration.html">QNetworkConfiguration</a></span> ap <span class="operator">=</span> mgr<span class="operator">.</span>defaultConfiguration();
<span class="type"><a href="qnetworksession.html">QNetworkSession</a></span> <span class="operator">*</span>session <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qnetworksession.html">QNetworkSession</a></span>(ap);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> <span class="comment">//code activates session</span>
<span class="type"><a href="qstring.html">QString</a></span> ident <span class="operator">=</span> session<span class="operator">-</span><span class="operator">></span>sessionProperty(<span class="string">"ActiveConfiguration"</span>)<span class="operator">.</span>toString();
<span class="keyword">if</span> ( ap<span class="operator">.</span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qnetworkconfiguration.html">QNetworkConfiguration</a></span><span class="operator">.</span>ServiceNetwork ) {
Q_ASSERT( ap<span class="operator">.</span>identifier() <span class="operator">!</span><span class="operator">=</span> ident );
Q_ASSERT( ap<span class="operator">.</span>children()<span class="operator">.</span>contains( mgr<span class="operator">.</span>configurationFromIdentifier(ident) ) );
} <span class="keyword">else</span> <span class="keyword">if</span> ( ap<span class="operator">.</span>type() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qnetworkconfiguration.html">QNetworkConfiguration</a></span><span class="operator">.</span>InternetAccessPoint ) {
Q_ASSERT( ap<span class="operator">.</span>identifier() <span class="operator">=</span><span class="operator">=</span> ident );
}
</pre></td>
</tr>
<tr class="even" valign="top">
<td>UserChoiceConfiguration</td>
<td>If the session <a href="qnetworksession.html#isOpen">isOpen</a>() and is bound to a
<a href="qnetworkconfiguration.html">QNetworkConfiguration</a> of
type UserChoice, this property returns the identifier of the
<a href="qnetworkconfiguration.html">QNetworkConfiguration</a> that
the configuration resolved to when <a href="qnetworksession.html#open">open</a>() was called; otherwise an
empty string.
<p>The purpose of this key is to determine the real <a href="qnetworkconfiguration.html">QNetworkConfiguration</a> that the
session is using. This key is different from
<i>ActiveConfiguration</i> in that this key may return an
identifier for either a <a href="qnetworkconfiguration.html#Type-enum">service network</a> or a
<a href="qnetworkconfiguration.html#Type-enum">Internet access
points</a> configurations, whereas <i>ActiveConfiguration</i>
always returns identifiers to <a href="qnetworkconfiguration.html#Type-enum">Internet access points</a>
configurations.</p>
</td>
</tr>
<tr class="odd" valign="top">
<td>ConnectInBackground</td>
<td>Setting this property to <i>true</i> before calling <a href="qnetworksession.html#open">open</a>() 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.</td>
</tr>
<tr class="even" valign="top">
<td>AutoCloseSessionTimeout</td>
<td>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.
<p>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 <a href="qnetworksession.html#closed">closed</a>() 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.</p>
</td>
</tr>
</table>
<p><b>See also</b> <a href="qnetworksession.html#setSessionProperty">setSessionProperty</a>().</p>
<h3 class="fn"><a name="setSessionProperty" />QNetworkSession.setSessionProperty (<i>self</i>, QString <i>key</i>, QVariant <i>value</i>)</h3><p>Sets the property <i>value</i> on the session. The property is
identified using <i>key</i>. Removing an already set property can
be achieved by passing an invalid <a href="qvariant.html">QVariant</a>.</p>
<p>Note that the <i>UserChoiceConfiguration</i> and
<i>ActiveConfiguration</i> properties are read only and cannot be
changed using this method.</p>
<p><b>See also</b> <a href="qnetworksession.html#sessionProperty">sessionProperty</a>().</p>
<h3 class="fn"><a name="state" /><a href="qnetworksession.html#State-enum">State</a> QNetworkSession.state (<i>self</i>)</h3><p>Returns the state of the session.</p>
<p>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.</p>
<p>A <a href="qnetworkconfiguration.html#Type-enum">QNetworkConfiguration.ServiceNetwork</a>
based session summarizes the state of all its children and
therefore returns the <a href="qnetworksession.html#State-enum">Connected</a> state if at least
one of the service network's <a href="qnetworkconfiguration.html#children">children()</a> configurations
is active.</p>
<p>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.</p>
<p><b>See also</b> <a href="qnetworksession.html#error">error</a>()
and <a href="qnetworksession.html#stateChanged">stateChanged</a>().</p>
<h3 class="fn"><a name="stop" />QNetworkSession.stop (<i>self</i>)</h3><p>This method is also a Qt slot with the C++ signature <tt>void stop()</tt>.</p><p>Invalidates all open sessions against the network interface and
therefore stops the underlying network interface. This function
always changes the session's <a href="qnetworksession.html#state">state</a>() flag to <a href="qnetworksession.html#State-enum">Disconnected</a>.</p>
<p>On Symbian platform, a 'NetworkControl' capability is required
for full interface-level stop (without the capability, only the
current session is stopped).</p>
<p><b>See also</b> <a href="qnetworksession.html#open">open</a>()
and <a href="qnetworksession.html#close">close</a>().</p>
<h3 class="fn"><a name="waitForOpened" />bool QNetworkSession.waitForOpened (<i>self</i>, int <i>msecs</i> = 30000)</h3><p>Waits until the session has been opened, up to <i>msecs</i>
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 <a href="qnetworksession.html#error">error</a>() to determine the cause of
the error.</p>
<p>The following example waits up to one second for the session to
be opened:</p>
<pre class="cpp">
session<span class="operator">-</span><span class="operator">></span><a href="qnetworksession.html#open">open</a>();
<span class="keyword">if</span> (session<span class="operator">-</span><span class="operator">></span>waitForOpened(<span class="number">1000</span>))
<a href="qtcore.html#qDebug">qDebug</a>(<span class="string">"Open!"</span>);
</pre>
<p>If <i>msecs</i> is -1, this function will not time out.</p>
<p><b>See also</b> <a href="qnetworksession.html#open">open</a>()
and <a href="qnetworksession.html#error">error</a>().</p>
<hr /><h2>Qt Signal Documentation</h2><h3 class="fn"><a name="closed" />void closed ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the network session has been
closed.</p>
<h3 class="fn"><a name="error-2" />void error (QNetworkSession::SessionError)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted after an error occurred. The <i>error</i>
parameter describes the error that occurred.</p>
<p><b>See also</b> <a href="qnetworksession.html#error">error</a>()
and <a href="qnetworksession.html#errorString">errorString</a>().</p>
<h3 class="fn"><a name="newConfigurationActivated" />void newConfigurationActivated ()</h3><p>This is the default overload of this signal.</p><p>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
<a href="qnetworksession.html#accept">accept</a>() or <a href="qnetworksession.html#reject">reject</a>() the new access
point.</p>
<p><b>See also</b> <a href="qnetworksession.html#accept">accept</a>() and <a href="qnetworksession.html#reject">reject</a>().</p>
<h3 class="fn"><a name="opened" />void opened ()</h3><p>This is the default overload of this signal.</p><p>This signal is emitted when the network session has been
opened.</p>
<p>The underlying network interface will not be shut down as long
as the session remains open. Note that this feature is dependent on
<a href="qnetworkconfigurationmanager.html#Capability-enum">system
wide session support</a>.</p>
<h3 class="fn"><a name="preferredConfigurationChanged" />void preferredConfigurationChanged (const QNetworkConfiguration&,bool)</h3><p>This is the default overload of this signal.</p><p>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. <i>config</i>
can be used to determine access point specific details such as
proxy settings and <i>isSeamless</i> indicates whether roaming will
break the sessions IP address.</p>
<p>As a consequence to this signal the application must either
start the roaming process by calling <a href="qnetworksession.html#migrate">migrate</a>() or choose to <a href="qnetworksession.html#ignore">ignore</a>() the new access
point.</p>
<p>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.</p>
<p>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.</p>
<p><b>See also</b> <a href="qnetworksession.html#migrate">migrate</a>(), <a href="qnetworksession.html#ignore">ignore</a>(), and <a href="qnetworkconfiguration.html#isRoamingAvailable">QNetworkConfiguration.isRoamingAvailable</a>().</p>
<h3 class="fn"><a name="stateChanged" />void stateChanged (QNetworkSession::State)</h3><p>This is the default overload of this signal.</p><p>This signal is emitted whenever the state of the network session
changes. The <i>state</i> parameter is the new state.</p>
<p><b>See also</b> <a href="qnetworksession.html#state">state</a>().</p>
<address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
