<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-09DCBB19-0285-56DC-996D-B3D876DAAC11" xml:lang="en"><title>What

Are SIM Application Toolikits</title><shortdesc>This section describes the SIM application Toolkits (SAT) and the

APIs available to access them. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This section is aimed at the developers writing SAT engines, which is the

client side implementation of the SAT functionality. The term Clients refers

to the SAT engine in this document. The developers are assumed to have good

knowledge of Symbian platform telephony architecture, 3GPP SAT

specifications and TSY modules. </p>

<section id="GUID-7A670743-FEDD-4888-8952-AC361D593C71"><title>Definitions</title> <dl>

<dlentry>

<dt>SAT</dt>

<dd><p>SIM application toolkit is the software present in the electronic card

of the device. There can be more than one SAT application present on the card. </p> </dd>

</dlentry>

<dlentry>

<dt>ICC</dt>

<dd><p>Integrated circuit card is the electronic card that can store the subscription

details of the user and the network operator related details. </p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-ED67B82D-8C30-4A4E-920A-52C758C21D7F"><title>SIM application toolkit interface</title> <p> <xref href="GUID-25B2D92E-82CE-34EC-A2DC-2973804EEFC3.dita"><apiname>RSat</apiname></xref> provides

an interface to the SIM application toolkits (SAT) stored in an electronic

card (ICC) of the phone through a TSY. </p> <p>The SAT interface is implemented

as a TSY plug-in extension to the telephony server. The SAT defines the protocols,

which instruct the phone to do various tasks such as display a menu item,

add a menu item or create an URL link. The SAT engine request notification

of these messages and they are executed through the TSY. </p> </section>

<section id="GUID-0CB1D922-FCB8-4F00-B69D-A21346877311"><title>Error messages</title> <p>SAT application requires an error

message to be returned when an <xref href="GUID-9BD11817-54AC-5731-98EC-91B0C8686847.dita">envelope</xref> command

or a <xref href="GUID-8D4B8ABF-8ADD-5142-A966-EBD913958B0E.dita">proactive</xref> command

fails. There are two types of error messages </p> <ul>

<li id="GUID-063B6A83-F723-5041-9514-4F31CD553851"><p>basic error message </p> </li>

<li id="GUID-C7C029D2-3F75-5070-8936-79174AAC37CF"><p>extended error message </p> </li>

</ul> <p>The basic error messages are those defined by the ETel core API and

the E32 base API. The extended error codes consists of error codes defined

in ETelSat API, ETelPacket API, ETelMultimode API, ETelCDMA API and those

defined by the licensees. Clients can choose to receive either basic or extended

error codes by using <xref href="GUID-25B2D92E-82CE-34EC-A2DC-2973804EEFC3.dita"><apiname>RTelServer::SetExtendedErrorGranualirity()</apiname></xref>.

The clients receive extended error codes when available, else the basic error

code is returned. </p> </section>

<section id="GUID-74938631-82C2-434E-8A60-1677B2CD8A36"><title> Icons and Images </title> <p>The proactive commands are sometimes

associated with an icon/image which is optional. The icons and images are

stored in the ICC. The command gives and image id to the SAT engines which

uses it to retrieve the elementary file from the ICC using <xref href="GUID-25B2D92E-82CE-34EC-A2DC-2973804EEFC3.dita"><apiname>RSat::GetIcon()</apiname></xref> for

icons and <xref href="GUID-25B2D92E-82CE-34EC-A2DC-2973804EEFC3.dita"><apiname>RSat::GetImageInstance()</apiname></xref> for

image files. The TSY retrieves the file and passes it to the SAT engine. The

SAT engine has to choose an instance, which is best suited for the particular

device and display it. </p> </section>

</conbody></concept>