/*

* Copyright (c) 2003 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:  This file contains the header file of the CCbsRecEtel class

*

*/

#ifndef     CCBSRECETEL_H

#define     CCBSRECETEL_H

//  INCLUDES

#include "MCbsEtelMessaging.h"

		/*****************************************************

		*	Series 60 Customer / ETel

		*	Series 60  ETel API

		*****************************************************/

#include <rmmcustomapi.h>       // SIM topics

// CONSTANTS

		/*****************************************************

		*	Series 60 Customer / TSY

		*	Needs customer TSY implementation

		*****************************************************/

// FORWARD DECLARATIONS

class CCbsEtelFactory;

class CCbsRecEtelMonitor;

class CCbsRecCollector;

class CCbsRecDecoder;

class CCbsRecNetworkListener;

class CCbsRecMessage;

class CCbsReceiverHelper;

class MCbsMcnSubscriptionsProvider;

class CCbsSetFilterSettingHandler;

class CCbsRecWcdmaMessage;

class CCbsMessage;

class CCbsMessageFactory;

class CCbsLivecastHandler;

//  CLASS DECLARATION 

/**

*   CCbsRecEtel sets up the receiver subsystem for receiving CBS messages 

*   from the ETEL server.

*

*   This class creates instances of CCbsRecEtelMonitor to communicate with 

*   ETel server, CCbsRecDecoder to decode message pages and 

*   CCbsRecCollector to combine partial messages together. CCbsRecEtel 

*   sends completed messages to the database via an interface 

*   class CCbsReceiverHelper.

*

*   An instance of CCbsRecNetworkListener is created to monitor network

*   state changes and report them to CCbsRecEtel instance.

*

*   CCbsRecEtel is also responsible for controlling the CBMI list entries 

*   in ME defining Message Identifiers and DCSes that are to be received. 

*

*   CCbsRecEtel instance does not store information on what topics and

*   languages to subscribe. Instead, on call to ApplyStateChangesL(), 

*   subscriptions and other CB settings are retrieved from the database 

*   and passed to EPOC Telephony server.

*

*   Thus, after topic subscriptions, languages or reception status have

*   been modified, a call to ApplyStateChangesL() has to be made in order

*   to actually bring the changes into effect.

*

*   ON SUBSCRIPTION OF TOPICS AND LANGUAGES

*

*   Although EPOC Telephony server can be requested to relay messages of certain topics and

*   languages, there is a couple of things to note.

*

*   1. In order to detect topics broadcasted within the current region, all

*   CB messages have to be received. This is done by subscribing all topics

*   and languages.

*

*   2. Since MCN clients may subscribe any number of topics, topic filtering 

*   has to be made to remove messages not requested by the UI client.

*

*   3. All languages have to be subscribed at all times. This is because

*   TSY limits the number of languages and a single language (e.g., English),

*   may be represented by multiple DCS values. In addition, CBS specification

*   tells that any message in unspecified language has to be received.

*   Thus the only possibility here is to ignore EPOC Telephony server provided facilities

*   to filter languages, and implement filtering in CbsServer. 

*   This is done in CCbsReceiverHelper.

*/

