// Copyright (c) 2002-2009 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:

// ETel (U)SAT header file.

// Describes the (U)SAT API - classes, methods and types.

// 

//

/**

 @file

 @publishedPartner

 @released

*/

#ifndef __ETELSAT_H__

#define __ETELSAT_H__

#include <e32base.h>

#include <s32mem.h>

#include <etel.h>

const TInt KETelExtSatV1=5000;  //< The global identifier for the first version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KETelExtSatV2=9000;  //< The global identifier for the second version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KETelExtSatV3=11000; //< The global identifier for the third version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KEtelExtSatV4=11100; //< The global identifier for the fourth version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KEtelExtSatV5=11200;	//< The global identifier for the fifth version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KEtelExtSatV6=11300;	//< The global identifier for the sixth version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

const TInt KEtelExtSatV7=11400;	//< The global identifier for the seventh version of the ETelSat API, for passing into RTelServer::IsSupportedByModule()

/**

(U)SAT allocated error space ranges from -5250 to -5299.

Do not return KErrSatBase as an error.

*/

const TInt KErrSatBase=-5250;

/** The (U)SIM Application Toolkit is busy. */

const TInt KErrSatBusy=KErrSatBase-1;

/**

The error code can be received following Call Control.  It is returned when the

(U)SIM (or MO SM Control by (U)SIM) either bars or modifies the original

action.

*/

const TInt KErrSatControl=KErrSatBase-2;

/**

The error code can be received following Multimedia Service Notification Download.

It is returned when the (U)SIM either bars the original action,The ME shall not retry the same command.

*/

const TInt KErrSatMmsFailure=KErrSatBase-3;

enum {KTpduMaxSize=248};

typedef TBuf8<KTpduMaxSize> TTpdu;

const TInt KPdpActivationParametersMaxLengh=512;  //< Global constant defines maximum length of the buffer that can hold PDP CONTEXT ACTIVATION REQUEST

typedef TBuf8<KPdpActivationParametersMaxLengh> TPdpParameters;

// Forward declaration

class CSatPtrHolder;

class RSat: public RTelSubSessionBase

