Qt Extended Network Services are defined by files that allow the configuration of Linux system networking services. Once the Network Service is defined the user customizes and starts the Network Service they require via using the Internet Settings application.
How it Works
Network configuration file format
The Qt Extended network support can be configured via Network configuration files in $HOME/Applications/Network/config. The structure and type of these configuration files determines the type of the network.
The following keys are generic to all network types:
[Info] The Info group provides a short summary of the network service.
Name - the name presented to the user (translatable).
Type - the parameter determines which plugin should be loaded in order to read this configuration. The following types are currently known:
lan -> LAN device (handled by (W)LAN plug-in $QPEDIR/src/plugins/network/lan )
wlan -> wireless LAN device (handled by (W)LAN plug-in $QPEDIR/src/plugins/network/lan )
pcmcialan -> PCMCIA LAN card is being used (handled by (W)LAN plug-in $QPEDIR/src/plugins/network/lan )
pcmciawlan -> wireless PCMCIA LAN card is being used (handled by (W)LAN plug-in $QPEDIR/src/plugins/network/lan )
dialup -> the dial-up plug-in ($QPEDIR/src/plugins/network/dialing)
bluetooth -> the Bluetooth DUN plug-in ( $QPEDIR/src/plugins/network/bluetooth )
Help - long description of the service (translatable and user visible).
Visibility - set to "hidden" if this interface should be hidden from the user view (e.g. server connections)
CustomID - this id allows the mapping of a network configuration to a plug-in. This means this configuration cannot be loaded by plug-in's which don't support the same custom ID. For more details refer to QtopiaNetworkFactoryIface::customID().
[Properties] The Properties group specifies parameters which are common to most plug-ins.
DeviceName - this allows the explicit assignment of network interfaces to configurations. Using e.g., eth0 as value for this field implies that eth0 is not to be used by other ethernet configurations and the current configuration will not be associated with any other interfaces. Leaving this value empty implies that the configuration should choose the next best interface that matches this type. By default this value is empty. This value is ignored by all network types which rely on dynamic creation of network device names such as the various dial-up and bluetooth interfaces.
DHCP - the interface is configured via DHCP (values = [y]/n)
IPADDR - the IP address to be used by the service (IPv4 or IPv6)
DNS_1 - primary DNS server (IPv4 or IPv6)
DNS_2 - secondary DNS server (IPv4 or IPv6)
BROADCAST - broadcast address (IPv4 or IPv6)
GATEWAY - gateway address (IPv4 or IPv6)
NETMASK - netmask (IPv4 or IPv6)
UserName - the login name if the service requires authentication
Password - the password if the service requires authentication
Autostart - the interface will be started during the Qt Extended startup period (values = y/n)
The QtopiaNetworkInterface class defines the general interface for plug-ins. The following plug-ins are provided by Qt Extended:
Dialup - allows the creation and configuration of network interfaces which require pppd
(W)LAN - allows the creation and configuration of Ethernet and WLAN interfaces
Bluetooth DUN - allows the creation and configuration of ppp connections to devices which support Bluetooth Dialup Networking.
Distribution specific configuration
Unfortunately there is no common way how Linux distributions handle the configuration of network devices. To accomodate for this case the Qt Extended network configuration is split into two parts. Each network plug-in handles the generation of configuration parameters and then passes the information on to a network script called <type>-network. This script must be implementated by device integrators in order to enable Qt Extended to write its configuration to device specific configuration files. By default, Qt Extended provides network script for busybox and SuSE v9.3 systems. If none of the provided scripts is suitable for the target device the template scripts in the plug-in directories can be used as a starting point for new scripts.
The network scripts need root permissions. If Qt Extended is started without root permissions a combination of sudo and setuid bit must be used.
The Dialup Plug-in
General dial-up configuration
The Dialup plug-in:
recognizes/configures the following types of modems for dialup/GPRS:
is implemented in $QPEDIR/src/plugins/network/dialing/
The Dialup plug-in makes use of keys in the Network Service configuration file. For further information refer to pppd documentation or the pppdman page.
[Serial]
GPRS - indicates the service uses a GPRS modem ( values = y/[n] )
APN - the Access Point Name for a GPRS service (GPRS only)
Phone - the phone number for dial-up connections (non-GPRS only)
Type - an internal configuration uses the internal modem as serial device. If the device is external, SerialDevice must be specified (values = [internal]/external)
SerialDevice - optional, the device, for example, /dev/ttyS2
SilentDial - suppress any dial tone (non-GPRS only) (values = y/[n])
Timeout - the disconnect/idle timeout (in seconds) after which pppd automatically disconnects the connection ( values = [none]/<number> )
UsePeerDNS - asks the peer for up to 2 DNS server addresses (values = [y]/n)
In addition to the network configuration file each dial-up interface is associated with a couple of files which guide the dial-up process or give reports about the state of the connection.
the plug-in creates chat files (in $HOME/Applications/Network/chat) which control dial-up process for pppd. These chat scripts follow the chat syntax (see man chat) and are created during the configuration process of the interface.
The pppd process writes its logging output to /tmp/qtopia-0/qpe-pppd-log-<peerID>.
GPRS
Introduction
General Packet Radio Service (GPRS) is a GSM data transmission technique that transmits and receives data in packets rather than via a continuous channel.
Qt Extended uses the Dialup network plug-in to establishing a connection see : $QPEDIR/src/plugins/networking/dialing/
In the ideal case
The user runs the Internet application and configures a GPRS connection
The user selects the newly created GPRS connection and it starts dialing
GPRS is established and Internet traffic can occur
GPRS startup procedure
An outline of the mechanism to establish a GPRS connection is provided in the following section. It is assumed that the application Setting->Internet has been used to create a valid GPRS configuration. The following code walkthrough applies to connections which are established via the internal phone modem only. Any other type of serial connection (e.g. via PCMCIA modem cards) does not use the Qt Extended phone library and hence uses a slightly different approach.
The Qt Extended Network Server is a server task and is started during the startup phase of the Qt Extended server. File location: $QPEDIR/src/server/networkserver.cpp
The network server initiates all network devices for which it can find a valid configuration ( see NetworkServer::updateNetwork() ). File location: $QPEDIR/src/server/networkserver.cpp
which sends a QCop message on the QPE/Network channel. The param parameter is optional and can be used to pass additional startup parameter to the network plug-in. Note that not all network plug-ins support additional parameter and will simply ignore them.
NetworkServer will receive this QCop msg and calls:
DialupImpl::start(...) prepares the pppd command line options. If the serial network device is the internal GSM modem, Qt Extended checks that the phone modem has a valid GSM network registration and starts the connection by calling:
For detailed description of pppd, please refer to man pppd.
GPRS AT dial string
By default the Dialup plug-in uses the following minimal dial string for GPRS connections:
dialstring = "AT+CGDCONT=1,\"IP\",\"" + <provider APN> + "\"" + " OK "
"AT+CGATT=1 OK "
"OK ATD*99***1#";
This string is not necessarily suitable for all modems. If a GPRS data connection cannot be started this string has to be adjusted to the requirements of the particular modem. It may be necessary to contact the modem manufacturer to determine the dial string that should be used. The dialstring can be customized in $QPEDIR/src/plugins/network/dialing/dialstring.cpp.
PPP network script
The dial-up plug-in uses the system dependent configuration script ppp-network. This script must be provided by system integrators. Whenever the dial-up plug-in requests a system dependent operation it calls ppp-network. It must support the following interface/command line options in order to allow interaction with Qt Extended:
start <pppd cmd args>
Starts pppd using the given cmd line arguments. This call requires installed peers files (see install option) and is called by Qt Extended whenever the user whishes to initiate the pppd connection.
stop <PPP-IFACE>
Stops the pppd process that is responsible for the given interface (e.g. ppp0)
install
In general this option is called when the user makes some adjustments to the interface configuration. By using this option Qt Extended ensures that the underlying system configuration reflects these adjustments.
peer <new peerfile>
Installs the given peer file to /etc/ppp/peers.
dns <DNS1> <DNS2>
DNS1 and DNS2 are installed as first and secondary DNS server. If no IP address is passed it is implied that DHCP must be used to obtain the DNS server addresses. This function called when a new interface comes online or when an explicit change of the default gateway has been requested.
cleanup
peer <peerfile>
Deletes <peerfile>.
dns
Reverts any DNS changes.
route <PPP-IFACE>
PPP_IFACE becomes the default gateway for packages. Any existing default route will be implicitly removed.
The LAN Plug-in
General LAN configuration
The LAN plug-in:
recognizes/configures the following types of Ethernet and WLAN adapter:
builtin Ethernet or WLAN devices, e.g. PCI cards (default behavior if not specified otherwise)
is implemented in $QPEDIR/src/plugins/network/lan/
If wireless support is not required the define NO_WIRELESS_LAN can be used to exclude the feature (see Hardware Configuration).
The (W)LAN plug-in makes use of the following keys in the Network Service configuration file. Please note that these entries are stored using QSettings' read/write array support (QSettings::beginReadArray()).
EAPIdentityPassword - password for WPA-EAP ( TTLS & PEAP only )
EAPAnonIdentity - anonymous identity (TTLS & PEAP only )
EAPClientCert - client certificate for WPA-EAP ( TLS only )
EAPClientKey - client key file for WPA-EAP ( TLS only )
EAPClientKeyPassword - client key file password for WPA-EAP ( TLS only )
EAPServerCert - server certificate for WPA-EAP
In addition to these fields the WirelessNetworks group can contain the following entries which are the same for all wireless networks. There main purpose is to determine the roaming behavior.
[WirelessNetworks]
Timeout - the connection to the current AP should be reavaluated after the set amount seconds given by this field. If this field is zero the device can not automatically reconnect to other networks if the current networks is out of reach ( defaults to zero ).
AutoConnect - This option requires a Timeout value >0 and instructs Qt Extended to automatically reconnect to a different network if the current network is out of reach or the link quality degrades too much.
(W)LAN network script
The lan plug-in uses the system dependent network script lan-network. This script must be provided by system integrators. Whenever the lan plug-in requests a system dependent operation it calls ppp-network. It must support the following interface/command line options in order to allow interaction with Qt Extended:
install <IFACE>
IFACE is the name of the network interface. Typical interface names are wlan0 or eth1.
This option is called when the user makes some adjustments to the interface configuration. By using this option Qt Extended ensures that the underlying system configuration reflects these adjustments. If a configuration for IFACE already exists, this command must override the existing values. This option is only called when the configuration changes. Therefore it must store these values to the appropriate configuration files so that any following start command for IFACE can be executed without further config changes.
This parameter supports the following subparameter:
dns [DNS1 DNS2]
DNS1 and DNS2 are installed as first and secondary DNS server. If no IP address is passed it is implied that DHCP must be used to obtain the DNS server addresses. This function called when a new interface comes online or when an explicit change of the default gateway has been requested.
dhcp
The IP, subnet mask, broadcast address and the gateway must be obtained via dhcp.
static <IP> <subnet> <broadcast> <gateway>
If no DHCP is used Qt Extended requires that the user enters the IP details manually. This parameter writes the details out to the system configuration.
wireless <PARAM>
The wireless option is used to pass wireless LAN details. The parameter is made up of a combination of the following options:
-essid <ESSID>
ESSID of the WLAN to be used.
-mode <Master|Managed|Ad-Hoc>
This parameter specifies the mode of the WLAN connection.
-ap <MAC>
MAC is the MacAddress of the access point that the user wants to connect to.
-bitrate <BITRATE>
BITRATE represents the bit rate which should be used for the connection. The unit for this value is MBit.
-nick <NICKNAME>
NICKNAME is the nick name for the WLAN.
-channel <CHANNEL>
CHANNEL is used by Ad-Hoc networks or Master devices only. If CHANNEL is zero and automatic value is requested.
-keylength <128|64>
The length of the WEP key in bit. If the encryption mechanism is not WEP this parameter can be ignored.
The wireless lan uses KEY1 to KEY4 for open/shared WEP encryption. DEFAULTKEY is a value between 1 and 4.
<open|shared> -phrase <PASSPHRASE>
The WLAN uses open/shared WEP encruption with a passphrase.
<none> -nokey
The WLAN uses open/shared WEP encryption without any password.
<WPA-PSK> <PASSWORD> <TKIP|AES>
The WLAN uses WPA-PSK as encryption. PASSWORD is used for the encryption algorithm. The last parameter determines what encryption algorithm is chosen. This determines whether WPA-PSK or WPA-PSK2 is used.
The WLAN uses WPA-EAP as encryption. The authentication is done via either PEAP or TTLS.
<IDENTITY> the RADIUS server identity
<PASSWORD> the password for the identity as configured on the RADIUS server
<SERVER-CERT> validates the servers authenticity
<AUTHENTICATION> the inner authentication (phase 2) method. Possible values MD5|GTC|MSCHAPV2|Any.
<ANON-IDENTITY> the anonymous identity (usually not needed)
stop <IFACE>
This command stops the running interface with name IFACE.
start <IFACE>
This command starts the actual interface. It cann be assumed the the neccessary configuration options for IFACE have been written to the appropriate files as the LAN plug-in always ensures that install has been called prior to start.
cleanup
This command is used when the user deletes a network interface. It may be used to cleanup some configuration files. However since the install option overides any existing configuration it is not absolutely necessary to provide an implementation for this command.
route <IFACE> -gw <GATEWAY IP>
IFACE becomes the default gateway for packages. Any existing default route will be implicitly removed.
The Bluetooth Dial-up Plug-in
General DUN configuration
The Bluetooth dial-up plug-in:
handles ppp interfaces established via Bluetooth connections
configures PPPD peer files in /etc/ppp/peers/
controls the pppd process
is implemented in $QPEDIR/src/plugins/network/bluetooth/
Note that this plug-in only provides the client side of Bluetooth dial-up network. the Qt Extended Bluetooth dial-up networking server is provides by a separate server task.
[Bluetooth]
Profile - must be set to "DUN"
[Serial]
DialString - the main dial string (e.g. *99***1#). Qt Extended automatically prepends AT to this string.
ExtraDialString - additional AT commands which need to be executed prior to the main dial string (e.g. +CGDCONT=1,"ip","<APN>"). Qt Extended automatically prepends AT to this string.
PartnerDevice - the Bluetooth address of the device that provides the DUN server
PeerID - the peer name (generated by Qt Extended)
Speed - the modem speed ( e.g. value = 115200 )
Timeout - the disconnect/idle timeout (in seconds) after which pppd automatically disconnects the connection ( values = [none]/<number> )
Bluetooth dial-up network script
The Bluetooth dial-up network script is called btdun-network and is almost identical to the dialup network script.
The Proxies page
The Dialup and LAN plug-ins share a proxies page. The settings for this page are defined in the configuration as:
[Proxy]
Type - 0 = No proxies, 1 = Automatic, 2 = Manual.
AutoConfig - the script for automatic proxy configuration
HttpHost - HTTP proxy server
HttpPort - socket to be used for HTTP connections via the proxy server
FtpHost - FTP proxy server
FtpPort - socket to be used for FTP connections via the proxy server
NoProxies - list of pages which don't require a proxy
Connectivity state of the device
Applications which are interested in the state of network interfaces should use QtopiaNetwork::online(). If more detailed information are required an application can use the QNetworkState or QNetworkDevice classes.
In order to integrate new plugins into the QNetworkState/QNetworkDevice monitoring system a few requirements must be fulfilled. Each interface must post its state transitions into the network value space. The network value space for a plugin can be found under /Network/Interfaces/<ident>. <ident> is the hash value of the interface handle associated with the particular instance of the plugin. The following entries must be published by the plugin:
UpdateTrigger - Changing this integer value triggers an update to subscribed clients.
Config - The full path (incl. filename) to the settings file for this interface.
NetDevice - The name of the *nix network interface. If the name is not known this value is empty.
ErrorString - A user visible error string which explains the last error. The string doesn't change if no further error occurs.
WAP
Qt Extended stores WAP settings in $HOME/Applications/Network/wap. Every WAP related application must use these configuration settings. They have several groups, with the following keys:
[Info]
The Info group provides a short summary of the WAP profile.
Name - the user visible name of the WAP profile and is equivalent to the ISPName when set via OTA configuration (translatable)
DataAccount - the configration file of the preferred internet account for this WAP profile
[Browser]
General settings for browser applications. Any custom implementation of a WAP browser must comply with these settings.
Cookies - determines how cookies are handled (values = [Reject]/Accept/Confirm)
ShowPictures - the WAP browser displays pictures (values = y/[n])
[MMS]
MMS server details
AllowDeliveryReport - the reception of an MMS shall be reported (values = y/[n])
Expiry - the expiry time for a sent MMS in hours. Zero is equivalent to the maximum timeout (values = <number>)
Port - the MMS server port number (default 110)
Server - url of the MMS server
Visibility - every MMS should contain the sender ID (values = [default]/show/hidden)
[Wap]
WAP server details
Gateway - url of the WAP gateway
UserName - login name for the WAP gateway
Password - password for the WAP gateway
Port - the gateway port number
Bearer - (set via OTA configuration only)
AddressType - (set via OTA configuration only)
LoginType - (set via OTA configuration only)
ProxyService - (set via OTA configuration only)
HomePage - WAP homepage (set via OTA configuration only)
The QWapAccount class may be used as an alternative to directly reading the configuration files.
OTA configuration
Qt Extended can handle OTA network configuration messages. These messages contain details like WAP/MMS server and login details. Every received message is handled by the Internet Settings application and will eventually be stored as a WAP/Internet configuration file.
Session management
The Qt Extended network server provides a session manager. This is used to ensure that a network interface is shutdown when there is no need for it. If an application starts a network interface the interface will remain active for the life time of the application. This means that network interfaces are stopped if an application crashes or quits. If two applications were to request the same interface the interface will stay active until the last application closes.
To cater for more flexibility the network server can extend the session life time beyond the life time of applications. By default every interface which has been started manually will remain active until it is turned off by the user or the interface times out (e.g. timeout on pppd sessions).
Troubleshooting
Example connect,disconnect scripts
The dial-up process uses chat files. These chat files may need some customization in order to work flawless with particular modems. The chat files are stored in $HOME/Applications/Network/chat. Each interface has a connect and a disconnect chat file. The following two chat files represent rather generic chat files for a GPRS connection.
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
ABORT BUSY
# Change the word internet to the name of your providers APN
"" "AT+CGDCONT=1,\"IP\",\"internet\""
OK "AT+CGATT=1"
OK "ATDT*99***1#"
If there are difficulties establishing the GPRS connection it may be helpful to use an approach which would temporarily circumvent the Qt Extended network code. The following script could be used to debug the connection process manually.
#!/bin/sh
#
# Start a pppd session via GPRS
#
# Usage:
# startpppd.sh [PPP peer to call]
#
# The following notes apply to the pppd options used. See the pppd man page for more details
# ttyS0 : change to the device that modem is connected to
# 115200 : lower modem speed if required
# noipdefault: pppd must not propose any IP address to the peer!
# ipcp-accept-local : Accept peers idea of our local address
# modem : use modem control lines; change modem to local if required
# novj : Disable all compression
# record /tmp/ppp-all-text.log : record all traffic to file shown
set -x
if [ -z "$1" ]; then
/usr/sbin/pppd \
ttyS0 \
115200 \
connect 'chat -s -v -f connect-chat' \
disconnect 'chat -s -v -- -f disconnect-chat' \
crtscts \
defaultroute \
replacedefaultroute \
noipdefault \
ipcp-accept-local \
modem \
usepeerdns \
demand \
connect-delay 5000 \
idle 120 \
nodetach \
lcp-echo-failure 0 \
lcp-echo-interval 0 \
novj \
nobsdcomp \
novjccomp \
nopcomp \
noaccomp \
debug
else
# call the specified peer
/usr/sbin/pppd call $1 \
connect 'chat -s -v -f connect-chat' \
disconnect 'chat -s -v -- -f disconnect-chat' \
record /tmp/ppp-all-text.log \
debug
fi
Enabling Debugging
In order to activate the Qt Extended internal network logging facilities you may have to edit $QPEDIR/etc/default/Trolltech/Log.conf or $HOME/Settings/Trolltech/Log.conf. For network debugging you may enable Network and AtChat logging.
Changing the GPRS Packet Size to Compensate for Poor Signal Quality
By default a packet size of 1500 will be used by pppd for GPRS traffic. In cases of poor signal quality it may be necessary to decrease the "mru" and "mtu" packet size being used by pppd, to for 512. See the pppd man page for details on setting mru and mtu values.
Configuration file elements to check/update
check that /etc/ppp/options does not have papcrypt enabled
check the password that may be specified : see /etc/ppp/chap-secrets and /etc/ppp/pap-secrets
check the contents of $HOME/Applications/Network/modules/DialUpGPRS*.conf
check the contents of /etc/ppp/peers/*GPRS*
check that GPRSDialString() in $QPEDIR/src/plugins/networking/dialing/dialstring.cpp suits your modem. For example you may need to use either
AT+CGDCONT=1,"IP" ...
AT+CGDCONT=1,"PPP" ...
update the /etc/ppp/options file to enable debugging and record ALL traffic. eg add
debug
record /tmp/ppp-all-text.log
modify the connect-chat, disconnect-chat and startpppd.sh to suit your modem and internet provider : at least
in connect-chat change internet to the name of your providers APN
in connect-chat change the GPRS init/dial string as required
Dialing with the example GPRS Dial script
Ensure that Qt Extended and pppd are not running
Start pppd via running startpppd.sh
Ping an non-local address : eg
ping 216.239.39.99
Confirm that pppd attempts to start the link and review the content of /tmp/ppp-all-text.log
If needed send the recorded traffic as setup in step 2 in a tar.gz to support
Network testing
The following can help to isolate any GPRS issues.
Run the following commands to ping local and non-local resources:
ping <some IP address on your local network>
ping 66.102.7.99
ping <some host on your local network>
ping www.google.com
It might be necessary to specify the network interface that the ping command should use. If you have more than one network interface and suspect routing issues use:
ping -I <iface-name> <host>
If one or less of the above tests fail then provide the output of the following commands :
/sbin/ifconfig -a
/sbin/ifstatus eth0
/sbin/route
cat /etc/resolv.conf
cat /etc/ppp/resolv.conf
If you have a firewall in use, check that the route uses the correct gateway address and that the firewall is not blocking IP traffic from the device. Lastly it may helpful to compare the results of running the above commands with results given by running the same commands on a development machine.
Requesting Support
If support is needed please ensure that your support request contains the following items:
the peer file ( see /etc/ppp/peers )
the network configuration file ( $HOME/Applications/Network/config/GPRS<peerID>.conf )
the pppd log file ( /tmp/qtopia-0/qpe-pppd-log-<peerID> )
the connect and disconnect chat ( $HOME/Applications/Network/chat/connect-<peerID> )
all parameters passed to pppd (check debug output for network details). Note that network logging may have to be enabled.
Cette page est une traduction d'une page de la documentation de Qt, écrite par Nokia Corporation and/or its subsidiary(-ies). Les éventuels problèmes résultant d'une mauvaise traduction ne sont pas imputables à Nokia.
Vous avez déniché une erreur ? Un bug ? Une redirection cassée ? Ou tout autre problème, quel qu'il soit ? Ou bien vous désirez participer à ce projet de traduction ? N'hésitez pas à nous contacter
ou par MP !
