NetworkConnection Class Reference

Network connection base class. More...

#include <NetworkConnection.h>

Inheritance diagram for NetworkConnection:
PowerEventListener Thread EventBroadcaster< NetworkEventListener > GprsConnection WlanConnection

List of all members.

Public Member Functions

 NetworkConnection (int netType)
 Class constructor.
virtual ~NetworkConnection ()
 Class destructor.
bool initialize ()
 Initialize network connection.
bool shutdown ()
 Shutdown network connection.
bool connect ()
 Connect to network.
bool disconnect ()
 Disconnect network.
void addListener (NetworkEventListener *pListener)
 Add new listener.
const char * getLastError ()
 Get last error.
int getNetworkType ()
 Get network type.
virtual bool isConnectionUp ()=0
 Check connection state The implementation must implement this method to return a valid value.
virtual bool getNetworkInfo (GENERIC_NETWORK_INFO &netInfo)=0
 Get network information.
const char * getLastStatus ()
 Get network status.
const char * getLastEventMsg ()
 Get last network status or error message.
NetworkEvent getLastEvent ()
 Get last network event (current status).

Protected Member Functions

virtual bool netInitialize ()=0
 Network initialization routine The implementation must implement this method to initialize the network connection.
virtual bool netConnect ()=0
 Network connection establish routine The implementation must implement this method to connect to a network.
virtual bool netDisconnect ()=0
 Network disconnect routine The implementation must implement this method to disconnect from a network.
virtual bool netShutdown ()=0
 Network shutdown routine The implementation must implement this method to shutdown the network connection.
virtual bool netRepair ()
 Repair network connection.
virtual bool netSuspend ()
 Suspend network connection.
virtual bool netResume ()
 Restore network connection.
virtual void run ()
 Worker thread.
virtual bool powerStateChange (PowerState oldState, PowerState newState)
 Power manager state change.
void eventNotify (NetworkEvent e)
 Notify listeners about event.
void reportError (const char *error)
 Report network connection error Reports the network connection error by broadcasting an EV_NETWORK_ERROR system event.
void setStatus (const char *status)
 Report the network status Reports the network status by broadcasting an EV_NETWORK_STATUS system event.

Static Protected Member Functions

static bool getInterfaceAddresses (const char *ifName, char *ipAddr, char *hwAddr)
 Get interface addresses.

Detailed Description

Network connection base class.

Implements the basic functionality of a network connection. Encapsulates a state machine and a worker thread that maintains the network connection and attempts to repair it when a failure is detected.

This is an abstract class, it may not be instantiated and used directly. Instead, a specific implementation should inherit from this class and implement the declared netXXX methods.

NetworkConnection is a power management aware class, it suspends the connection when a power saving mode of the data terminal is entered and restores the connection when returning from a power saving mode.


Constructor & Destructor Documentation

NetworkConnection::NetworkConnection ( int  netType  ) 

Class constructor.

Initializes the network connection object. The network type identifier is stored for external use via getNetworkType() method. It is recommended to use the platform specific types that match the communication module type identifier of the mobile data terminal.

Parameters:
netType Specifies the network type identifier.
NetworkConnection::~NetworkConnection (  )  [virtual]

Class destructor.

Terminates the network connection object.


Member Function Documentation

void NetworkConnection::addListener ( NetworkEventListener pListener  ) 

Add new listener.

Adds a new listener of type TListener to the list of event listeners.

Parameters:
pListener Pointer to the event listener class that implements TListener interface.

Reimplemented from EventBroadcaster< NetworkEventListener >.

bool NetworkConnection::connect (  ) 

Connect to network.

Connects to network. Starts the worker thread and launches the state machine of the network connection.

The function returns immediately, typically before the network is actually connected. The caller may monitor network activity via NetworkEventListener interface.

Returns:
Returns true if the connection was initiated successfully.
bool NetworkConnection::disconnect (  ) 

Disconnect network.

Disconnects from network. Stops the worker thread and calls netDisconnect() internally.

The function blocks until the network is disconnected, or an error occurs.

Returns:
Returns true if the connection was closed successfully.
void NetworkConnection::eventNotify ( NetworkEvent  e  )  [protected]

Notify listeners about event.

Broadcasts the specified event by calling all registered listeners.

Parameters:
e Specifies the event identifier to be delivered.
bool NetworkConnection::getInterfaceAddresses ( const char *  ifName,
char *  ipAddr,
char *  hwAddr 
) [static, protected]

Get interface addresses.

Retrieves IP and MAC addresses of the network connection interface.

Parameters:
ifName Points to a null-terminated string containing the name of the interface.
ipAddr Points to a string buffer that receives the IP address of the network interface.
hwAddr Points to a string buffer that receives the hardware MAC address of the network interface.
Returns:
Returns true if address was successfully stored in a buffer, false otherwise
const char* NetworkConnection::getLastError (  )  [inline]

Get last error.

Returns:
Returns the text message associated with a last error occured, NULL if none.

