<?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 xml:lang="en" id="GUID-B8F07736-F598-59F0-A004-02A8CBE40554"><title>Multimode Stores</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Information can be stored on the phone in a proprietary storage such as an ME-based phonebook or in a standardised storage area such as SMS on SIM or network operator details on a NAM. Multimode telephony provides a number of classes to access these stores. </p> <p>The following table lists the store types; whether the type must be supported by all TSYs or whether it is optional; and whether the type is of potential use in GSM, WCDMA and CDMA modes respectively. </p> <p>The following table describes the store types and the modes with which they can be used. </p> <table id="GUID-8EF6A506-AA9B-5768-BD69-30B82845FDF8"><tgroup cols="5"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/><thead><row><entry>Area</entry> <entry>Required</entry> <entry>GSM</entry> <entry>WCDMA</entry> <entry>CDMA</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-E6D28D2B-5201-569E-881D-1D5A0BDC41B0">SMS message store</xref>  </p> </entry> <entry><p>n</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> </row> <row><entry><p> <xref href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-954142E4-DAF2-5526-988C-C62FB076A5EB">Phone book store</xref>  </p> </entry> <entry><p>n</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> </row> <row><entry><p> <xref href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-94DD9BEF-AA0D-5491-BA84-C4B502AB0E03">Own numbers store</xref>  </p> </entry> <entry><p>n</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> </row> <row><entry><p> <xref href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-3E8A8566-1B25-5C82-B844-41A7F907A11E">Emergency numbers store</xref>  </p> </entry> <entry><p>n</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> <entry><p>y</p> </entry> </row> <row><entry><p> <xref href="GUID-B8F07736-F598-59F0-A004-02A8CBE40554.dita#GUID-B8F07736-F598-59F0-A004-02A8CBE40554/GUID-2871999B-51F4-5B4E-9640-7FE19A9CF9C5">NAM store</xref>  </p> </entry> <entry><p>n</p> </entry> <entry><p>n</p> </entry> <entry><p>n</p> </entry> <entry><p>y</p> </entry> </row> </tbody> </tgroup> </table> <section id="GUID-67D3FCA0-79D1-5841-85FA-D50D13B15FA8"><title>Store base class</title> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore</apiname></xref> is the base class that implements all of the basic operations performed on the stores. </p> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore</apiname></xref> provides functions to: </p> <ul><li id="GUID-CA63E48A-F41E-5AF5-901C-C4BCF5EB855A"><p>get information about the specified store using <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>GetInfo()</apiname></xref>. This information is encapsulated in an <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>TMobilePhoneStoreInfoV1</apiname></xref> object, and includes the store's name, the type of data that it stores, the total number of storage slots and the number of used slots. Particular stores may provide derived types with additional store information. </p> </li> <li id="GUID-BB42851B-0260-5582-959F-9AA21F73163D"><p>read and write specified entries using <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>Read()</apiname></xref> and <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>Write()</apiname></xref>. Each type of store has its own type of entry, but all stores have a common base class <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>TMobilePhoneStoreEntryV1</apiname></xref> </p> </li> <li id="GUID-58C4A16A-A7A8-5C1F-AEA8-7EA303C2AF6F"><p>delete an entry, or all entries, using <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>Delete()</apiname></xref> and <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>DeleteAll()</apiname></xref>. </p> </li> <li id="GUID-E2026651-5B6D-5898-81B0-CA4B52C643C5"><p>be notified of store events, such as entries being added and deleted, using <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>NotifyStoreEvent()</apiname></xref>  </p> </li> </ul> </section> <section id="GUID-E6D28D2B-5201-569E-881D-1D5A0BDC41B0"><title>SMS message store</title> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore</apiname></xref> represents the phone-side storage of incoming and outgoing SMS messages and any associated status reports. Clients use it to read, write and delete SMS messages in the SIM/R-UIM and ME memory. Each physical location of an SMS message store maps to a separate instance of an SMS message store in the TSY. Clients can open handles to each of these stores. Each SMS message in a store has a status that tells the client whether that message was received or sent, read or unread and whether or not it is waiting for or has received a status report. </p> <p>The following SMS-specific types and functions are added by <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore</apiname></xref>: </p> <ul><li id="GUID-E99E0465-E2E9-565E-A793-2F6B549CF0ED"><p>to open an SMS store session for phone-based or ICC-card based storage use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore::Open()</apiname></xref>  </p> </li> <li id="GUID-C3066FF5-B2C9-581D-B913-73BA2E814DC1"><p>SMS store capabilities are returned within <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreInfoV1::iCaps</apiname></xref>. Capabilities combine the generic phone store capabilities of <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreCaps</apiname></xref> and the SMS store-specific capabilities of <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore::TMobileSmsStoreCaps</apiname></xref>. </p> </li> <li id="GUID-22903873-C3CE-5183-99D3-C4D93DFFDEA5"><p>SMS store entries are either <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore::TMobileCdmaSmsEntryV1</apiname></xref> for CDMA or a <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileSmsStore::TMobileGsmSmsEntryV1</apiname></xref> objects for GSM. </p> </li> <li id="GUID-E202CEF4-49AD-5E15-9300-0EF546EDE93B"><p>to retrieve multiple messages in one operation use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CRetrieveMobilePhoneSmsList</apiname></xref> to get the list, a <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CMobilePhoneGsmSmsList</apiname></xref> for GSM or <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CMobilePhoneCdmaSmsList</apiname></xref> for CDMA object. </p> </li> </ul> </section> <section id="GUID-954142E4-DAF2-5526-988C-C62FB076A5EB"><title>Phone book store</title> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore</apiname></xref> allows clients to access phone books that are stored in ICC memory or in non-volatile memory on the phone itself. Address book data is stored in Contacts databases, which allows the Contacts engine API to be used for advanced functionality such as sorting and searching entries. The <xref href="GUID-03F27854-B9FC-5796-AA67-7093DB7AD4B0.dita">Phonebook Synchroniser</xref> updates the Contacts databases with the ICC phonebook data when required. </p> <p>A number of types of phone book are available: </p> <ul><li id="GUID-931E8B42-ECC7-55FA-B310-31309B9FA58C"><p>recently dialled calls </p> </li> <li id="GUID-5C295CB7-C828-5934-8488-2562B686E1CC"><p>missed calls </p> </li> <li id="GUID-AA87B1BF-237A-573B-8AAB-967618CF334B"><p>received calls </p> </li> <li id="GUID-3F829E31-D108-5864-A9AB-C76258A6FEE5"><p>abbreviated dialling numbers (TA, ME and ICC-based) </p> </li> <li id="GUID-3CDDAFE7-2E02-5A49-9C2D-01A11AA13329"><p>voice mailbox numbers </p> </li> <li id="GUID-9EF37454-CA81-59C4-9A8C-97EEBC7C4246"><p>fixed dialling numbers </p> </li> <li id="GUID-A13B7345-5FD7-5691-90C1-D81B0BA11891"><p>service dialling numbers </p> </li> <li id="GUID-55D3032A-14C8-54B5-BF9F-88A76EAE732D"><p>last numbers dialled </p> </li> <li id="GUID-0BA15BAF-F2E6-56AC-B17B-DFC986E18B65"><p>barred dialling numbers </p> </li> </ul> <p>The following phone book-specific types and functions are added by the <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore</apiname></xref> class: </p> <ul><li id="GUID-70168218-174B-5562-9BA8-95F89B9A3BCD"><p>to open a session for a specified type of phone book store, use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore::Open()</apiname></xref>  </p> </li> <li id="GUID-87EFFC0E-DEA3-55E8-889E-085091D99C1A"><p>phone book store information is encapsulated in <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore::TMobilePhoneBookInfoV1</apiname></xref>, derived from <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreInfoV1</apiname></xref>  </p> </li> <li id="GUID-0ADB6048-727D-5F1C-8CB9-8DECB3EB818D"><p>phone book store entries are variably-sized byte streams with different fields delineated by tags. <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore::Read()</apiname></xref> and <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneBookStore::Write()</apiname></xref> read and write respectively a byte streams. It is easier for clients to use the Contacts engine API rather than write their own code to encode and decode the byte streams. </p> </li> </ul> <p><b>Example </b> </p> <p>The following code reads the address information for the last missed call from the missed calls phone book. </p> <codeblock id="GUID-E3B38C5B-47C9-5935-B1D7-17FEF69326A4" xml:space="preserve">HBufC8* CClientApp::LastMissedCallL()

    {

    // Test can read entries from missed calls store

    RMobilePhoneBookStore::TMobilePhoneStoreInfoV1 phoneStoreInfo;

    RMobilePhoneBookStore::TMobilePhoneStoreInfoV1Pckg phoneStoreInfoPckg(phoneStoreInfo);

    TRequestStatus status;

    iMobilePhone.GetPhoneStoreInfo(status, phoneStoreInfoPckg, KETelMeMissedPhoneBook);

    User::WaitForRequest(status);

    User::LeaveIfError(status.Int());

    HBufC8* pbData = 0;

    if ( phoneStoreInfo.iCaps & RMobilePhoneBookStore::KCapsReadAccess)

        {

        // Open session to missed calls store

        RMobilePhoneBookStore pbStoreSession;

        User::LeaveIfError(pbStoreSession.Open(iMobilePhone, KETelMeMissedPhoneBook));

        CleanupClosePushL(pbStoreSession);

        TInt totalEntries = phoneStoreInfo.iUsedEntries;

        if (totalEntries > 0)

            {

            const TInt KAddressBuffer = 200;

            pbData = HBufC8::NewLC(KAddressBuffer);

            TInt numEntries = 1;

            TPtr8 des = pbData->Des();

            pbStoreSession.Read(status, totalEntries, numEntries, des);

            User::WaitForRequest(status);

            User::LeaveIfError(status.Int());

            CleanupStack::Pop(); // pbData

            }

        // Clean up

        CleanupStack::PopAndDestroy(); // calls pbStoreSession.Close()

        }

    return pbData;

    }</codeblock> </section> <section id="GUID-94DD9BEF-AA0D-5491-BA84-C4B502AB0E03"><title>Own numbers store</title> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileONStore</apiname></xref> allows clients to access a store of own numbers. There is one store that holds both own numbers for all modes. </p> <p>The following phone book-specific types and functions are added by <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileONStore</apiname></xref>: </p> <ul><li id="GUID-67286DBA-44B3-5B67-8684-09DC4FDE89AA"><p>to open a session for the own numbers store, use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileONStore::Open()</apiname></xref>  </p> </li> <li id="GUID-38385320-B825-519D-8451-017B3174D705"><p>own number store information is encapsulated in <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileONStore::TMobileONStoreInfoV1</apiname></xref>, derived from <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobilePhoneStore::TMobilePhoneStoreInfoV1</apiname></xref>  </p> </li> <li id="GUID-7B147834-081F-5CCF-A1C4-3008E352834D"><p>own numbers store entries are <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileONStore::TMobileONEntryV1</apiname></xref> objects </p> </li> <li id="GUID-2DDAC1CA-197F-57E4-B354-581E3F5DE3CE"><p>to retrieve all the entries in one operation use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CRetrieveMobilePhoneONList</apiname></xref> to get the list, a <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CMobilePhoneONList</apiname></xref> object. </p> </li> </ul> </section> <section id="GUID-3E8A8566-1B25-5C82-B844-41A7F907A11E"><title>Emergency numbers store</title> <p> <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileENStore</apiname></xref> allows clients to access the list of emergency telephone numbers. </p> <p>A TSY returns one list that has the emergency numbers for all the supported network modes, or if this is not possible, just the emergency numbers for the current mode. </p> <p>The following phone book-specific types and functions are added by <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileENStore</apiname></xref>: </p> <ul><li id="GUID-4F3AA88D-7D70-5082-B3DA-68F6F806D2C4"><p>to open a session for the emergency numbers store, use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileENStore::Open()</apiname></xref>  </p> </li> <li id="GUID-A5987511-0325-570A-B320-76C3B2052EC4"><p>emergency numbers store entries are <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>RMobileENStore::TMobileENEntryV1</apiname></xref> objects </p> </li> <li id="GUID-1F967CBF-FD5A-5F13-A20F-DC3A90A23DD5"><p>to retrieve all the entries in one operation use <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CRetrieveMobilePhoneENList</apiname></xref> to get the list, a <xref href="GUID-018DBDBE-72D5-366A-887C-BDD554F6EB8C.dita"><apiname>CMobilePhoneENList</apiname></xref> object. </p> </li> </ul> <p><b>Example </b> </p> <p>The following code outputs the number for each entry in the store. </p> <codeblock id="GUID-B13515BD-3EF7-5773-BC43-BD321C50DC53" xml:space="preserve">void CClientApp::PrintEmergencyNumbers()

    {

    // Open emergency number store

    RMobileENStore enStore;

    User::LeaveIfError(enStore.Open(iMobilePhone));

    CleanupClosePushL(enStore);

    // Create and start asynchronous emergency number retriever

    CRetrieveMobilePhoneENList* retrieveEnList = CRetrieveMobilePhoneENList::NewL(enStore);

    CleanupStack::PushL(retrieveEnList);

    TRequestStatus status;

    retrieveEnList->Start(status);

    User::WaitForRequest(status);

    User::LeaveIfError(status.Int());

    // Get the list of emergency numbers

    CMobilePhoneENList* enList = retrieveEnList->RetrieveListL();

    CleanupStack::PushL(enList);

    // Print each number

    TInt nEntries = enList->Enumerate();

    RMobileENStore::TMobileENEntryV1 enEntry;

    for (TInt i=0; i<=nEntries; i++)

        {

        enEntry = enList->GetEntryL(i);

        console->Printf(_L("%S\n"),enEntry.iNumber);

        }

    // Clean up

    CleanupStack::PopAndDestroy(3); // enList, retrieveEnList, enStore