--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/IMPSengine/enginc/ImpsIpCirWatcherAPI.h Thu Dec 17 08:41:52 2009 +0200
@@ -0,0 +1,358 @@
+/*
+* 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