class CCbsRecEtel : public CBase

    {

    public:     // New functions

        /**

        *   Creates an instance of the class.

        *

        *   @return A new instance of CCbsRecEtel.

        */

        static CCbsRecEtel* NewL();

        /**

        *   Destructor.

        */

        ~CCbsRecEtel();

        /**

        *   Called by the network listener (instance of CCbsRecEtelMonitor)

        *   to indicate that a new message has been received and must be 

        *   handled.

        *

        *   The message page is decoded, cell information (if present) is 

        *   extracted and routed to MCN clients. Pages of multipaged messages 

        *   are then given to the collector. If the message is completed

        *   (all pages collected) or the message is singlepaged, it is

        *   given onwards to CCbsReceiverHelper.

        *

        *   Note that a multipaged message page is routed to MCN clients 

        *   before it is assembled. This is acceptable because maximum

        *   length of a MCN message is specified to be 20 characters.

        *

        *   Ownership of aMessage transferred to CCbsRecEtel.

        *

        *   @param aMessage A pointer to the message page received.

        */

        void HandleMessageReceivedL( CCbsMessage* aMessage );

        /**

        *   Augments aMessage with current network information (i.e., PLMN, LAC

        *   and Cell ID). Does nothing if the network listener iListener

        *   is unavailable.        

        *

        *   @param aMessage Message page.

        */

        TInt AddNetworkInfo( CCbsMessage& aMessage ) const;

        /**

        *   Sets the interface to which all accepted messages are given. 

        *   

        *   @param aInterface A pointer to the receiver interface.

        */

        void SetInterface( CCbsReceiverHelper* aInterface );

        /**

        *   Returns the current and maximum number of subscribed topics.

        *

        *   Topic restrictions are imposed by the TSY in use.

        *

        *   @param aTotal               Total amount of subscribed topics.

        *   @param aMax                 Maximum amount of subscribed topics.

        */

        void GetSubscriptionsLimitsL( TInt& aTotal, TInt& aMax );

        /**

        *   MCN client sessions register to CCbsRecEtel using this function.

        *

        *   When topic subscriptions are gathered during execution of

        *   ApplyStateChangesL(), subscriptions of each registered subscription

        *   provider are added to the CBMI list that determines which

        *   topics are received.

        *

        *   @param aProvider            Topic subscription providing instance

        */

        void AddSubscriptionProviderL( 

            MCbsMcnSubscriptionsProvider* aProvider );

        /**

        *   Removes a topic subscription provider.

        *

        *   @param aProvider            Topic subscription providing instance

        */

        void RemoveSubscriptionProviderL( 

            const MCbsMcnSubscriptionsProvider* aProvider );

        /**

        *   Retrieves current subscriptions, languages and settings

        *   from DB. This data is augmented by topic subscription

        *   information retrieved from MCN client(s). Resulting

        *   topic subscriptions, languages and settings will then

        *   be requested from EPOC Telephony server.

        *

        */    

        void ApplyStateChangesL();

        /**

        *   Returns the current cell information.

        *

        *   The information is retrieved from the last cell information

        *   message received.

        *

        *   Result codes:

        *   KErrNone                    Operation successful, aCellInfo 

        *                               contains a valid cell info message

        *   KErrNotFound                Cell information hasn't been received

        *                               yet - aCellInfo is invalid.

        *

        *   @param  aInfoMessage        Current info message

        *   @param  aTopicNumber        Number of the topic that 

        *                               the msg belongs to

        *   @return                     Result code

        */

        TInt GetCurrentMessage( TDes& aInfoMessage, TInt aTopicNumber );

        /**

        *   Loads CB topics from SIM and adds them on the topic list.

        *   A topic is not added on the list if the same topic

        *   already exists on the list. This identification is done

        *   by the number of the topic only. 

        *

        *   The name of an added topic will be taken from SIM.

        *   If no name has been associated with the topic, the string

        *   <qtn_cb_litext_sim_topic> will be given to the topic.

        *

        *   Result codes:

        *   KErrNotSupported            TSY does not support SIM topics.

        *

        *   @return                     Result code.

        */

        TInt LoadSimTopicsL();

        /**

        *   Deletes a CB topic matching the given topic number from SIM.

        *

        *   Leaves if the operation is unsuccessful.

        *   

        *   @param aNumber              Number of topic to be deleted from SIM.

        *   @param aDeleteAll           Are we deleting all SIM topics, ETrue/EFalse

        */

        void DeleteSimTopicL( const TUint16 aNumber, const TBool aDeleteAll );

        /**

        *   Deletes all topics from the SIM card.

        *

        *   Leaves if the operation is unsuccessful.

        *           

        */

        void DeleteAllSimTopicsL();

        /**

        *   Passes the given CB message to each registered subscriptions

        *   provider (a subscription provider is a MCN client wishing

        *   CB message routing service).

        *

        *   @param  aMessage                CB message

        */

        void RouteMessageL( const CCbsMessage& aMessage );

        /**

        *   Returns the message collector reference.

        *

        *   @return                     Collector reference

        */

        CCbsRecCollector& Collector();

        /**

        *   Returns the receiver helper reference.

        *

        *   @return                     Receiver helper reference

        */

        CCbsReceiverHelper& Interface() const;

   private:

        /**

        *   Constructor.

        */

        CCbsRecEtel();

        /**

        *   Finalizes the construction.

        */

        void ConstructL();

        /**

        *   Establishes a connection with the EPOC Telephony server.

        *

        *   Also opens the necessary EPOC Telephony server resources such as RMobilePhone and

        *   RMobileBroadcastMessaging sessions.

        */

        void ConnectToEtelL();

        /**

        *   Sets the given CB reception mode on ME.

        *

        *   @param aSetting         CB receive mode

        */

        void SetReceptionStatusL( 

            RMobileBroadcastMessaging::TMobilePhoneBroadcastFilter aSetting );

        /**

        *   Returns the total number of topic subscriptions made by

        *   MCN clients registered to the server.

        *

        *   @return                     Number of subscriptions by

        *                               MCN clients.

        */

        TUint NumberOfMcnSubscriptions() const;

        /**

        *   Copies cell information message body into an internal

        *   cache. This way MCN clients can be provided the current

        *   cell information message even without message routing service.

        *

        *   The given message is assumed to be a valid cell information

        *   message (CB message of topic 050).

        *

        *   @param  aMessage                Cell information message

        */

        void ExtractCellInformation( const CCbsMessage& aMessage );

        /**

        *   Copies cell information message body into an internal

        *   cache. This way MCN clients can be provided the current

        *   HomeZone message even without message routing service.

        *

        *   The given message is assumed to be a valid HomeZone

        *   message (CB message of topic 221).

        *

        *   @param  aMessage                Cell information message

        */

        void ExtractHomeZoneInformation( const CCbsMessage& aMessage );

        /**

        *   Checks if the time of the day is such that the user does

        *   not want to receive any messages.

        *

        *   @param  aMessage                CB message

        *   @return                         ETrue if the message should

        *                                   be recived, otherwise EFalse.

        */

        TBool CheckTimeL( const CCbsMessage* aMessage );

    private:    // Data

        // Own: Collector, which is responsible for combining multipaged

        // messages.        

        CCbsRecCollector* iCollector;

        // Own: responsible for converting 7-bit and 8-bit representations 

        // into UCS-2.

        CCbsRecDecoder* iDecoder;

        // Current reception status. This is a cached version of 

        // a variable stored in ME/SIM.

        RMobileBroadcastMessaging::TMobilePhoneBroadcastFilter iReception;

        // Ref: interface to the server. 

        CCbsReceiverHelper* iInterface;

        // Own: SMS messaging object for receiving CBS message pages 

        // from the EPOC Telephony server.

        MCbsEtelMessaging* iMessaging;

        // Own: ETel monitor receives the message pages and forwards them to

        // CCbsRecEtel.

        CCbsRecEtelMonitor* iEtelMonitor;

        // Own: Filter setting handler processes asynchronous 

        // Set Filter Setting command.

        CCbsSetFilterSettingHandler* iFilterSettingHandler;   

        // EPOC Telephony server session.

        RTelServer iEtelServer;

        // Represents the GSM phone used for messaging and network information

        // retrieving.

		/*****************************************************

		*	Series 60 Customer / ETel

		*	Series 60  ETel API

		*****************************************************/

        RMobilePhone iGsmPhone;

        // Custom API is used for SIM Topic handling.

		/*****************************************************

		*	Series 60 Customer / ETel

		*	Series 60  ETel API

		*****************************************************/

        RMmCustomAPI iCustomPhone;

        // Own: active object which listens to changes in network state

        // and reports them to CCbsRecEtel instance.

        CCbsRecNetworkListener* iNetworkListener;

        // Own: set of MCN sessions that provide their topic subscriptions and

        // get cell information routing services

        CArrayFixFlat< MCbsMcnSubscriptionsProvider* >* iSubscriptionProviders;

        // ETrue if a cell information message has been received.

        TBool iCellInfoReceived;

        // Current reception status. This is a cached version of 

        // a variable stored in ME.       

        TBool iReceptionEnabled;

        // Current cell information message.

        TMcnMessage iCurrentCellInfoMessage;

        // Has the user set a time to limit the reception

        TBool iLimitedReception;

        // The current time

        TTime iNow;

        TDateTime iDateTimeNow;

        // Start and end times of limited reception

        TTime iStartTime;

        TTime iEndTime;

        // Cell info cache variables

        RMobilePhone::TMobilePhoneNetworkInfoV1 iCellInfoPLMN;

        TUint iCellInfoLAC;

        TUint iCellInfoCellId;

        // ETrue if HomeZone message has been received

        TBool iHomeZoneReceived;

        // HomeZone cache variables

        RMobilePhone::TMobilePhoneNetworkInfoV1 iHomeZonePLMN;

        TUint iHomeZoneLAC;

        TUint iHomeZoneCellId;

        // Current HomeZone message

        TMcnMessage iCurrentHomeZoneMessage;

        // Message factory

        CCbsMessageFactory* iFactory;

        // LC message handler

        CCbsLivecastHandler* iLivecastHandler;

        // Local variation bits, fetched from CenRep

        TInt iLVBits;

        // Indication of new SIM Topics

        TBool iNewSimTopicsAdded;

        __DECLARE_TEST;

    };

#endif      //  CCBSRECETEL_H   

// End of File