/**

 * Provides an interface to Symbian's ETelSat API.  RSat inherits from

 * RTelSubSessionBase defined in ETEL.H.

 *

 * On GSM/WCDMA networks, this API offers access to the (U)SIM Application

 * Toolkit, or (U)SAT.  On CDMA networks, it offers access to Cdma Card Application

 * Toolkit, or CCAT. Both toolkits are very similar.

 *

 * Phones on both networks contain an electronic card that stores the information

 * such as subscriber's identification, the phone's number, an address book, etc.

 * The (U)SAT and CCAT toolkits allow the card to be more than just a storage

 * device; they define a protocols that allow the card to ask the phone to perform

 * tasks.  For instance, a card can ask the phone to display a message on the

 * screen, add new menu items to the phone's menus, ask the phone to dial a number,

 * or browse to a URL.

 *

 * (U)SAT and CCAT are based around 'Proactive Commands': each is a task for the

 * phone to perform.  For the four tasks mentioned in the previous paragraph, the

 * card sends the phone proactive commands called DISPLAY TEXT, SET UP MENU, SET

 * UP CALL, and LAUNCH BROWSER. Understanding the range of proactive commands and

 * their capabilities is the first step to understanding (U)SAT and CCAT.

 *

 * To use Symbian's ETelSat API you request notification when proactive commands

 * arrive at the phone.  For each proactive command (DISPLAY TEXT, SET UP

 * MENU etc.) there is an RSat member function.  This function tells Symbian OS

 * when you are interested in a proactive command.  It also gives

 * Symbian OS a TRequestStatus that is completed when the next proactive

 * command arrives.

 *

 * Some of the proactive commands are not accessible to Symbian's ETelSat API.

 * Your phone's TSY deals with them for you, hiding them from RSat.  The remaining

 * proactive commands are handled by RSat.  Request notification for each one

 * using the functions listed below.

 *

 * (U)SAT and CCAT are defined in 3GPP TS 31.111 and 3GPP2 C.S0035-0 respectively.

 * Both of these specifications are based on ETSI TS 102 223.  We suggest you read

 * ETSI TS 102 223 before reading anything else: it is much more informative and

 * easier to read than the other two specifications. We also suggest you have a

 * basic understanding of ETSI TS 102 223 before using Symbian's ETelSat API.

 *

 * Before starting a (U)SAT or CCAT session, start a session with a phone.  A phone

 * session is represented by either RPhone or RMobilePhone.  Now you can create an

 * RSat interface and start the RSat session with RSat::Open().  Pass this method

 * the RPhone or RMobilePhone instance.  This tells the (U)SAT or CCAT session

 * which phone to work with.

 *

 * This documentation uses the word "UICC" to mean  the card. Here are

 * the phrases used to describe the card on various networks:

 *

 * On GSM networks, the physical card is called the ICC and the software it

 * contains is called the SIM (Subscriber Identity Module).  SAT is an interface

 * to the software.

 *

 * On WCDMA networks, the physical card is called the UICC and the software it

 * contains is called the USIM (Universal Subscriber Identity Module).  USAT is an

 * interface to the software.

 *

 * On 3G CDMA networks, the card and the software are called a R-UIM.  CCAT is an

 * interface to the software.

 *

 * To use the ETelSat API, follow these steps.  Firstly, create an interface to the phone, if you haven't already done so:

 *

 * - Create an RPhone

 * - Call RPhone::ConstructL()

 * - Call RPhone::Open()

 *

 * Secondly, create and open an interface to the ETelSat client:

 *

 * - Create an RSat

 * - Call RSat::ConstructL()

 * - Call RSat::Open(), passing it the RPhone from the previous step.

 *

 * Now tell the UICC what SAT features the phone supports.  The UICC expects this

 * information in a "profile" object.  The structure of this object is described in

 * ETSI TS 102 223.

 *

 * - Firsly, call RSat::GetMeSideSatProfile().  The TSY returns a profile

 * describing the SAT features that are supported by the phone's hardware and the

 * TSY.  These will be features that are not under the ETelSat client's control; you

 * cannot use the RSat API to access them.

 *

 * - Now modify the profile to include the SAT features that you support.  This

 * will mainly involve settings flags in the profile object.

 *

 * - Finally, send the profile to the UICC by calling RSat::ClientSatProfileIndication()

 *

 * Here is a list of the proactive commands supported by RSat.  Once you have

 * completed all the steps above, queue some notification requests by

 * calling some RSat::Notify..... command listed below:

 *

 * - DISPLAY TEXT - displays text to the user - see RSat::NotifyDisplayTextPCmd()

 * - GET INKEY -

 *   instructs phone to display text and/or an icon and to expect the user to enter a single character -

 *   RSat::NotifyGetInkeyPCmd()

 * - GET INPUT -

 *   instructs phone to display text and/or an icon and to expect the user to enter a string -

 *   RSat::NotifyGetInputPCmd()

 * - PLAY TONE -

 *   instructs phone to play a tone -

 *   RSat::NotifyPlayTonePCmd()

 * - SET UP MENU -

 *   provides a set of menu items to be integrated with the phone's menu system -

 *   RSat::NotifySetUpMenuPCmd()

 * - SELECT ITEM -

 *   provides a set of menu items to be shown to the user. The user can choose one of these menu items -

 *   RSat::NotifySelectItemPCmd()

 * - SEND SHORT MESSAGE -

 *   asks the phone to send an SMS message -

 *   RSat::NotifySendSmPCmd()

 * - SEND SS -

 *   asks the phone to send a supplementary service request -

 *   RSat::NotifySendSsPCmd()

 * - SEND USSD -

 *   asks the phone to send a Unstructured Supplementary Service Data request to the network -

 *   RSat::NotifySendUssdPCmd()

 * - SET UP CALL -

 *   asks the phone to connect a call -

 *   RSat::NotifySetUpCallPCmd()

 * - REFERSH -

 *   indicates that changes have occurred to the UICC that may affect the phone -

 *   RSat::NotifyRefreshPCmd()

 * - SET UP EVENT LIST -

 *   gives the phone a list of events that may occur to the phone.

 *   The phone must inform the UICC when an event on the list occurs -

 *   RSat::NotifySetUpEventListPCmd()

 * - SET UP IDLE MODE TEXT -

 *   provides text (and optionally an icon) to be displayed when the phone is idle -

 *   RSat::NotifySetUpIdleModeTextPCmd()

 * - SEND DTMF -

 *   asks the phone to send a DTMF string -

 *   RSat::NotifySendDtmfPCmd()

 * - PERFORM CARD APDU -

 *   asks the phone to send an APDU command -

 *   RSat::NotifyPerformCardApduPCmd()

 * - POWER OFF CARD -

 *   closes the session with the card specified in the command -

 *   RSat::NotifyPowerOffCardPCmd()

 * - POWER ON CARD -

 *   starts a session with the card specified in the command -

 *   RSat::NotifyPowerOnCardPCmd()

 * - GET READER STATUS -

 *   requests the status of the card reader specified in the command -

 *   RSat::NotifyGetReaderStatusPCmd()

 * - RUN AT COMMAND -

 *   asks the phone to perform the AT command provided -

 *   RSat::NotifyRunAtCommandPCmd()

 * - LANGUAGE NOTIFICATION -

 *   tells the phone the language in which any text strings from the UICC are written -

 *   RSat::NotifyLanguageNotificationPCmd()

 * - LAUNCH BROWSER -

 *   asks the phone to browse to the supplied URL -

 *   RSat::NotifyLaunchBrowserPCmd()

 * - OPEN CHANNEL -

 *   asks the phone to open a channel -

 *   RSat::NotifyOpenChannelPCmd()

 * - CLOSE CHANNEL -

 *   asks the phone to close a channel previously opened with the OPEN CHANNEL proactive command -

 *   RSat::NotifyCloseChannelPCmd()

 * - RECEIVE DATA -

 *   asks the phone for data from  a channel opened with the OPEN CHANNEL proactive command -

 *   RSat::NotifyReceiveDataPCmd()

 * - SEND DATA -

 *   asks the phone to send data on a channel opened with the OPEN CHANNEL proactive command -

 *   RSat::NotifySendDataPCmd()

 * - GET CHANNEL STATUS -

 *   asks the phone to return the status of a channel opened with the OPEN CHANNEL proactive command -

 *   RSat::NotifyGetChannelStatusPCmd()

 * - SERVICE SEARCH -

 *   RSat::NotifyServiceSearchPCmd()

 * - GET SERVICE INFO -

 *   RSat::NotifyGetServiceInfoPCmd()

 * - DECLARE SERVICE -

 *   RSat::NotifyDeclareServicePCmd()

 * - TIMER MANAGEMENT -

 *   asks the phone to start, stop and read the current value of timers -

 *   RSat::NotifyTimerMgmtPCmd()

 * - PROVIDE LOCAL INFORMATION -

 *   instructs the phone to send local information to the UICC -

 *   RSat::NotifyLocalInfoPCmd()

 * - POLLING INTERVAL -

 *   tells the phone how often the UICC would like to be polled by the phone -

 *   RSat::NotifyPollingIntervalPCmd()

 * - POLLING OFF -

 *   tells the phone not to poll the UICC for proactive commands any more -

 *   RSat::NotifyPollingOffPCmd()

 * - RETRIEVE MULTIMEDIA MESSAGE

 *   asks the phone to store the Multimedia Message received from the Network on UICC-

 *   RSat::NotifyRetrieveMultimediaMsgPCmd()

 * - SUBMIT MULTIMEDIA MESSAGE

 *   asks the phone to submit the Multimedia Message stored in the UICC to the Network-

 *   RSat::NotifySubmitMultimediaMsgPCmd()

 * - DISPLAY MULTIMEDIA MESSAGE

 *   asks the phone to display the Multimedia message to the user-

 *   RSat::NotifyDisplayMultimediaMsgPCmd() 

 * - SET FRAMES

 *   This command instructs the terminal to divide the terminal screen into multiple, scrollable rectangular regions called frames inorder to present multiple information at once-

 *   RSat::NotifySetFramesPCmd()

 * - GET FRAMES STATUS

 *   This command requests the terminal to return a Frames parameters data object-

 *   RSat::NotifyGetFramesStatusPCmd()

 *

 * Note: the phone continuously polls the card, waiting for proactive commands.

 * However, the polling process is hidden from the ETelSat API - simply request

 * notification and wait for the commands.

 */

    {

public:

    IMPORT_C RSat();

    IMPORT_C TInt Open(RPhone& aPhone);

    IMPORT_C void Close();

    IMPORT_C void NotifyProactiveSimSessionEnd(TRequestStatus& aReqStatus) const;

    IMPORT_C void NotifyProactiveSimSessionStart(TRequestStatus& aReqStatus) const;

    class TSatBase

    /**

    Base class for all the (U)SAT ETel API parameters.

    There may be several versions of a parameter.  Parameter classes are named

    'name version number', such as RSat::TGetInkeyV1 and RSat::TGetInkeyV2.

    Both of these classes are used with the "GET INKEY" proactive command. They

    hold similar information but are designed for use with different versions

    of the (U)SAT ETel API. Version 2 contains the version 1 class plus extra

    information.  A third version would contain version 2 plus extra

    information, etc.

    In classes derived from RSat::TSatBase, the base class holds the class's

    version number.  The version number is a value from RSat::TSatVersion.

    Each value in RSat::TSatVersion describes the versions of Symbian OS with

    which they are used.

    You never need to set the version number; the class's constructor does

    this. Generally, RSat clients do not need to read the version number.

    The TSY can use RSat::TSatBase::ExtensionId() to return the version number.

    A typical situation is this:  the TSY is passed a (U)SAT ETel API parameter

    in a descriptor.  The TSY does not know which version it has been given so

    it should guess. For example, it could unpack the descriptor into the

    latest version of the parameter then call RSat::TSatBase::ExtensionId() to

    retrieve the actual version number.  If the TSY chose the incorrect version

    number then the descriptor can be unpacked into the correct parameter class.

    */

        {

    public:

        IMPORT_C TInt ExtensionId() const;

    protected:

        TSatBase();

    protected:

        /** The extension identifier or version number. */

        TInt iExtensionId;

        };

    class TSatPCmdBase : public TSatBase

    /**

    Base class for all the (U)SAT ETel API proactive command classes.

    TSatPCmdBase inherits from TSatBase and is the base class for all the (U)SAT

    ETel API proactive command classes, for which it holds the associated

    proactive command number.

    */

        {

    public:

        IMPORT_C TUint8 PCmdNumber() const;

        IMPORT_C TInt SetPCmdNumber(TUint8 aNumber);

    protected:

        TSatPCmdBase();

    protected:

        /** Proactive command number from 3GPP 31.111 and ETSI TS 102 223.

        Valid range is 0x01 to 0xFE. */

        TUint8 iPCmdNumber;

        };

    enum TSatVersion

    /**

    The version number of a (U)SAT ETel API parameter,

    returned by RSat::TSatBase::ExtensionId().

    @see RSat::TSatBase

    */

        {

        KSatVersionNotSet=-1,   //< (U)SAT version has not been set yet

        KSatV1=1,               //< API version 1, (U)SAT API delivered by v6.1 and v7.0.

        KSatV2=2,               //< API version 2, (U)SAT API delivered by 7.0s

        KSatV3=3,               //< API version 3, (U)SAT API delivered by v8.0a, v8.0b, v8.1a, v8.1b.

   		KSatV4=4,				//< API version 4, (U)SAT API delivered by v9.1

        KSatV5=5,				//< API version 5, (U)SAT API delivered by v9.2

        KSatV6=6,				//< API version 6, (U)SAT API delivered by v9.4

        KSatV7=7				//< API version 7, (U)SAT API delivered by v9.5

        };

    enum THelp

    /**

    The UICC may offer help to accompany a GET INKEY, GET INPUT, SET UP MENU or

    SELECT ITEM proactive command. This help is normally text for the phone's

    user.

    Below are links to four member functions.  They request notification for

    the GET INKEY, GET INPUT, SET UP MENU or SELECT ITEM proactive commands.

    When they complete, an object is returned containing the proactive

    command's details.  This includes an RSat::THelp that states whether help

    is available for the command.

    It is up to you whether you tell the user that help is available, and

    whether to display the help should the user ask for it. The proactive

    command does not contain the help; it only indicates whether help is

    available with RSat::THelp.  The process of getting help depends upon the

    proactive command; see the links to the member functions below for details.

    @see RSat::NotifyGetInkeyPCmd()

    @see RSat::NotifyGetInputPCmd()

    @see RSat::NotifySetUpMenuPCmd()

    @see RSat::NotifySelectItemPCmd()

    */

        {

        EHelpNotSet,        //< Initialization value used within constructor(s).

        EHelpAvailable,    //< Help information available to the user.

        ENoHelpAvailable    //< No help information is available to the user.

        };

    enum TTimeUnit

    /**

    Describes the units in RSat::TDuration.

    @see RSat::TDuration

    */

        {

        ETimeUnitNotSet,    //< Initialization value used within constructor(s).

        ENoDurationAvailable,     //< No duration has been provided. The ME should default to general beep.

        EMinutes,    //< The duration is expressed in minutes.

        ESeconds,     //< The duration is expressed in seconds.

        ETenthsOfSeconds    //< The duration is expressed in tenths of seconds.

        };

    struct TDuration

    /** Class used in RSat whenever a measure of duration is required. */

        {

        TTimeUnit iTimeUnit;    //< Unit used to encode the duration in iNumOfUnits

        TUint8 iNumOfUnits;     //< Valid range is 1 to 255.

        };

    enum TDeviceId

    /** Some proactive commands are aimed at particular devices.  The device will be on of those defined here. */

        {

        KDeviceIdNotSet         =-1,      //< Initialisation value

        KKeypad                 =0x01,    //< The destination device for the proactive command is the keypad.

        KDisplay                =0x02,    //< The destination device for the proactive command is the display.

        KEarPiece               =0x03,    //< The destination device for the proactive command is the earpiece.

        KAdditionalCardReader0  =0x10,    //< The destination device for the proactive command is the additional card reader 0.

        KAdditionalCardReader1  =0x11,    //< The destination device for the proactive command is the additional card reader 1.

        KAdditionalCardReader2  =0x12,    //< The destination device for the proactive command is the additional card reader 2.

        KAdditionalCardReader3  =0x13,    //< The destination device for the proactive command is the additional card reader 3.

        KAdditionalCardReader4  =0x14,    //< The destination device for the proactive command is the additional card reader 4.

        KAdditionalCardReader5  =0x15,    //< The destination device for the proactive command is the additional card reader 5.

        KAdditionalCardReader6  =0x16,    //< The destination device for the proactive command is the additional card reader 6.

        KAdditionalCardReader7  =0x17,    //< The destination device for the proactive command is the additional card reader 7.

        KChannel1               =0x21,    //< The destination device for the proactive command is the channel 1.

        KChannel2               =0x22,    //< The destination device for the proactive command is the channel 2.

        KChannel3               =0x23,    //< The destination device for the proactive command is the channel 3.

        KChannel4               =0x24,    //< The destination device for the proactive command is the channel 4.

        KChannel5               =0x25,    //< The destination device for the proactive command is the channel 5.

        KChannel6               =0x26,    //< The destination device for the proactive command is the channel 6.

        KChannel7               =0x27,    //< The destination device for the proactive command is the channel 7.

        KUICC                   =0x81,    //< The destination device for the proactive command is the UICC.

        KME                     =0x82,    //< The destination device for the proactive command is the Mobile Equipment, typically a phone.

        KNetwork                =0x83     //< The destination device for the proactive command is the network.

        };

	/**

	Specifies the text coding scheme for RSat buffers. It may be used in

	conjunction with any RSat buffer to indicate the coding scheme used.

	(See ETSI TS 102 223 V5.9.0 section 8.15.)

	*/

	enum TSatTextCoding

		{

		/** 7-bit packed coding */

		E7bitPacked,

		/** 7-bit unpacked (i.e. 8-bit) coding */

		E7bitUnpacked,

		/** 16-bit Unicode (UCS-2) coding */

		E16bitUCS2

		};

	/**

	@see RSat::TTextString

	*/

	enum {KTextStringMaxSize=250};

    /** Generic Text String

    This text string definition is to be used through the API where a text

    string is required. Text string should be presented to the client in

    unicode format. This type can be used in envelope commands, proactive

    commands and terminal response.

    @see RSat::KTextStringMaxSize

    */

    typedef TBuf<KTextStringMaxSize> TTextString;

    // Alpha Identifier

    /**

    @see RSat::TAlphaIdBuf

    @see RSat::TAlphaId

	@see RMobileCall::KAlphaIdMaxSize

	*/

    enum {KAlphaIdMaxSize=254};

    /**

    Buffer containing the alpha identifier in the proactive command sent from the ICC.

	@see RSat::TAlphaId

	@see RMobileCall::TAlphaIdBuf

    */

    typedef TBuf<KAlphaIdMaxSize> TAlphaIdBuf;

    /**

    Indicates the status of the alpha ID to the client.  It can be present or

    not present.  If it is present, then it can contain data (typically text)

    or it can be a null object.

    @see RSat::TAlphaId

    */

    enum TAlphaIdStatus

        {

        EAlphaIdNotSet,     //< Value used at initialisation

        EAlphaIdProvided,   //< The alpha ID was provided by the ICC and contains data, typically text.

        EAlphaIdNull,       //< The alpha ID was provided by the ICC but was a null object.

        EAlphaIdNotPresent  //< No alpha ID provided by the ICC.

        };

    /**

    Proactive commands can include some text called an 'alpha identifier'.

    The meaning of the text depends upon the proactive command; see each

    command's description for more details.

    In Symbian OS, details of each proactive command are encapsulated in a

    class.  Each class includes an RSat::TAlphaId.  Inside this, iStatus

    contains the status of the command's alpha identifier:

    If iStatus is RSat::EAlphaIdProvided then RSat::TAlphaId::iAlphaId contains

    the proactive command's alpha identifier text.  The description of each

    proactive command will tell you what to do with the text.

    If iStatus is RSat::EAlphaIdNull then the proactive command's alpha

    identifier is an empty string.  RSat::TAlphaId::iAlphaId contains nothing.

    This commonly indicates that nothing should be display to the user while

    the proactive command is executed; see the proactive command's description.

    If iStatus is RSat::EAlphaIdNotPresent then the proactive command did not

    contain an alpha identifier.  This is commonly indicates that you can

    display whatever you like to the user while the proactive command is

    executed; see the proactive command's description.

    It is intended by ETSI / 3GPP to be a short identifier of one or two words.

    However the maximum buffer size is 254 in this API.

    */

    struct TAlphaId

        {

        TAlphaIdStatus iStatus; //< The status of the alpha ID.

        TAlphaIdBuf iAlphaId; 	//< The alpha ID's text.  Only valid if iStatus is RSat::EAlphaIdProvided.

        };