Reimplemented in WlanConnection.

NetworkEvent NetworkConnection::getLastEvent (  ) 

Get last network event (current status).

Returns:
Returns the network event last occurred
const char* NetworkConnection::getLastEventMsg (  )  [inline]

Get last network status or error message.

Returns:
Returns last network status or error message.
const char* NetworkConnection::getLastStatus (  )  [inline]

Get network status.

Returns:
Returns current network status.
virtual bool NetworkConnection::getNetworkInfo ( GENERIC_NETWORK_INFO netInfo  )  [pure virtual]

Get network information.

Parameters:
netInfo Address to the structure where to store the retrieved network information The implementation must implement this method to fill the information structure.
Returns:
Returns true if the information was read successfully.

Implemented in GprsConnection, and WlanConnection.

int NetworkConnection::getNetworkType (  )  [inline]

Get network type.

Returns:
Returns the network type identifier specified in the class constructor.
bool NetworkConnection::initialize (  ) 

Initialize network connection.

Initializes the network connection. The connection may be initialized only once. Internally this method calls netInitialize() virtual function which should be overridden by a specific network implementation.

Returns:
Returns true if the network connection was initialized successfully.
virtual bool NetworkConnection::isConnectionUp (  )  [pure virtual]

Check connection state The implementation must implement this method to return a valid value.

Returns:
Returns true if the network connection is still available.

Implemented in GprsConnection, and WlanConnection.

virtual bool NetworkConnection::netConnect (  )  [protected, pure virtual]

Network connection establish routine The implementation must implement this method to connect to a network.

Returns:
Returns true if network connection was established successfully.

Implemented in GprsConnection, and WlanConnection.

virtual bool NetworkConnection::netDisconnect (  )  [protected, pure virtual]

Network disconnect routine The implementation must implement this method to disconnect from a network.

Returns:
Returns true if the network was disconnected successfully.

Implemented in GprsConnection, and WlanConnection.

virtual bool NetworkConnection::netInitialize (  )  [protected, pure virtual]

Network initialization routine The implementation must implement this method to initialize the network connection.

Returns:
Returns true if the network connection was initialized successfully.

Implemented in GprsConnection, and WlanConnection.

bool NetworkConnection::netRepair (  )  [protected, virtual]

Repair network connection.

Called internally when the state machine of the network connection detects that a network failure. The default behavior is to disconnect from network by calling netDisconnect() and then re-connect by calling netConnect() virtual methods.

The implementation may override this method to take a specific action.

Returns:
Return true if the connection was repaired successfully.
bool NetworkConnection::netResume (  )  [protected, virtual]

Restore network connection.

Called internally when the mobile data terminal leaves a power saving mode. The implementation may override this method to take a specific action.

Returns:
Return true when the connection is restored successfully.

Reimplemented in GprsConnection, and WlanConnection.

virtual bool NetworkConnection::netShutdown (  )  [protected, pure virtual]

Network shutdown routine The implementation must implement this method to shutdown the network connection.

Returns:
Returns true if the network connection was shut down successfully.

Implemented in GprsConnection, and WlanConnection.

bool NetworkConnection::netSuspend (  )  [protected, virtual]

Suspend network connection.

Called internally when the mobile data terminal enters a power saving mode. The implementation may override this method to take a specific action.

Returns:
Return true when ready to enter a power saving mode. Return false to reject the request and abort power saving.

Reimplemented in GprsConnection, and WlanConnection.

bool NetworkConnection::powerStateChange ( PowerState  oldState,
PowerState  newState 
) [protected, virtual]

Power manager state change.

Notifies the listener class about a change in the power manager state. The method is called before the power manager executes all steps necessary to proceed to the specified new power state. The listener may reject current state transition by returning false. If the listener does not want to interfere, or allows transition to the new state, it should return true.

Parameters:
oldState Specifies the old state of the power manager.
newState Specifies the new state of the power manager.

Implements PowerEventListener.

void NetworkConnection::reportError ( const char *  error  )  [protected]

Report network connection error Reports the network connection error by broadcasting an EV_NETWORK_ERROR system event.

Parameters:
error Pointer to the error description
void NetworkConnection::run (  )  [protected, virtual]

Worker thread.

Runs the state machine of the network connection. Tries to connect to network initially. When connected, checks for network availability and tries to restore the network connection in case of a failure.

Reimplemented from Thread.

void NetworkConnection::setStatus ( const char *  status  )  [protected]

Report the network status Reports the network status by broadcasting an EV_NETWORK_STATUS system event.

Parameters:
status Pointer to the status description
bool NetworkConnection::shutdown (  ) 

Shutdown network connection.

Shuts down and uninitializes the network connection. The connection may be shut down only if it is disconnected.

Internally this method calls netShutdown() virtual function which should be overridden by a specific network implementation.

Returns:
Returns true if the network connection was shut down successfully.

The documentation for this class was generated from the following files:
Generated on Wed Oct 20 11:13:44 2010 for libspatha by  doxygen 1.6.3