Multimode Stores

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.

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.

The following table describes the store types and the modes with which they can be used.

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

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 + + + + + +Multimode Stores

The following table describes the store types and the modes with which they can be used.

Area Required GSM WCDMA CDMA

SMS message store

Phone book store

Own numbers store

Emergency numbers store

NAM store

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

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

SMS messaging

\ No newline at end of file