QtopiaNetwork Class Reference
[QtBaseModule]

Detailed Description

The QtopiaNetwork class provides functions for starting/stopping of network devices/interfaces.

In general it allows the managing of existing network configurations. The management functions include the starting and stopping of interfaces and other functions which may be useful for applications which want to influence the connectivity state of Qtopia.

The QtopiaNetworkServer synchronizes network interface operations across all Qt Extended applications. Client applications can request network operations via the static methods provided by this class. The following functions are thin wrapper functions encapsulating IPC calls to the QtopiaNetworkServer which then acts on behalf of the caller:

• startInterface()
• stopInterface()
• setDefaultGateway()
• unsetDefaultGateway()
• shutdown()

The second set of static functions relates to the management of network configuration files. By default Qt Extended saves network configurations in the directory returned by settingsDir(). Network interfaces are identified via a handle which is the absolute path and name of the network configuration file containing the parameters for that interface. The network server will choose and load the appropriate network plug-in based on the configuration handle. QNetworkState::deviceType() can be used to determine the type of a network handle. In order to obtain a list of network handles of a particular type availableNetworkConfigs() should be used.

loadPlugin() finds and loads the Qt Extended network plug-in that is suitable for a given network handle. However to avoid multiple access to the same network interface the returned QtopiaNetworkInterface instance should be carefully managed. The most common reason for instanciating a QtopiaNetworkInterface from outside of the network server would be the need to allow the user to configure the interface via QtopiaNetworkInterface::configuration(). The internet application would be an example for such a use case.

QtopiaNetwork only provides a minimum level of monitoring functionality via online(). If more detailed monitoring is required one of the following classes should be used:

• QNetworkState - very generic connectivity information related to Qtopia
• QNetworkDevice - specific information about the state of a particular hardware device
• QNetworkConnection - information beyond the device level such as the remote partner

See also QtopiaNetworkServer.

Member Type Documentation

enum QtopiaNetwork::TypeFlag
flags QtopiaNetwork::Type

This enum is used to describe the type of a network connection.

These sub types are used in conjunction with QtopiaNetwork::GPRS and QtopiaNetwork::Dialup only:

These sub types specify the type of the external device which is used to establish the connection.

These sub types are used in conjunction with QtopiaNetwork::Bluetooth only.

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

Member Function Documentation

QStringList QtopiaNetwork::availableNetworkConfigs ( QtopiaNetwork::Type type = QtopiaNetwork::Any, const QString & path = QString() )   [static]

Returns a list of all known Qt Extended network interface handles which match type. A handle uniquely identifies a Qt Extended network interfaces and is the absolute path to the configuration file that contains the settings for a particular QtopiaNetworkInterface. path specifies the directory where the lookup takes place.

Note that the lookup is independent of the state of an interface. It always returns all Qt Extended network interfaces which are online and offline.

If type is set to QtopiaNetwork::Any it returns all known NetworkInterfaces. If path is empty the lookup will take place in settingsDir().

QPointer<QtopiaNetworkInterface> QtopiaNetwork::loadPlugin ( const QString & handle )   [static]

Loads the appropriate network plug-in for the interface with handle; or 0 if no suitable plug-in can be found.

Only use this function if you intend to configure the returned QtopiaNetworkInterface via QtopiaNetworkInterface::configuration(). Any other use may trigger undesired behaviour whereby the loaded network interface instance may overshadow the instance created by the QtopiaNetworkServer. For more details see the QtopiaNetworkInterface general class documentation.

bool QtopiaNetwork::online ()   [static]

Returns true if any known network interface is online/connected. This can be used to check the general connectivity status of the Qt Extended environment. A device is considered to be online if it is in the state QtopiaNetwork::Up, QtopiaNetwork::Demand or QtopiaNetwork::Pending.

More detailed state updates on a per device base can be obtained by using QNetworkDevice and overal state change notifications across all network devices are provided by QNetworkState.

void QtopiaNetwork::setDefaultGateway ( const QString & handle )   [static]

The network interface identified by handle becomes the new default gateway. If the device is connected to more than one network at a time this can be used to choose a preferred network for data transfers.

QString QtopiaNetwork::settingsDir ()   [static]

Returns the default directory for network interface configurations; $HOME/Applications/Network/config.

void QtopiaNetwork::shutdown ()   [static]

Stops all active network interfaces.

void QtopiaNetwork::startInterface ( const QString & handle, const QVariant & options = QVariant() )   [static]

Starts that the network interface identified by handle. If the interface is running already this function does nothing.

options is used internally by some network plug-ins. It allows to specify additional parameters which are specific to particular network plug-ins. Otherwise this parameter can safely be ignored.

void QtopiaNetwork::stopInterface ( const QString & handle, bool deleteIface = false )   [static]

Stops the network interface identified by handle. If deleteIface is true the server will delete all configuration information associated to this interface.

void QtopiaNetwork::unsetDefaultGateway ( const QString & handle )   [static]

Qt Extended will set the default gateway to an interface that is not equal to handle. This is useful if handle goes offline and the caller doesn't care what interface should become the new default gateway.