Default constructor

At the beginning of a ETelSat API session, you must tell the UICC what SAT features the phone supports. Do this after creating and opening an RSat session. This is a three-part process:

Once you have told the UICC of the profile:

Initialises RSat . called as part of the two-phase construction (typical to Symbian OS).

Default destructor

The SET UP EVENT LIST proactive command gives the phone a list of events that may occur to the phone. The event list may include a change of access technology, user action, browser termination and more. You must inform the UICC when an event on the list occurs by calling RSat::EventDownload() . If the event is not on the list then you do not need to notify the UICC.

See RSat::NotifySetUpEventListPCmd() for more information.

This method retrieves the CLUT (Colour Lookup Table) for an image instance designated by aInstanceNumber. This is used when displaying icons; see RSat::GetImageInstance() .

The format of the CLUT is described in ETSI TS 131 102; see Annex B.

To cancel an outstanding request, call RTelSubSessionBase::CancelAsyncRequest( ESatGetClut )

A proactive command may be accompanied by an icon to be displayed to the user; see RSat::TIconId . The command does not contain the icon. Instead, it contains an icon identifier, RSat::TIconId::iIdentifier . When you want to display an icon, the first step is to pass RSat::TIconId::iIdentifier to RSat::GetIcon() to retrieve the icon's EF record from the UICC.

The EF record describes the icon. The UICC may store several images that represent the same icon. Images can differ in size and coding scheme. Each is listed and described in the EF record. Analyse the EF record and choose a suitable image, then call RSat::GetImageInstance() to retrieves the actual image data to display.

If none of the images are suitable then see the error conditions described in RSat::TIconId .

The EF record is described in ETSI TS 131 102; search for EFimg or "Contents of files at the DFGRAPHICS level"

To cancel an outstanding request, call RTelSubSessionBase::CancelAsyncRequest( ESatGetIcon )

This method retrieves an icon's image data from the UICC. The data is returned in aInstance.

For colour images, you will also need to retrieve a Colour LookUp Table (CLUT). Use RSat::GetClut() for this.

Before calling this method, you must have called RSat::GetIcon() to retrieve the icon's EF record.

aInstanceInfo is a RSat::TInstanceInfoV3Pckg (a packaged RSat::TInstanceInfoV3 ) containing details of the image you would like to get. This includes the image's size. aInstance should be the size of the image.

The EF record is described in ETSI TS 131 102; search for EFimg or "Contents of files at the DFGRAPHICS level". The format of both image data and CLUT is also described in ETSI TS 131 102; see Annex B.

To cancel an outstanding request, call RTelSubSessionBase::CancelAsyncRequest( ESatGetImageInstance )

At the beginning of a ETelSat API session, you must tell the UICC what SAT features the phone supports. Do this after creating and opening an RSat session. This is a three-part process:

Once you have told the UICC of the profile:

