/*
* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
* class for describing CIR watcher. listening for Cir Channel.
*
*/
#ifndef __IMPSCIRWATCHERAPI_H__
#define __IMPSCIRWATCHERAPI_H__
//List here the supported CIR types
enum TImpsSupportedCirTypes
{
EImpsTcpCir = 0,
EImpsUdpCir
};
//How many times connectiong should be retried
const TUint KMaxNumberOfConnAttempts = 10;
//How many times pinging should be retried
const TInt KMaxNumberOfPingAttempts = 5;
//The default UDP Port number
const TUint KDefaultUDPPortNumber = 3717;
//Status constants
const TUint KImpsCIRWatcherIdle = 5001;
const TUint KImpsCIRWatcherUnknown = 5002;
const TUint KImpsCIRWatcherAwaitingDNS = 5003;
const TUint KImpsCIRWatcherConnectingTCPSocket = 5004;
const TUint KImpsCIRWatcherSendingHELOMessage = 5005;
const TUint KImpsCIRWatcherReceivingHELOResponse = 5006;
const TUint KImpsCIRWatcherSendingPINGRequest = 5007;
const TUint KImpsCIRWatcherWaitingPINGResponse = 5008;
const TUint KImpsCIRWatcherReceivingFromSocket = 5009;
const TUint KImpsCIRWatcherBearerSuspended = 5010;
const TUint KImpsCIRWatcherStopping = 5011;
const TUint KImpsCIRWatcherUDPWatcherActive = 5012;
//FORWARD DECLARATIONS
class MMsgConnManager;
class MImpsCirReceiver;
// CLASS DECLARATION
class CImpsTcpCirWatcher : public CActive
{
public:
/**
* Two-phased constructor.
* @param TInt Interval of the ping requests
* @param MImpsCirReceiver& Reference to the receiving object
* @param MImpsConnectionManager& Reference to the current
* IMPS Connection Manager
* @return CImpsTcpCirWatcher
*/
static CImpsTcpCirWatcher* NewL( const TInt aPingInterval,
MImpsCirReceiver& aCirReceiver,
MMsgConnManager& aConnManager );
/**
* Destructor. A simple wrapper to the C++ destructor.
*
* NOTE that CIR watcher uses the connection and socket
* server instances owned by MImpsConnectionManager,
* so one should be very careful NOT to Destroy() the
* ConnMan instance before an instance of this interface.
* At deletion time this class might have outstanding socket
* reads and/or writes, the cancelling of which will surely
* fail in case the socket session on which the sockets were
* initially opened has been prematurely closed.
*/
virtual ~CImpsTcpCirWatcher();
public: //New functions
/**
* Start a TCP Watcher. This is an asynchronous request
* that completes as soon as the watcher receives a response
* to the HELO request. In such case the watcher completes
* client's request and starts to ping the server in intervals
* defined in the constructor call (default) or by the dedicated
* method SetPingInterval(). The new value becomes effective
* as soon as the ping request following the change of the value
* has been issued.
*
* It should be noted that a call to this method means anything
* only when watcher is at idle state. In other words, watcher
* must be stopped before an attempt to start it again may take place.
* If, for instance, a client wishes to change the server which
* the watcher is connected to, it must first call StopTCPWatcher()
* method and only then initiate a new connection to a different server.
*
* @param aStatus Request status of the client
* @param aServerPort Port number of the server
* @param aServerAddress Address of the server
* @param aCSPSessionID ID of the client's CSP Session
*/
virtual void StartTCPWatcherL( TRequestStatus& aStatus,
const TUint aServerport,
const TDesC& aServerAddress,
const TDesC8& aCSPSessionID ) = 0;
/**
* Stops a TCP Watcher. This is a synchronous request
* which cancels all socket reads and writes and,
* eventually, closes the outbound socket, too.
*/
virtual void StopTCPWatcher() = 0;
/**
* Returns the current state of the watcher. This method comes
* in handy for example in situations where a GPRS resume has
* just been occurred. In such case the client is able to ask
* whether or not the watcher has recovered from the event.
* In principle, the following two status values indicate an
* error:
*
* - KImpsCIRWatcherUnknown
* - KImpsCIRWatcherBearerSuspended
*
* If the watcher is ready to be started, the value should be
* KImpsCIRWatcherIdle, not KImpsCIRWatcherUnknown. The latter
* most likely indicates an irretrievable error, whereas the
* status KImpsCIRWatcherBearerSuspended is an error in each
* case: if suspend is the prevailing status on the client side
* too, nothing can be sent or received; if, on the other hand,
* this method returns a status value that suggests the watcher
* thinks bearer is still suspended while the client has received
* a resume event, the two modules are seriously out of sync.
*/
virtual TUint WatcherStatus() const = 0;
/*
* Set the interval in which the watcher pings the server.
* The new value becomes effective as soon as the ping request
* following the change of the value has been issued; i.e. if
* there is already a timer counting at the time of the call of
* this method, it makes no sense to interrupt it.
*/
virtual void SetPingInterval( const TInt aPingInterval ) = 0;
protected:
/**
* C++ constructor
* @return CImpsTcpCirWatcher
*/
CImpsTcpCirWatcher();
private: //Data
TUid iDestructorKey;
};
class CImpsUdpCirWatcher : public CBase
{
public:
/**
* Two-phased constructor.
* @return CImpsUdpCirWatcher Pointer to the UDP/IP CIR Watcher
*/
static CImpsUdpCirWatcher* NewL();
/**
* C++ destructor
*/
virtual ~CImpsUdpCirWatcher();
public: //New functions
/**
* Registers a UDP Watcher. UDP (User Datagram Protocol) is an
* unreliable protocol in the sense that it does not guarantee
* controlled transmission of user's data. The protocol is
* essentially connectionless, which is, basically, also the
* reason for its unreliability. Since the sending and receiving
* parties do not synchronise, or "shake hands" at any time,
* it may happen that the packets constituting the user data
* arrive in random order or, in the worst case, get lost
* altogether while en route. It is therefore advisable to
* use TCP Watcher if reliability is the key aspiration.
*
* UDP Watcher, on the other hand, consumes a lot less resources,
* since there is basially only one pending socket read, which,
* from the point of view of the system, entails a single active
* object waiting for a request (=the socket read) to complete.
* A task could not be much more light-weight.
*
* It should be noted that the service port can (and may) be the
* same for two different receivers. The watcher checks the number
* of the port each time a new receiver is registered and if it finds
* that the specified port is already reserved, it simply bundles up
* the receivers that wish to receive CIRs from that specific port.
*
* The return value is KErrNone if the method executes successfully.
* Otherwise it is one of the system-wide error codes.
*
* @param TInt The UDP Port to listen to
* @param MImpsCirReceiver The object that receives incoming CIRs
* @return TInt Error code
**/
virtual void RegisterCirReceiverL( const MImpsCirReceiver& aCirReceiver,
const TInt aServicePort = KDefaultUDPPortNumber ) = 0;
/**
* Unregister a UDP Watcher. The return value is KErrNone if
* the method executes successfully. Leaves with KErrNotFound
* if the receiver to be unregistered has not been registered.
* Otherwise the error is one of the system-wide error codes.
*
* @param MImpsCirReceiver The receiver to unregister
* @return TInt Error code
*/
virtual void UnregisterCirReceiverL( const MImpsCirReceiver& aCirReceiver ) = 0;
/**
* Reset all watchers on a specified port.
*
* NOTE: By default resets all watchers on all ports!
*
* @param TInt The port to reset; by default all ports
* @return void
*/
virtual void Reset( const TInt aServicePort = KErrArgument ) = 0;
/**
* Destructor.
*
* NOTE: This method only deletes the actual singleton in case
* there are no more references to it. If a client needs
* to get rid of the object right away, it should use the
* DeleteSingleton() method, instead.
*/
virtual void Destroy() = 0;
/**
* Destructor. Deletes the singleton object.
*
* NOTE: After a call to this method, ALL references a client
* may still have to the UDP watcher will be unusable!
*/
virtual void DeleteSingleton() = 0;
protected:
/**
* C++ constructor
* @return CImpsTcpCirWatcher
*/
CImpsUdpCirWatcher();
/**
* Stores the destructor key returned by the ECOM framework.
* This method is implemented in the plugin DLL so as not to
* reveal too much of the implementation to client application.
*
* @param TUid Destructor key
* @return void
*/
virtual void StoreDestructorKeyL( const TUid aDestructorKey ) = 0;
protected: //Data
RArray<TUid> iDestructorKeyArray;
};
/**
* MImpsCirReceiver
*
* Abstract interface for receiving CIRs from the server
* The client module implements this class.
*/
class MImpsCirReceiver
{
public: //New functions
/**
* CIRWatcher calls this method when it receives a CIR
* from the remote server.
*
* @TDesC8& The incoming data
* @TImpsSupportedCirTypes The type of the received CIR
* @return void
*/
virtual void CirReceivedL( const TDesC8& aMessage,
const TImpsSupportedCirTypes aCirType ) = 0;
/**
* CIRWatcher calls this method in case it encounters an
* error situation from which it cannot recover. In general,
* the watcher is designed to be as self-contained as possible,
* but it can still happen that something quite unexpected
* happens that forces the client to handle the situation by,
* for instance, stopping the whole service and reinstating
* the watcher after the erroneus conditions have been dealt with.
* This could be called an emergency brake of a sort.
*
* @param TInt Error code
* @param TImpsSupportedCirTypes The type of the received CIR
* @return void
*/
virtual void HandleErrorL( const TInt aReceiverError,
const TImpsSupportedCirTypes aCirType ) = 0;
};
/**
* This class is for packaging of the parameters needed by the
* TCP Watcher. The ECOM framework only accepts one parameter per
* constructor; thus the parameters need to be bundled together
* into a single utility object, the pointer to which will eventually
* be delivered to the constructor of the implementing class.
*/
class TTcpWatcherParameters
{
public:
/**
* C++ Constructor
*
* @param TInt Ping interval
* @param MImpsCirReceiver& Reference to the receiver
* @param MImpsConnectionManager& Reference to the connection manager
* @return TTcpWatcherParameters
*/
TTcpWatcherParameters( const TInt aPingInterval,
MImpsCirReceiver& aCirReceiver,
MMsgConnManager& aConnManager ) :
iPingInterval( aPingInterval ),
iCirReceiver( aCirReceiver ),
iConnManager( aConnManager ) {}
public:
const TInt iPingInterval;
MImpsCirReceiver& iCirReceiver;
MMsgConnManager& iConnManager;
};
#include "ImpsIpCirWatcherAPI.inl"
#endif
// End of File