/*

* Copyright (c) 2008 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:  Sub-session for SAT services.

*

*/

#ifndef RSATSERVICE_H

#define RSATSERVICE_H

//  INCLUDES

#include <e32std.h>

// FORWARD DECLARATIONS

class CFbsBitmap;

class RSatSession;

class TSatIconInfo;

class TSatInternalIconInfo;

class CSatPluginMonitor;

// DATA TYPES

/**

 * Array containing the icon information

 */

typedef RArray<TSatIconInfo> RIconEf;

// CLASS DECLARATION

/**

 *  <b>Sub-session for SAT services to SIM</b>

 *

 *  In order to use SAT Service API, services of an another API is needed:

 *  <ul>

 *  <li><b>SAT Client API</b>        \n For connecting SAT Session <BR>

 *  </ul>

 *

 *  Idle mode text client needs to monitor for idle mode content 

 *  changes and call SetIdleModeTextResponse()

 *  if content is updated.

 *  Result needs to be reported also if there already is  

 *  initial content after startup, when change notification has not been 

 *  requested yet.

 *  Example sequence for Idle mode client:

 *  1. Startup

 *  2. Request notification for idle mode content updates from.

 *  3. Try to get initial idle mode text.

 *  4. Use initial content, if there was some.

 *  5. Report result if there was content.

 *  Later:

 *  6. Idle mode text change notification request is completed.

 *  7. Renew notification request.

 *  8. Read new content.

 *  9. Use new content.

 *  10. Report result.

 *

 *  @code

 *  // How to connect to SAT service :

 *  // How to request notification on SetupIdleModeText change:

 *

 *  RSatSession satSession;

 *  RSatService satService;

 *  // Connect session

 *  satSession.ConnectL();

 *  satService.OpenL( satSession );

 *  // Start observing asynchronously for changes

 *  satService.NotifySetupIdleModeTextChange( status );

 *  

 *  //How to read Idle Mode Text and icon:

 *

 *  // Read text and icon after startup and when notified about change.

 *  TSatIconQualifier iconQualif( ESatIconNoIcon );

 *  TUint8 recordId( 0 );

 *  TInt error( KErrNone );

 *  HBufC* text = NULL;

 *  satService.GetSetupIdleModeTextL( 

 *    text, iconQualif, recordId );

 *  CFbsBitmap* icon = NULL;

 *  if ( text )

 *      {

 *      // Use text, take care of cleanup.

 *      }

 *  if ( ESatIconNoIcon != iconQualif )

 *      {

 *      // There's an icon to be displayed.

 *      // Get icon records into array.

 *      RIconEf iconInfos;

 *      CleanupStack::PushL( TCleanupItem( 

 *          LocalArrayCleanupFunction, iconInfos )

 *      satService.GetIconInfoL( recordId, iconInfos );

 *

 *      // Resolve which icon to use using icon infos.

 *      // Then get the icon you selected.

 *      icon = satService.GetIconL( iconInfos[ 0 ] );

 *      CleanupStack::PopAndDestroy(); // iconInfos

 *

 *      if ( ESatIconSelfExplanatory == iconQualif )

 *          {

 *          // Only icon should be displayed.

 *          }

 *      else if ( ESatIconNotSelfExplanatory == iconQualif )

 *          {

 *          // Both text and icon should be displayed.

 *          }

 *      }

 *  // else: only text should be displayed

 *  

 *  // Display text and/or icon, take care of their cleanup.

 *

 *  @endcode

 *

 *

 *  @lib SatClient.lib

 *  @since 5.1

 */