This method can be used to retrieve more details about the channel after the channel is opened. PCmd type should be set to RSat::ECsBearer , RSat::EGprsBearer , RSat::ELocalLinksBearer or RSat::EUiccServerMode (or another enum defined in RSat::TOpenChannelType .

This method retrieves the Provisioning Reference File designated by aFileRef. Call this when handling a LAUNCH BROWSER proactive command.

Sends a MENU SELECTION envelope command to the UICC. This is related to a SET UP MENU proactive command. SET UP MENU asks for a menu to be added to the phone's menu system. If a user chooses an item from this menu, then inform the UICC of the user's selection with RSat::MenuSelection() .

This method allows the client to pass the MM1_notification.REQ message to the UICC upon receiving the MMS notification intended for the UICC. The MMS Notification download envelope command details are passed in the packaged version of TMmsNotificationDownloadV6 in the aMmsNotificationDownload parameter.

To cancel a previously placed RSat::MmsNotificationDownload request, call RTelSubSessionBase::CancelAsyncRequest(ESatMmsNotificationDownload)

To cancel a previously placed RSat::MmsTransferStatus request, call RTelSubSessionBase::CancelAsyncRequest(ESatMmsTransferStatus)

In SAT-enabled phones, the UICC can request control of outgoing calls or activation of PDP Contexts. The phone's TSY passes the call's parameters to the UICC, such as the telephone number, or in the case of PDP activation PDP parameters. The UICC will allow the call (activation of the context), disallow the call (activation of the context), or it will modify the call's (pdp context activation) parameters. This happens without the RSat client's involvement. However, RSat clients can be informed when call control has taken place the by calling RSat::NotifyCallControlRequest() .

This notification completes when a client requests a call set up or PDP contedxt activation which is modified by the UICC.

You may receive this notification following your attempt to send an SMS in response to a SET UP CALL proactive command (call) or OPEN CHANNEL proactive command (PDP context). You may also receive it when another application attempts to set up a call or activate PDP context.

Upon completion, for a call, aCallControlDetails contains the details of the new action to be performed, instead of the original call set up; for a PDP context activation, aPdpParameters contain the parameters that shall be utilized instead or original PDP activation request.

This notification completes when a client (not necessarily the SAT client) requests a Cell Broadcast data download. Upon completion the envelope command details will be returned in a RSat::TCbDownloadV3Pckg , a packaged version of the RSat::TCbDownloadV3 class in the aCbDownload.

This method requests notification when a CLOSE CHANNEL proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The CLOSE CHANNEL command requests that the phone closes a channel previously opened with the OPEN CHANNEL proactive command. The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

The command includes:

When you open a channel following an OPEN CHANNEL command, you chose a channel identifier - a number from 1 to 7. When you inform the UICC that you opened a channel successfully, you tell the UICC which number you have chosen to represent the channel. The UICC includes this number in subsequent CLOSE CHANNEL commands so that you know which channel to close.

See the description of the CLOSE CHANNEL command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Once you have attempted to close the channel, give your response to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TCloseChannelRspV2Pckg (a packaged TCloseChannelRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TCloseChannelRspV3 etc).

This method requests notification when a DECLARE SERVICE proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

You need to give a response to command back to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TDeclareServiceRspV2Pckg (a packaged TDeclareServiceRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TDeclareServiceRspV3 etc).

The DISPLAY MULTIMEDIA MESSAGE command tells the phone to Display the Multimedia file to the User .

This asynchronous request is a notifier that completes when the UICC issues a DISPLAY MULTIMEDIA MESSAGE PCmd. Upon completion the proactive command details will be returned in a packaged version of TDisplayMultimediaMessageV6 in the aPCmd parameter.

To cancel a previously placed RSat::NotifyDisplayMultimediaMsgPCmd request, call RTelSubSessionBase::CancelAsyncRequest(ESatNotifyDisplayMultimediaMsgPCmd)

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions up to and including 9.4, pass RSat::TerminalRsp() a RSat::TDisplayMultimediaMessageRspV6Pckg (a packaged RSat::TDisplayMultimediaMessageRspV6 ). For later versions of Symbian OS, check for an updated API (RSat::TDisplayMultimediaMessageRspV7 etc).

This method requests notification when a DISPLAY TEXT proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The DISPLAY TEXT command instructs the terminal to display a text message, and/or an icon. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

Once you have dealt with the command, you must give your response to the DISPLAY TEXT command. In Symbian OS versions up to and including 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TDisplayTextRspV1Pckg (a packaged RSat::TDisplayTextRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TDisplayTextRspV2 etc).

This method requests notification when a GET CHANNEL STATUS proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The GET CHANNEL STATUS command asks the phone to return the status of a channel opened with the OPEN CHANNEL proactive command. Both of these commands are described fully in ETSI TS 102 223 and 3GPP TS 31.111.

When you open a channel following an OPEN CHANNEL command, you chose a channel identifier - a number from 1 to 7. When you inform the UICC that you opened a channel successfully, you tell the UICC which number you have chosen to represent the channel. The UICC includes this number in subsequent GET CHANNEL STATUS commands so that you know which channel's status to return.

Symbian OS support for this command is available from v7.0s onwards.

You need to return the channel status or an error to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TGetChannelStatusRspV2Pckg (a packaged TGetChannelStatusRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TGetChannelStatusRspV3 etc).

GET FRAMES STATUS command requests the terminal to return a Frames parameters data object.

This asynchronous request is a notifier that completes when the UICC issues a GET FRAMES STATUS PCmd. Upon completion the proactive command details will be returned in a packaged version of TGetFramesStatusV6 in the aPCmd parameter.

To cancel a previously placed RSat::NotifyGetFramesStatusPCmd request, call RTelSubSessionBase::CancelAsyncRequest(ESatNotifyGetFramesStatusPCmd)

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions up to and including 9.4, pass RSat::TerminalRsp() a RSat::TGetFramesStatusRspV6Pckg (a packaged RSat::TGetFramesStatusRspV6 ). For later versions of Symbian OS, check for an updated API (RSat::TGetFramesStatusRspV7 etc).

This method requests notification when a GET INKEY proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The GET INKEY command instructs you to display text and/or an icon and to expect the user to enter a single character. The command states the required response:

The response entered by the user shall be passed back to the UICC. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

Once you have dealt with the command, you must give your response to the GET INKEY command. For Symbian OS v6.1 or v7.0 pass RSat::TerminalRsp() a RSat::TGetInkeyRspV1Pckg (a packaged TGetInkeyRspV1 ). For versions up to and included v8.1a and v8.1b use RSat::TGetInkeyRspV2Pckg (a packaged RSat::TGetInkeyRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TGetInkeyRspV3 etc).

This method requests notification when a GET INPUT proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The GET INPUT command instructs you to display text and/or an icon and to expect the user to enter a string. Pass the string back to the UICC. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

Once you have dealt with the command, you must give your response to the GET INPUT command. For Symbian OS versions up to and including v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TGetInputRspV1Pckg (a packaged RSat::TGetInputRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TGetInputRspV2 etc).

This method requests notification when a GET READER STATUS proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The GET READER STATUS command requests the status of the card reader specified in the command. The command is described fully in ETSI TS 102 223. Symbian OS support for this command is available from v7.0s onwards.

The command can request two types of information:

Once you have tried to get the status, you must give your response to the GET READER STATUS command. This should include the APDU command results, if there are any. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TGetReaderStatusRspV2Pckg (a packaged RSat::TGetReaderStatusRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TGetReaderStatusRspV3 etc).

This method requests notification when a GET SERVICE INFO proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

You need to give a response to command back to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TGetServiceInfoRspV2Pckg (a packaged TGetServiceInfoRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TGetServiceInfoRspV3 etc).

This method requests notification when a LANGUAGE NOTIFICATION proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The LANGUAGE NOTIFICATION command tells the phone the language in which any text strings from the UICC are written. This includes text within proactive commands or envelope command responses. The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111. Symbian OS support for this command is available from v7.0s onwards.

The command contains a flag, RSat::TLanguageNotificationV2::iNotificationType , that describes the command's purpose:

Once you have dealt with the command, you must give your response to the LANGUAGE NOTIFICATION command. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TLanguageNotificationRspV2Pckg (a packaged TLanguageNotificationRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TLanguageNotificationRspV3 etc).

This method requests notification when a LAUNCH BROWSER proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The LAUNCH BROWSER command requests that the phone browses to the supplied URL. The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111. Symbian OS support for this command is available from v7.0s onwards.

Handling the command is a four-stage process:

Step one is to ask the user for their permission to launch the browser. The LAUNCH BROWSER command provides two parameters for this: an alpha identifier ( RSat::TLaunchBrowserV2::iAlphaId ) and an icon ( RSat::TLaunchBrowserV2::iIconId ). You can display these to help the user make a choice.

Step two: examine the rest of the command and decide whether you can proceed. The command includes:

Step three is to tell the UICC your intentions. You must do this before launching the browser. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TLaunchBrowserRspV2Pckg (a packaged RSat::TLaunchBrowserRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TLaunchBrowserRspV3 etc).

Finally, you can launch the browser.

This method requests notification when a PROVIDE LOCAL INFORMATION proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

Support for this command is only available from v7.0s of Symbian OS onwards.

The PROVIDE LOCAL INFORMATION command instructs the phone to send local information to the UICC. The command is described fully in ETSI TS 102 223, 3GPP2 C.S0035-0 and 3GPP TS 31.111. Briefly, though, the command includes:

The type of information depends upon the network on which the phone is running. For GSM/WCDMA networks, read 3GPP TS 31.111; for CDMA networks read 3GPP2 C.S0035-0. ETSI TS 102 223 only provides generic information about the PROVIDE LOCAL INFORMATION command.

Provide the information (or an error code) in the format described in the specifications. In Symbian OS versions up to and including 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TLocalInfoRspV3Pckg (a packaged RSat::TLocalInfoRspV3 ). For later versions of Symbian OS, check for an updated API (RSat::TLocalInfoRspV4 etc).

In SAT-enabled phones on GSM/WCDMA networks, the UICC can control who SMS messages are sent to. The phone's TSY passes the UICC the SMS's parameters, such as the telephone number of the recipient. The UICC will allow the message, disallow the message, or it modify the delivery parameters. This happens without the RSat client's involvement. However, RSat clients can be informed when SMS control has taken place the by calling RSat::NotifyMoSmControlRequest() .

This notification completes when a client tries to send an SMS which is then modified by SMS control.

You may receive this notification following your attempt to send an SMS in response to a SEND SHORT MESSAGE proactive command. You may also receive it when another application attempts to send an SMS.

Upon completion, aMoSmDetails contains the details of the new SMS operation to be performed instead of the original request.

This method requests notification when an OPEN CHANNEL proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The OPEN CHANNEL command asks the phone to open a channel. You must inform the UICC whether you were successful. If so, subsequent proactive commands ask the phone to read or write data to the channel, to get the channel's status and to close the channel.

The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111. The documents also describe these related commands:

The OPEN COMMAND defines the channel that should be opened. Typical examples are a channel to an IP address, an Internet domain name, a local serial connection etc.

The command is returned in a class that inherits from RSat::TOpenChannelBaseV2 . When you receive an OPEN CHANNEL command, look at its RSat::TOpenChannelBaseV2::iPCmdType field. This determines the type of bearer to use for the channel. There are three types:

The description of the "TOpen..." classes describes their contents and how to set up the channel.

If you successfully open a channel then you must assign it a channel number from 1 to 7. You can have up to seven channels open at once, each opened with a separate OPEN CHANNEL command. You must inform the UICC of your chosen channel number. Subsequent CLOSE CHANNEL, SEND DATA, RECEIVE DATA and GET CHANNEL STATUS commands from the UICC will include a channel number from those you have returned to the UICC.

If you do not successfully open a channel then return an error code as recommended in ETSI TS 102 223 and 3GPP TS 31.111.

Whether you are successful or unsuccessful, respond to the OPEN CHANNEL command as follows: for Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TOpenChannelRspV2Pckg (a packaged RSat::TOpenChannelRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TOpenChannelRspV3 etc).

This method requests notification when a PERFORM CARD APDU proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The PERFORM CARD APDU command asks the phone to send an APDU command to the card specified in the command. The command is described fully in ETSI TS 102 223. Symbian OS support for this command is available from v7.0s onwards.

The command includes:

Once you have dealt with the APDU command, you must give your response to the PERFORM CARD APDU command. This should include the APDU command results, if there are any. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TPerformCardApduRspV2Pckg (a packaged RSat::TPerformCardApduRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TPerformCardApduRspV3 etc).

This method requests notification when a PLAY TONE proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The PLAY TONE command instructs you to play a tone. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

See the description of the PLAY TONE command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Once you have dealt with the command, you must give your response to the PLAY TONE command. For Symbian OS v6.1 or v7.0 pass RSat::TerminalRsp() a RSat::TPlayToneRspV1Pckg (a packaged TPlayToneRspV1 ). For versions up to and including v8.1a and v8.1b use RSat::TPlayToneRspV2Pckg (a packaged RSat::TPlayToneRspV2). For later versions of Symbian OS, check for an updated API (RSat::TPlayToneRspV3 etc).

This method requests notification when a POLL INTERVAL proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

Support for this command is only available from v7.0s of Symbian OS onwards.

The POLL INTERVAL command tells the phone how often the UICC would like to be polled by the phone. Each time it is polled, it can pass proactive commands to the phone. The command is described fully in ETSI TS 102 223. The command includes:

It is up to the phone to choose the polling interval; the value in the proactive command is only a request. It should choose the closest acceptable value. The phone should tell the UICC what interval it has chosen to use as follows:

In Symbian OS versions up to and including 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TPollingIntervalRspV3Pckg (a packaged RSat::TPollingIntervalRspV3 ). For later versions of Symbian OS, check for an updated API (RSat::TPollingIntervalRspV4 etc).

This method requests notification when a POLLING OFF proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

Support for this command is only available from v7.0s of Symbian OS onwards.

The POLLING OFF command tells the phone not to poll the UICC for proactive commands any more. The command is described fully in ETSI TS 102 223. The command includes the device for which polling should be turned off - RSat::TPollingOffV3::iDestination .

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions up to and including 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TPollingOffRspV3Pckg (a packaged RSat::TPollingOffRspV3 ). For later versions of Symbian OS, check for an updated API (RSat::TPollingOffRspV4 etc).

This method requests notification when a POWER OFF CARD proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The POWER OFF CARD command closes the session with the card specified in the command. The command is described fully in ETSI TS 102 223. Symbian OS support for this command is available from v7.0s onwards.

Once you have tried to close the session, you must give your response to the POWER OFF CARD command. This should include the APDU command results, if there are any. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TPowerOffCardRspV2Pckg (a packaged RSat::TPowerOffCardRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TPowerOffCardRspV3 etc).

This method requests notification when a POWER ON CARD proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The POWER ON CARD command requests that you start a session with the card specified in the command. The command is described fully in ETSI TS 102 223. Symbian OS support for this command is available from v7.0s onwards.

Once you have tried to start the session, you must give your response to the POWER ON CARD command. This should include the APDU command results, if there are any. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TPowerOnCardRspV2Pckg (a packaged RSat::TPowerOnCardRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TPowerOnCardRspV3 etc).

This method requests notification when a RECEIVE DATA proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The RECEIVE DATA command asks the phone for data from a channel opened with the OPEN CHANNEL proactive command. Both of these commands are described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

The command includes:

When you open a channel following an OPEN CHANNEL command, you chose a channel identifier - a number from 1 to 7. When you inform the UICC that you opened a channel successfully, you tell the UICC which number you have chosen to represent the channel. The UICC includes this number in subsequent RECEIVE DATA commands so that you know which channel to use.

See the description of the RECEIVE DATA command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

You need to give the data or an error to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TReceiveDataRspV2Pckg (a packaged TReceiveDataRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TReceiveDataRspV3 etc).

This method requests notification when a REFRESH proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The REFRESH command is described fully in ETSI TS 102 223. It tells you three main things:

RSat::TRefreshV1::iType indicates any or all of these things. If one or more of the data files on the UICC have changed, a list of the changed files will be given in RSat::TRefreshV1::iFileList . This will be a series of identifiers from RSat::TElementaryFiles . If an application needs to be refreshed, its ID is in RSat::TRefreshV2::iAid .

Any application that deals with UICC data may want to receive notification when files change. For instance, the address book application may want to know if the address book data changes. Hence the procedure for handling REFRESH commands is more complicated than other proactive commands. The following scheme is necessary to allow for multiple clients to process a REFRESH notification:

Your phone's main SAT application decides when other applications receive REFRESH commands. If the main SAT application is in the middle of editing UICC data, it can delay the REFRESH notification to other applications until it has finished editing:

Once you have dealt with a REFRESH command, you must give your response to the UICC. For Symbian OS versions up to and included v8.1a and v8.1b pass a RSat::TRefreshRspV2Pckg (a packaged RSat::TRefreshRspV2) to RSat::TerminalRsp() . For later versions of Symbian OS, check for an updated API (RSat::TRefreshRspV3 etc).

This notification completes when SAT engine indicates that it can complete the required refresh. This is phase 1 of a two phase refresh cycle with RSat::NotifyRefreshPCmd() being phase 2. The TSY should inform the UICC via terminal response should refresh not be possible at this time. This is intended to be used only by the SAT engine.

See RSat::NotifyRefreshPCmd() for more information.

This notification completes when SAT Engine indicates that it can complete the required refresh. This is phase 1 on a two phase refresh cycle with NotifyRefreshPCmd being phase 2. The TSY should inform the UICC via terminal response should refresh not be possible at this time. This is intended to be used only by the SAT Engine.

The RETRIEVE MULTIMEDIA MESSAGE command tells the phone to retrieve a Multimedia file from Network.

This asynchronous request is a notifier that completes when the UICC issues a RETRIEVE MULTIMEDIA MESSAGE PCmd. Upon completion the proactive command details will be returned in a packaged version of TRetrieveMultimediaMessageV6 in the aPCmd parameter.

To cancel a previously placed RSat::NotifyRetrieveMultimediaMsgPCmd request, call RTelSubSessionBase::CancelAsyncRequest(ESatNotifyRetrieveMultimediaMsgPCmd)

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions beginning from 9.4, pass RSat::TerminalRsp() a RSat::TRetrieveMultimediaMessageRspV6Pckg (a packaged RSat::TRetrieveMultimediaMessageRspV6 ). For later versions of Symbian OS, check for an updated API (RSat::TRetrieveMultimediaMessageRspV7 etc).

This method requests notification when a RUN AT COMMAND proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The RUN AT COMMAND command asks the phone to perform the AT command provided. The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111. Symbian OS support for this command is available from v7.0s onwards.

The command includes:

See the description of the RUN AT COMMAND command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Once you have dealt with the command, you must give your response to the RUN AT COMMAND command. This should include the AT response string, if there is one. For Symbian OS versions from v7.0s to v8.1a and v8.1b, pass RSat::TerminalRsp() a RSat::TRunAtCommandV2RspPckg (a packaged TRunAtCommandRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TRunAtCommandRspV3 etc).

This method requests notification when a SELECT ITEM proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SELECT ITEM command provides a set of menu items to be shown to the user. The user can choose one of these menu items. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

Once you have integrated the menu (but before the user has made a selection), you must give your response to the SELECT ITEM command. For Symbian OS versions up to and including v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TSelectItemRspV1Pckg (a packaged TGetInputRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TSelectItemRspV2 etc).

If the user chooses a menu item then inform the UICC with RSat::MenuSelection() . This includes the identifier of the chosen menu item.

You may receive a SELECT ITEM command with no menu! This means that the menu from the previous SELECT ITEM command should be removed; see RSat::TMenuItemBaseV1::IsRemoveMenu() .

This method requests notification when a SEND DATA proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The SEND DATA command asks the phone to send data on a channel opened with the OPEN CHANNEL proactive command. Both of these commands are described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

The command includes:

When you open a channel following an OPEN CHANNEL command, you chose a channel identifier - a number from 1 to 7. When you inform the UICC that you opened a channel successfully, you tell the UICC which number you have chosen to represent the channel. The UICC includes this number in subsequent SEND DATA commands so that you know which channel to use.

See the description of the SEND DATA command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

You need to give a response to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TSendDataRspV2Pckg (a packaged TSendDataRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TSendDataRspV3 etc).

This method requests notification when a SEND DTMF proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SEND DTMF command asks the phone to send a DTMF string. A call must be in progress to send DTMF tones. This command is independent of sending DTMF within the call set up (as defined in the SET UP CALL command) and therefore can be used at any time during a call.

The command is described fully in ETSI TS 102 223. It contains:

See the description of the SEND DTMF command in ETSI TS 102 223 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Once you have dealt with the command, you must give your response to the SEND DTMF command. For Symbian OS v6.1 or v7.0 pass RSat::TerminalRsp() a RSat::TSendDtmfRspV1Pckg (a packaged TSendDtmfRspV1 ). For versions 7.0s, v8.1a and v8.1b use RSat::TSendDtmfRspV2Pckg (a packaged TSendDtmfRspV2). For later versions of Symbian OS, check for an updated API (RSat::TSendDtmfRspV3 etc).

This method requests notification when a SEND SHORT MESSAGE proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SEND SHORT MESSAGE command asks the phone to send an SMS message. Return the response to this request to the UICC.

The command is described in ETSI TS 102 223, with additional information for GSM/WCDMA networks in 3GPP TS 31.111, and for CDMA networks in 3GPP2 C.S0035-0. The command contains:

Display the icon as described in RSat::TIconId . Display the text in the alpha identifier, if there is any. If the alpha identifier is not present in the proactive command then you can display whatever you like while sending the message.

However, if the alpha identifier is present in the proactive command but it is an empty string then do not display anything: just send the message without letting the user know. To help with this, send the message by calling RSat::SendMessageNoLogging() instead of the usual RMobileSmsMessaging::SendMessage(). This avoids the message being logged.

Return the result of the SMS or an error code to the UICC. For Symbian OS versions up to and including v8.1a and 8.1b pass RSat::TerminalRsp() a RSat::TSendSsRspV1Pckg (a packaged TSendSsRspV1 ). For later versions of Symbian OS, check for an updated API ( RSat::TSendSsRspV2 etc).

This method requests notification when a SEND SS proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

This command is only supported on GSM/WCDMA networks. It can be ignored on CDMA networks.

The SEND SS command asks the phone to send a supplementary service request to the network. Return the response to this request to the UICC.

The command is described fully in 3GPP TS 31.111 but does not appear in ETSI TS 102 223. It contains:

See the description of the SEND SS command in 3GPP TS 31.111 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Return the result of the SS request or an error code to the UICC. For Symbian OS versions up to and including v8.1a and 8.1b pass RSat::TerminalRsp() a RSat::TSendSsRspV1Pckg (a packaged TSendSsRspV1 ). For later versions of Symbian OS, check for an updated API ( RSat::TSendSsRspV2 etc).

This method requests notification when a SEND USSD proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

This command is only supported on GSM/WCDMA networks. It can be ignored on CDMA networks.

The SEND USSD command asks the phone to send an Unstructured Supplementary Service Data request to the network. Return the response to this request to the UICC.

The command is described fully in 3GPP TS 31.111. Note that it does not appear in ETSI TS 102 223. It contains:

See the description of the SEND USSD command in 3GPP TS 31.111 for the circumstances under which the alpha identifier's text should be displayed. Display the icon as described in RSat::TIconId .

Return the result of the USSD request or an error code to the UICC. For Symbian OS versions up to and including v8.1a and 8.1b pass RSat::TerminalRsp() a RSat::TSendUssdRspV1Pckg (a packaged TSendUssdRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TSendUssdRspV2 etc).

This method requests notification when a SERVICE SEARCH proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

The command is described fully in ETSI TS 102 223 and 3GPP TS 31.111.

Symbian OS support for this command is available from v7.0s onwards.

You need to give a response to command back to the UICC. For Symbian OS versions from 7.0s to v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TServiceSearchRspV2Pckg (a packaged TServiceSearchRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TServiceSearchRspV3 etc).

SET FRAMES command instructs the terminal to divide the terminal screen into multiple, scrollable rectangular regions called frames inorder to present multiple information at once. It can be applied to entire screen or to an already existing frame, dividing this frame into sub-frames

This asynchronous request is a notifier that completes when the UICC issues a SET FRAMES PCmd. Upon completion the proactive command details will be returned in a packaged version of TSetFramesV6 in the aPCmd parameter.

To cancel a previously placed RSat::NotifySetFramesPCmd request, call RTelSubSessionBase::CancelAsyncRequest(ESatNotifySetFramesPCmd)

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions up to and including 9.4, pass RSat::TerminalRsp() a RSat::TSetFramesRspV6Pckg (a packaged RSat::TSetFramesRspV6 ). For later versions of Symbian OS, check for an updated API (RSat::TSetFramesRspV7 etc).

This method requests notification when a SET UP CALL proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SET UP CALL command asks you to connect a phone call. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

After receiving the command, first look at RSat::TSetUpCallV1::iType to decide whether to make the call. Then you need to ask the user's permission to call. This is the confirmation phase. Display the confirmation alpha ID and icon as described in ETSI TS 102 223.

If the user gives permission, you can dial the number and attempt to connect the call. This is the 'call set up' phase. Display the call setup alpha ID and icon as described in ETSI TS 102 223.

If the call could not be connected, look at RSat::TSetUpCallV1::iType to see whether you should try to dial again. Do not re-dial for longer than RSat::TSetUpCallV1::iDuration .

Once the call has connected, or if the call could not be made and you have finished re-dialling, you must give your response to the SET UP CALL command. For Symbian OS v6.1 or v7.0 pass RSat::TerminalRsp() a RSat::TSetUpCallRspV1Pckg (a packaged TSetUpCallRspV1 ). For versions up to and including v8.1a and v8.1b use RSat::TSetUpCallRspV2Pckg (a packaged RSat::TSetUpCallRspV2 ). For later versions of Symbian OS, check for an updated API (RSat::TSetUpCallRspV3 etc).

This method requests notification when a SET UP EVENT LIST proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SET UP EVENT LIST command gives the phone a list of events about which the UICC is interested in receiving notification. The event list may include such things as a change of access technology, user action, browser termination and more. You must inform the UICC when an event on the list occurs by calling RSat::EventDownload() . If the event is not on the list then you do not need to notify the UICC.

RSat::TSetUpEventListV1::iEvents field contains the list of events in the form of flags from RSat::TEventList . When a flagged event occurs, notify the UICC by passing RSat::EventDownload() the appropriate flag. Many events require you to supply information about the event.

The events, their flags and any additional information required by the UICC are shown below. Most events are described in the "Envelope Commands (Event Download)" section of ETSI TS 102 223. 3GPP TS 31.111 contains additional detail for certain events on GSM/WCDMA networks.

As an alternative to the above, the SET UP EVENT LIST command may cancel the previous command. It does this by setting the command's RSat::TSetUpEventListV1::iType to RSat::ERemoveExistingEventList instead of RSat::EUpdateEventList .

You must give your response to the command after you receive it. In Symbian OS versions up to and including 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TSetUpEventListRspV1Pckg (a packaged TSetUpEventListRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TSetUpEventListRspV2 etc).

This method requests notification when a SET UP IDLE MODE TEXT proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SET UP IDLE MODE TEXT command provides text (and optionally an icon) to be displayed when the phone is idle. The presentation style is not defined by this command; that is left to the phone designer. The command is described fully in ETSI TS 102 223.

Two types of command can be sent by the UICC:

Once you have dealt with the command, you must give your response to the SET UP IDLE MODE TEXT command. For Symbian OS versions up to and including v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TSetUpIdleModeTextRspV1Pckg (a packaged RSat::TSetUpIdleModeTextRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TSetUpIdleModeTextRspV2 etc).

This method requests notification when a SET UP MENU proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is competed. Unpack the command to examine its contents.

The SET UP MENU command provides a set of menu items to be integrated with the phone's menu system. The user can choose one of these menu items at their own discretion. The command is described fully in ETSI TS 102 223. Briefly, though, the command includes:

Once you have integrated the menu (but before the user has made a selection), you must give your response to the SET UP MENU command. For Symbian OS versions up to and including v8.1a and v8.1b pass RSat::TerminalRsp() a RSat::TSetUpMenuRspV1Pckg (a packaged TGetInputRspV1 ). For later versions of Symbian OS, check for an updated API (RSat::TSetUpMenuRspV2 etc).

If the user chooses a menu item then inform the UICC with RSat::MenuSelection() . This includes the identifier of the chosen menu item.

You may receive a SET UP MENU command with no menu! This means that the menu from the previous SET UP MENU command should be removed; see RSat::TMenuItemBaseV1::IsRemoveMenu() .

Cancels notification for a SET UP MENU proactive command.

This notification completes when a client (not necessarily the SAT client) requests a SMS-PP data download. Upon completion the envelope command details will be returned in a RSar::TSmsPpDownloadV3Pckg, a packaged version of the RSat::TSmsPpDownloadV3 class in the aSmsPpDownload.

The SUBMIT MULTIMEDIA MESSAGE command tells the phone to Submit a Multimedia file to the Network.

This asynchronous request is a notifier that completes when the UICC issues a SUBMIT MULTIMEDIA MESSAGE PCmd. Upon completion the proactive command details will be returned in a packaged version of TSubmitMultimediaMessageV6 in the aPCmd parameter.

To cancel a previously placed RSat::NotifySubmitMultimediaMsgPCmd request, call RTelSubSessionBase::CancelAsyncRequest(ESatNotifySubmitMultimediaMsgPCmd)

Once you have dealt with the command, you must give your response to the UICC. In Symbian OS versions beginning from 9.4, pass RSat::TerminalRsp() a RSat::TSubmitMultimediaMessageRspV6Pckg (a packaged RSat::TSubmitMultimediaMessageRspV6 ). For later versions of Symbian OS, check for an updated API (RSat::TSubmitMultimediaMessageRspV7 etc).

The phone provides timers for the UICC. Using the TIMER MANAGEMENT proactive command, the UICC can start, stop and read the current value of a timer. Receive these commands with RSat::NotifyTimerMgmtPCmd() , then start, stop or read a timer as requested. Timers are started with a particular value. When this counts down to zero, send a TIMER EXPIRATION envelope command to the UICC with RSat::NotifyTimerExpiration() .

Each TIMER MANAGEMENT proactive command includes an ID that identifiers the timer. You must manage up to 8 timer for the UICC. When a timer expires, pass the ID of the timer to the UICC in aTimerExpiration.

Support for this command is only available from v7.0s of Symbian OS onwards.

This method requests notification when a TIMER MANAGEMENT proactive command is sent by the UICC. When the request completes, the command is placed into aPCmd and the aReqStatus is completed. Unpack the command to examine its contents.

Support for this command is only available from v7.0s of Symbian OS onwards.

The phone provides timers for the UICC. Using proactive commands, the UICC can start, stop and read the current value of timers. Timers are started with a particular value. When this counts down to zero, send a Timer Expiration envelope command to the UICC; see RSat::NotifyTimerExpiration() . You must manage up to 8 timers for the UICC.

The command is described fully in ETSI TS 102 223, 3GPP2 C.S0035-0 and 3GPP TS 31.111. Briefly, though, TIMER MANAGEMENT commands are of three types:

Each command includes a timer identifier, RSat::TTimerMgmtV3::iTimerId , so that you know which timer to use.

After you have tried to stop, start or read a timer, respond to the UICC as follows: In Symbian OS versions 7.0s, 8.1a & 8.1b, pass RSat::TerminalRsp() a RSat::TTimerMgmtRspV3Pckg (a packaged TTimerMgmtRspV3 ). For later versions of Symbian OS, check for an updated API (RSat::TTimerMgmtRspV4 etc).

This notification completes when the TSY has finished its handling of a proactive command. This should be used for proactive commands that are handled by the TSY and not by the ETelSat client. It informs the ETelSat client when the TSY has completed the required actions of the command.

This method opens the RSat interface.

You must have previously opened an interface to the phone (either an RPhone or EMobilePhone). Pass the phone session to RSat::Open() .

After opening the RSat session:

This method allows client to report whether refresh can be carried out. This is intended to be used only by the SAT engine.

See RSat::NotifyRefreshPCmd() for more information.

This method sends a SAT SMS without it being logged.

See RSat::NotifySendSmPCmd() for more information.

This method replies to a proactive command. The reply is sent to the UICC. This is a generic method which replies to every proactive command.

Each type of proactive command requires a different response. There are classes to implement the responses for the different commands. To respond to a command, create an instance of the appropriate class, fill in the fields, and then package the object. Then pass the package and the associated proactive command type to RSat::TerminalRsp() .

Indicates that you are ready to receive proactive commands from the UICC. Do not call this until:

This method allows the client to pass a USSD packet to the UICC upon receiving the USSD packet intended for the UICC. The USSD Data Download ENVELOPE command details are passed in the packaged version of TUssdDataDownloadV6 class in the aDes parameter

To cancel a previously placed RSat::UssdDataDownload request, call RTelSubSessionBase::CancelAsyncRequest(ESatUssdDataDownload)

Specifies to the client who should perform the modified action: the client side or the ME Side.

All proactive commands require a response from you to the UICC via the RSat::TerminalRsp() method. Some require a descriptor containing 'additional information', RSat::TAdditionalInfo . The information in this descriptor will depend upon the type of proactive command to which you are responding; see the description of each proactive command.

Besides returning the descriptor, you must indicate the type of additional information by returning a value from RSat::TAdditionalInfoType .

RSat::TAdditionalInfo RSat::TerminalRsp()

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. RSat::TAlphaId

Indicates the validity of the alpha ID from RSat::TCallControlV1::GetAlphaId() .

Bearer Capability Repeat Indicator.

RMobileCall::TBCRepeatIndicator

Addition information provide to the UICC in response to proactive commands. A value from this enumeration should be provided when the general response to a command is RSat::KBearerIndepProtocolError Set the additional information type to RSat::KMeProblem .

Enum values are dictated by ETSI TS 102 223; see the description of the 'Result' data objects.

Part of an OPEN CHANNEL proactive command. Used by RSat::TBearer . Defines the bearer type that you should use to open the channel. RSat::TOpenChannelBaseV2

RSat::TBearerList