Multimode Stores

Store base class

RMobilePhoneStore is the base class that implements all of the basic operations performed on the stores.

RMobilePhoneStore provides functions to:

• get information about the specified store using GetInfo(). This information is encapsulated in an TMobilePhoneStoreInfoV1 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.

• read and write specified entries using Read() and Write(). Each type of store has its own type of entry, but all stores have a common base class TMobilePhoneStoreEntryV1

• delete an entry, or all entries, using Delete() and DeleteAll().

• be notified of store events, such as entries being added and deleted, using NotifyStoreEvent()

SMS message store

RMobileSmsStore 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.

The following SMS-specific types and functions are added by RMobileSmsStore:

• to open an SMS store session for phone-based or ICC-card based storage use RMobileSmsStore::Open()

• SMS store capabilities are returned within RMobilePhoneStore::TMobilePhoneStoreInfoV1::iCaps. Capabilities combine the generic phone store capabilities of RMobilePhoneStore::TMobilePhoneStoreCaps and the SMS store-specific capabilities of RMobileSmsStore::TMobileSmsStoreCaps.

• SMS store entries are either RMobileSmsStore::TMobileCdmaSmsEntryV1 for CDMA or a RMobileSmsStore::TMobileGsmSmsEntryV1 objects for GSM.

• to retrieve multiple messages in one operation use CRetrieveMobilePhoneSmsList to get the list, a CMobilePhoneGsmSmsList for GSM or CMobilePhoneCdmaSmsList for CDMA object.

Phone book store

RMobilePhoneBookStore 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 Phonebook Synchroniser updates the Contacts databases with the ICC phonebook data when required.

A number of types of phone book are available:

• recently dialled calls

• missed calls

• received calls

• abbreviated dialling numbers (TA, ME and ICC-based)

• voice mailbox numbers

• fixed dialling numbers

• service dialling numbers

• last numbers dialled

• barred dialling numbers

The following phone book-specific types and functions are added by the RMobilePhoneBookStore class:

• to open a session for a specified type of phone book store, use RMobilePhoneBookStore::Open()

• phone book store information is encapsulated in RMobilePhoneBookStore::TMobilePhoneBookInfoV1, derived from RMobilePhoneStore::TMobilePhoneStoreInfoV1

• phone book store entries are variably-sized byte streams with different fields delineated by tags. RMobilePhoneBookStore::Read() and RMobilePhoneBookStore::Write() 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.

Example

The following code reads the address information for the last missed call from the missed calls phone book.

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;
    }

Own numbers store

RMobileONStore allows clients to access a store of own numbers. There is one store that holds both own numbers for all modes.

The following phone book-specific types and functions are added by RMobileONStore:

• to open a session for the own numbers store, use RMobileONStore::Open()

• own number store information is encapsulated in RMobileONStore::TMobileONStoreInfoV1, derived from RMobilePhoneStore::TMobilePhoneStoreInfoV1

• own numbers store entries are RMobileONStore::TMobileONEntryV1 objects

• to retrieve all the entries in one operation use CRetrieveMobilePhoneONList to get the list, a CMobilePhoneONList object.

Emergency numbers store

RMobileENStore allows clients to access the list of emergency telephone numbers.

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.

The following phone book-specific types and functions are added by RMobileENStore:

• to open a session for the emergency numbers store, use RMobileENStore::Open()

• emergency numbers store entries are RMobileENStore::TMobileENEntryV1 objects

• to retrieve all the entries in one operation use CRetrieveMobilePhoneENList to get the list, a CMobilePhoneENList object.

Example

The following code outputs the number for each entry in the store.

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
    }

NAM store

RMobileNamStore is used to access Number Assignment Module (NAM) storage. NAM storage stores the parameters used in the operation of CDMA phones. The API assumes that NAMs are stored in phone-side memory.

The v7.0 API encapsulates each NAM entry in an RMobileNamStore::TMobileNamEntryV1 object, which assumes a maximum parameter size of 64 bytes. v8.1 (v4 of the ETelMM API) adds a RMobileNamStore::TMobileNamEntryV4 type, which allows a maximum parameter size of 256 bytes. It also provides identifiers for standard NAM parameters in RMobileNamStore::TStandardNamParameters. The TSY can support and define additional NAM parameters.

There can be only one NAM can be active at a time: functions to read or write usually apply to the currently active NAM.

The following NAM-specific types and functions are added by RMobileNamStore:

• to open a NAM store session use RMobileNamStore::Open()

• NAM store information is encapsulated in RMobileNamStore::TMobileNamStoreInfoV1, derived from RMobilePhoneStore::TMobilePhoneStoreInfoV1

• NAM store entries are RMobileNamStore::TMobileNamEntryV4 objects (RMobileNamStore::TMobileNamEntryV1 in the v1 ETelMM API).

• to specify the active NAM within the NAM store use RMobileNamStore::SetActiveNam()

• to retrieve multiple NAM entries in one operation use CRetrieveMobilePhoneNamList to get the list, a CMobilePhoneNamListV4 object (CMobilePhoneNamList in the v1 ETelMM API).

• to store a new version of an entire list of NAM entries use RMobileNamStore::StoreAllL() (there are two overloads for v1 and v4 APIs).