1 /*

     2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * class for describing CIR watcher. listening for Cir Channel.

    16 *

    17 */

    18 

    19 

    20 #ifndef __IMPSCIRWATCHERAPI_H__

    21 #define __IMPSCIRWATCHERAPI_H__

    22 

    23 //List here the supported CIR types

    24 enum TImpsSupportedCirTypes

    25     {

    26     EImpsTcpCir = 0,

    27     EImpsUdpCir

    28     };

    29 

    30 //How many times connectiong should be retried

    31 const TUint KMaxNumberOfConnAttempts                = 10;

    32 

    33 //How many times pinging should be retried

    34 const TInt KMaxNumberOfPingAttempts                 = 5;

    35 

    36 //The default UDP Port number

    37 const TUint KDefaultUDPPortNumber                   = 3717;

    38 

    39 //Status constants

    40 const TUint KImpsCIRWatcherIdle                     = 5001;

    41 const TUint KImpsCIRWatcherUnknown                  = 5002;

    42 const TUint KImpsCIRWatcherAwaitingDNS              = 5003;

    43 const TUint KImpsCIRWatcherConnectingTCPSocket      = 5004;

    44 const TUint KImpsCIRWatcherSendingHELOMessage       = 5005;

    45 const TUint KImpsCIRWatcherReceivingHELOResponse    = 5006;

    46 const TUint KImpsCIRWatcherSendingPINGRequest       = 5007;

    47 const TUint KImpsCIRWatcherWaitingPINGResponse      = 5008;

    48 const TUint KImpsCIRWatcherReceivingFromSocket      = 5009;

    49 const TUint KImpsCIRWatcherBearerSuspended          = 5010;

    50 const TUint KImpsCIRWatcherStopping                 = 5011;

    51 const TUint KImpsCIRWatcherUDPWatcherActive         = 5012;

    52 

    53 //FORWARD DECLARATIONS

    54 class MMsgConnManager;

    55 class MImpsCirReceiver;

    56 

    57 // CLASS DECLARATION

    58 class CImpsTcpCirWatcher : public CActive

    59     {

    60     public:

    61 

    62         /**

    63         * Two-phased constructor.

    64         * @param TInt Interval of the ping requests

    65         * @param MImpsCirReceiver& Reference to the receiving object

    66         * @param MImpsConnectionManager& Reference to the current

    67         *                                IMPS Connection Manager

    68         * @return CImpsTcpCirWatcher

    69         */

    70         static CImpsTcpCirWatcher* NewL( const TInt aPingInterval,

    71                                          MImpsCirReceiver& aCirReceiver,

    72                                          MMsgConnManager& aConnManager );

    73 

    74         /**

    75         * Destructor. A simple wrapper to the C++ destructor.

    76         *

    77         * NOTE that CIR watcher uses the connection and socket

    78         * server instances owned by MImpsConnectionManager,

    79         * so one should be very careful NOT to Destroy() the

    80         * ConnMan instance before an instance of this interface.

    81         * At deletion time this class might have outstanding socket

    82         * reads and/or writes, the cancelling of which will surely

    83         * fail in case the socket session on which the sockets were

    84         * initially opened has been prematurely closed.

    85         */

    86         virtual ~CImpsTcpCirWatcher();

    87 

    88     public:   //New functions

    89 

    90         /**

    91         * Start a TCP Watcher. This is an asynchronous request

    92         * that completes as soon as the watcher receives a response

    93         * to the HELO request. In such case the watcher completes

    94         * client's request and starts to ping the server in intervals

    95         * defined in the constructor call (default) or by the dedicated

    96         * method SetPingInterval(). The new value becomes effective

    97         * as soon as the ping request following the change of the value

    98         * has been issued.

    99         *

   100         * It should be noted that a call to this method means anything

   101         * only when watcher is at idle state. In other words, watcher

   102         * must be stopped before an attempt to start it again may take place.

   103         * If, for instance, a client wishes to change the server which

   104         * the watcher is connected to, it must first call StopTCPWatcher()

   105         * method and only then initiate a new connection to a different server.

   106         *

   107         * @param aStatus Request status of the client

   108         * @param aServerPort Port number of the server

   109         * @param aServerAddress Address of the server

   110         * @param aCSPSessionID ID of the client's CSP Session

   111         */

   112         virtual void StartTCPWatcherL( TRequestStatus& aStatus,

   113                                        const TUint aServerport,

   114                                        const TDesC& aServerAddress,

   115                                        const TDesC8& aCSPSessionID ) = 0;

   116 

   117         /**

   118         * Stops a TCP Watcher. This is a synchronous request

   119         * which cancels all socket reads and writes and,

   120         * eventually, closes the outbound socket, too.

   121         */

   122         virtual void StopTCPWatcher() = 0;

   123 

   124         /**

   125         * Returns the current state of the watcher. This method comes

   126         * in handy for example in situations where a GPRS resume has

   127         * just been occurred. In such case the client is able to ask

   128         * whether or not the watcher has recovered from the event.

   129         * In principle, the following two status values indicate an

   130         * error:

   131         *

   132         *     - KImpsCIRWatcherUnknown

   133         *     - KImpsCIRWatcherBearerSuspended

   134         *

   135         * If the watcher is ready to be started, the value should be

   136         * KImpsCIRWatcherIdle, not KImpsCIRWatcherUnknown. The latter

   137         * most likely indicates an irretrievable error, whereas the

   138         * status KImpsCIRWatcherBearerSuspended is an error in each

   139         * case: if suspend is the prevailing status on the client side

   140         * too, nothing can be sent or received; if, on the other hand,

   141         * this method returns a status value that suggests the watcher

   142         * thinks bearer is still suspended while the client has received

   143         * a resume event, the two modules are seriously out of sync.

   144         */

   145         virtual TUint WatcherStatus() const = 0;

   146 

   147         /*

   148         * Set the interval in which the watcher pings the server.

   149         * The new value becomes effective as soon as the ping request

   150         * following the change of the value has been issued; i.e. if

   151         * there is already a timer counting at the time of the call of

   152         * this method, it makes no sense to interrupt it.

   153         */

   154         virtual void SetPingInterval( const TInt aPingInterval ) = 0;

   155 

   156     protected:

   157 

   158         /**

   159         * C++ constructor

   160         * @return CImpsTcpCirWatcher

   161         */

   162         CImpsTcpCirWatcher();

   163 

   164     private:  //Data

   165 

   166         TUid                        iDestructorKey;

   167     };

   168 

   169 class CImpsUdpCirWatcher : public CBase

   170     {

   171     public:

   172 

   173         /**

   174         * Two-phased constructor.

   175         * @return CImpsUdpCirWatcher Pointer to the UDP/IP CIR Watcher

   176         */

   177         static CImpsUdpCirWatcher* NewL();

   178 

   179         /**

   180         * C++ destructor

   181         */

   182         virtual ~CImpsUdpCirWatcher();

   183 

   184     public:   //New functions

   185 

   186         /**

   187         * Registers a UDP Watcher. UDP (User Datagram Protocol) is an

   188         * unreliable protocol in the sense that it does not guarantee

   189         * controlled transmission of user's data. The protocol is

   190         * essentially connectionless, which is, basically, also the

   191         * reason for its unreliability. Since the sending and receiving

   192         * parties do not synchronise, or "shake hands" at any time,

   193         * it may happen that the packets constituting the user data

   194         * arrive in random order or, in the worst case, get lost

   195         * altogether while en route. It is therefore advisable to

   196         * use TCP Watcher if reliability is the key aspiration.

   197         *

   198         * UDP Watcher, on the other hand, consumes a lot less resources,

   199         * since there is basially only one pending socket read, which,

   200         * from the point of view of the system, entails a single active

   201         * object waiting for a request (=the socket read) to complete.

   202         * A task could not be much more light-weight.

   203         *

   204         * It should be noted that the service port can (and may) be the

   205         * same for two different receivers. The watcher checks the number

   206         * of the port each time a new receiver is registered and if it finds

   207         * that the specified port is already reserved, it simply bundles up

   208         * the receivers that wish to receive CIRs from that specific port.

   209         *

   210         * The return value is KErrNone if the method executes successfully.

   211         * Otherwise it is one of the system-wide error codes.

   212         *

   213         * @param TInt The UDP Port to listen to

   214         * @param MImpsCirReceiver The object that receives incoming CIRs

   215         * @return TInt Error code

   216         **/

   217         virtual void RegisterCirReceiverL( const MImpsCirReceiver& aCirReceiver,

   218                                            const TInt aServicePort = KDefaultUDPPortNumber ) = 0;

   219 

   220         /**

   221         * Unregister a UDP Watcher. The return value is KErrNone if

   222         * the method executes successfully. Leaves with KErrNotFound

   223         * if the receiver to be unregistered has not been registered.

   224         * Otherwise the error is one of the system-wide error codes.

   225         *

   226         * @param MImpsCirReceiver The receiver to unregister

   227         * @return TInt Error code

   228         */

   229         virtual void UnregisterCirReceiverL( const MImpsCirReceiver& aCirReceiver ) = 0;

   230 

   231         /**

   232         * Reset all watchers on a specified port.

   233         *

   234         * NOTE: By default resets all watchers on all ports!

   235         *

   236         * @param TInt The port to reset; by default all ports

   237         * @return void

   238         */

   239         virtual void Reset( const TInt aServicePort = KErrArgument ) = 0;

   240 

   241         /**

   242         * Destructor.

   243         *

   244         * NOTE: This method only deletes the actual singleton in case

   245         *       there are no more references to it. If a client needs

   246         *       to get rid of the object right away, it should use the

   247         *       DeleteSingleton() method, instead.

   248         */

   249         virtual void Destroy() = 0;

   250 

   251         /**

   252         * Destructor. Deletes the singleton object.

   253         *

   254         * NOTE: After a call to this method, ALL references a client

   255         *       may still have to the UDP watcher will be unusable!

   256         */

   257         virtual void DeleteSingleton() = 0;

   258 

   259     protected:

   260 

   261         /**

   262         * C++ constructor

   263         * @return CImpsTcpCirWatcher

   264         */

   265         CImpsUdpCirWatcher();

   266 

   267         /**

   268         * Stores the destructor key returned by the ECOM framework.

   269         * This method is implemented in the plugin DLL so as not to

   270         * reveal too much of the implementation to client application.

   271         *

   272         * @param TUid Destructor key

   273         * @return void

   274         */

   275         virtual void StoreDestructorKeyL( const TUid aDestructorKey ) = 0;

   276 

   277     protected:  //Data

   278 

   279         RArray<TUid>                iDestructorKeyArray;

   280     };

   281 

   282 /**

   283 * MImpsCirReceiver

   284 *

   285 * Abstract interface for receiving CIRs from the server

   286 * The client module implements this class.

   287 */

   288 class MImpsCirReceiver

   289     {

   290     public:   //New functions

   291 

   292         /**

   293         * CIRWatcher calls this method when it receives a CIR

   294         * from the remote server.

   295         *

   296         * @TDesC8& The incoming data

   297         * @TImpsSupportedCirTypes The type of the received CIR

   298         * @return void

   299         */

   300         virtual void CirReceivedL( const TDesC8& aMessage,

   301                                    const TImpsSupportedCirTypes aCirType ) = 0;

   302 

   303         /**

   304         * CIRWatcher calls this method in case it encounters an

   305         * error situation from which it cannot recover. In general,

   306         * the watcher is designed to be as self-contained as possible,

   307         * but it can still happen that something quite unexpected

   308         * happens that forces the client to handle the situation by,

   309         * for instance, stopping the whole service and reinstating

   310         * the watcher after the erroneus conditions have been dealt with.

   311         * This could be called an emergency brake of a sort.

   312         *

   313         * @param TInt Error code

   314         * @param TImpsSupportedCirTypes The type of the received CIR

   315         * @return void

   316         */

   317         virtual void HandleErrorL( const TInt aReceiverError,

   318                                    const TImpsSupportedCirTypes aCirType ) = 0;

   319     };

   320 

   321 /**

   322 * This class is for packaging of the parameters needed by the

   323 * TCP Watcher. The ECOM framework only accepts one parameter per

   324 * constructor; thus the parameters need to be bundled together

   325 * into a single utility object, the pointer to which will eventually

   326 * be delivered to the constructor of the implementing class.

   327 */

   328 class TTcpWatcherParameters

   329     {

   330     public:

   331 

   332         /**

   333         * C++ Constructor

   334         *

   335         * @param TInt Ping interval

   336         * @param MImpsCirReceiver& Reference to the receiver

   337         * @param MImpsConnectionManager& Reference to the connection manager

   338         * @return TTcpWatcherParameters

   339         */

   340         TTcpWatcherParameters( const TInt aPingInterval,

   341                                MImpsCirReceiver& aCirReceiver,

   342                                MMsgConnManager& aConnManager ) :

   343                 iPingInterval( aPingInterval ),

   344                 iCirReceiver( aCirReceiver ),

   345                 iConnManager( aConnManager ) {}

   346 

   347     public:

   348 

   349         const TInt                  iPingInterval;

   350         MImpsCirReceiver&           iCirReceiver;

   351         MMsgConnManager&            iConnManager;

   352     };

   353 

   354 #include "ImpsIpCirWatcherAPI.inl"

   355 

   356 #endif

   357 

   358 // End of File