class RSatService : public RSubSessionBase

    {

    public:  // Enumerations

        /**

         * Result options for idle mode text setup.

         */

        enum TSATIdleResult

            {

            /** 

             * Text and Icon were set up successfully

             */

            ESATIdleSuccess = 0x00,

            /** 

             * Text was set up successfully, but requested icon was not 

             * displayed

             */

            ESATIdleSuccessRequestedIconNotDisplayed = 0x04,

            /**

             * Text could not be displayed - temporary problem

             */

            ESATIdleMeUnableToProcessCmd = 0x20,

            /**

             * Text could not be displayed - permanent problem

             */

            ESATIdleCmdBeyondMeCapabilities = 0x30

            };

        /**

         * Specifies icon role.

         */

        enum TSatIconQualifier

            {

            /** 

             * Icon is not available.

             */

            ESatIconNoIcon = 1,

            /**

             * Icon is self-explanatory, 

             * i.e. if displayed, it replaces the text string.

             */

            ESatIconSelfExplanatory,

            /**

             * Icon is not self-explanatory, 

             * i.e. if displayed, it shall be displayed together with 

             * the text string.

             */

            ESatIconNotSelfExplanatory

            };

    public:  // Constructors

        /**

         * C++ default constructor.

         */

        IMPORT_C RSatService();

    public: // New functions

        /**

         * Opens the sub-session.

         *

         * @since 5.1

         * @param aSession Sub-session.

         * @leave Error value returned by RSubSessionBase::CreateSubSession.

         */

        IMPORT_C void OpenL( const RSatSession& aSession );

        /**

         * Closes the sub-session.

         * 

         * @since 5.1

         */

        IMPORT_C void Close();

        /**

         * Requests notification when idle mode text or image are

         * updated.

         *

         * Idle client needs to monitor for setup idle mode content updates.

         * When a request is completed, the Idle client 

         * can read new content using GetSetupIdleModeTextL and must 

         * report idle mode content displaying result using

         * SetIdleModeTextResponse().

         *

         * @since 5.1

         * @param aStatus Request to be completed on update.

         * @return KErrNone or a system-wide error code. 

         * On an error request is not accepted so don't set requester active.      

         */

        IMPORT_C TInt NotifySetupIdleModeTextChange( 

            TRequestStatus& aStatus );

        /**

         * Cancels notification request for setup idle mode 

         * text or image change.

         *        

         * @since 5.1

         */

        IMPORT_C void NotifySetupIdleModeTextChangeCancel();

        /**

         * Get idle mode text and icon.

         *

         * Icon and text should be displayed depending on how aIconQualifier

         * specifies icon role. Result must be reported using  

         * RSatService::SetIdleModeTextResponse().

         * Notice: result needs to be reported also if content is available 

         * already after startup when client requests notification for the 

         * first time.

         * If unable to display icon, then only text can be displayed (adjust

         * reported result value).

         *

         * @since 5.1

         * @param aText New text, if available. Ownership transferred.

         * NULL if no text to display.

         * @param aIconQualifier Specifies if icon, text or both are preferred.

         * @param aRecordNumber Record id for icon.

         * @return Reserved for future use.

         * @leave KErrNotFound ESatIconNotSelfExplanatory icon without text.

         */

        IMPORT_C TBool GetSetupIdleModeTextL( 

            HBufC*& aText, 

            TSatIconQualifier& aIconQualifier,

            TUint8& aRecordNumber );        

        /**

         * Gets the information of icons from the SIM.

         *

         * @since 5.1

         * @param aRecordNumber Record number from proactive command.

         * @param aIconEf Contains the icon information.

         * @leave Error value returned by RSubSessionBase::SendReceive.

         * @leave KErrCorrupt if the info is invalid.

         */

        IMPORT_C void GetIconInfoL( TUint8 aRecordNumber, 

                                    RIconEf& aIconEf ) const;

        /**

         * Gets the bitmap of selected icon from SIM. Client should determine

         * the suitable icon using GetIconInfoL.

         *

         * @since 5.1

         * @param aIconInfo Information of the selected icon.

         * @leave Error value returned by RSubSessionBase::SendReceive.

         * @leave Error value returned by CFbsBitmap::Duplicate.

         * @leave Error value returned by RSubSessionBase::Send.

         * @return Bitmap of the icon. The client is responsible for deleting

         * the pointer.

         */

        IMPORT_C CFbsBitmap* GetIconL( const TSatIconInfo& aIconInfo ) const;

        /**

         * Sets SetUpIdleModeText response. 

         *

         * This must be called by the Idle client application after 

         * IdleModeText has been modified by SAT, meaning

         * when RSatService::NotifySetupIdleModeTextChange() is completed.

         * Also needs to be called if GetSetupIdleModeTextL() returned 

         * content and RSatService::NotifySetupIdleModeTextChange() 

         * notification was not requested yet.

         * 

         * @since 5.1

         * @param aResult Result of displaying idle mode text and icon.

         */

        IMPORT_C void SetIdleModeTextResponse( 

            const TSATIdleResult& aResult ) const;

    private: // New functions

        /**

         * Checks that the data from SIM is valid.

         * 

         * @since 5.1

         * @param aData Icon info to be checked.

         * @leave KErrCorrupt if the info is invalid.

         */

        void CheckInfoValidityL( const TDesC8& aData ) const;

        /**

         * Set ETSI specified bitmap data to TSatIconInfo.

         * 

         * @since 5.1

         * @param aContainer Client side Icon info.

         * @param aIconSatData RSat::TIcon data from server.

         */    

        void SetIconInfoL( TSatIconInfo& aContainer, 

                          const TDesC8& aIconSatData ) const;

        /**

         * Convert TSatIconinfo to TSatInternalIconInfo.

         * 

         * @since 5.1

         * @param aIconInfo user side icon info.

         * @param aInternalIconINfo sat side icon info.

         */                           

        void FillInternalIconInfo( const TSatIconInfo& aIconInfo, 

                 TSatInternalIconInfo& aInternalIconInfo ) const;                          

    private: 

        /** 

         * Prohibit copy constructor if not deriving from CBase. 

         */

        RSatService( const RSatService& );

        /**  

         * Prohibit assigment operator if not deriving from CBase. 

         */

        RSatService& operator=( const RSatService& );

    private: // Data  

        /**

         * Arguments for asynchronous message.

         */

        TIpcArgs iArgs;

        /**

         * Maximum support icon size.

         */        

        TInt iMaxIconDataSize;

        /**

         * SetupIdleMode content monitoring.

         * Own

         */   

        CSatPluginMonitor* iSatPluginMonitor;

    };

#endif // RSATSERVICE_H

// End of File