/*
* 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