RMobilePhoneBookStore Class Reference

class RMobilePhoneBookStore : public RMobilePhoneStore

Provides member functions for clients to access phone books that are stored in ICC memory or in non-volatile memory on the phone itself. This sub-session and the member functions within this section must be supported if the TSY indicates that it supports the MobilePhonebookStore functional unit.

Inherits from

Public Member Functions
RMobilePhoneBookStore()
IMPORT_C voidClose()
IMPORT_C TIntOpen(RMobilePhone &, const TDesC &)
IMPORT_C TIntOpen(RMobilePhone &, const TDesC &, const TDesC &)
IMPORT_C voidRead(TRequestStatus &, TInt, TInt, TDes8 &)
IMPORT_C voidWrite(TRequestStatus &, const TDesC8 &, TInt &)
Protected Member Functions
IMPORT_C voidConstructL()
Private Member Functions
RMobilePhoneBookStore(const RMobilePhoneBookStore &)
Inherited Functions
RMobilePhoneStore::BaseConstruct(CMobilePhoneStorePtrHolder *)
RMobilePhoneStore::Delete(TRequestStatus &,TInt)const
RMobilePhoneStore::DeleteAll(TRequestStatus &)const
RMobilePhoneStore::Destruct()
RMobilePhoneStore::GetInfo(TRequestStatus &,TDes8 &)const
RMobilePhoneStore::NotifyStoreEvent(TRequestStatus &,TUint32 &,TInt &)const
RMobilePhoneStore::RMobilePhoneStore()
RMobilePhoneStore::Read(TRequestStatus &,TDes8 &)const
RMobilePhoneStore::Write(TRequestStatus &,TDes8 &)const
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const
RTelSubSessionBase::Blank(const TInt,TReqPriorityType)const
RTelSubSessionBase::Blank(const TInt,TRequestStatus &,TReqPriorityType)const
RTelSubSessionBase::CancelAsyncRequest(TInt)const
RTelSubSessionBase::CancelReq(const TInt,const TInt)const
RTelSubSessionBase::CancelSubSession()const
RTelSubSessionBase::Get(const TInt,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::Get(const TInt,TRequestStatus &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::RTelSubSessionBase()
RTelSubSessionBase::ResetSessionHandle()
RTelSubSessionBase::SessionHandle()const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,TRequestStatus &,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const RFile &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC16 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::Set(const TInt,const TDesC8 &,const TDesC8 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,TDes8 &,const TDesC16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC16 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes16 &,TReqPriorityType)const
RTelSubSessionBase::SetAndGet(const TInt,TRequestStatus &,const TDesC8 &,TDes8 &,TReqPriorityType)const
RTelSubSessionBase::SetSessionHandle(RSessionBase &)
RTelSubSessionBase::SubSessionHandle()
Public Member Enumerations
enumanonymous { KMaxPBIDSize = 15 }
enumTMobilePBFieldTags {
ETagPBNewEntry = 0xA0, ETagPBUniqueId = 0xB0, ETagPBAdnIndex = 0xC0, ETagPBText = 0xC1, ETagPBNumber = 0xC2, ETagPBTonNpi = 0xC3, ETagPBBearerCap = 0xC4, ETagPBAnrStart = 0xC5, ETagPBSecondName = 0xC6, ETagPBGroupName = 0xC7, ETagPBEmailAddress = 0xC8, ETagPBEntryControl = 0xC9, ETagPBHiddenInfo = 0xCA, ETagPBDateTime = 0xCB, ETagPBDuration = 0xCC, ETagPBCallStatus = 0xCD, ETagPBEntryStatus = 0xCE
}
enumTMobilePhoneBookCaps {
KCapsRestrictedWriteAccess = 0x00000001, KCapsSecondNameUsed = 0x00000002, KCapsAdditionalNumUsed = 0x00000004, KCapsGroupingUsed = 0x00000008, KCapsEntryControlUsed = 0x00000010, KCapsEmailAddressUsed = 0x00000020, KCapsBearerCapUsed = 0x00000040, KCapsSynchronisationUsed = 0x00000080
}
enumTMobilePhoneBookLocation { ELocationUnknown, ELocationIccMemory, ELocationPhoneMemory, ELocationExternalMemory, ELocationCombinedMemory }
Inherited Enumerations
RMobilePhoneStore:TMobilePhoneStoreCaps
RMobilePhoneStore:TMobilePhoneStoreInfoExtId
RMobilePhoneStore:TMobilePhoneStoreType
RMobilePhoneStore:TMobileStoreEvent
RTelSubSessionBase:TReqPriorityType
Public Member Type Definitions
typedef TBuf8< KMaxPBIDSize > TMobilePhoneBookIdentity
typedef TPckg< TMobilePhoneBookInfoV1 > TMobilePhoneBookInfoV1Pckg
typedef TPckg< TMobilePhoneBookInfoV2 > TMobilePhoneBookInfoV2Pckg
typedef TPckg< TMobilePhoneBookInfoV5 > TMobilePhoneBookInfoV5Pckg
Inherited Attributes
RMobilePhoneStore::iStorePtrHolder
RTelSubSessionBase::iPtrHolder

Constructor & Destructor Documentation

RMobilePhoneBookStore()

IMPORT_CRMobilePhoneBookStore()

Constructor.

RMobilePhoneBookStore(const RMobilePhoneBookStore &)

RMobilePhoneBookStore(const RMobilePhoneBookStore &)[private]

Parameters

const RMobilePhoneBookStore &

Member Functions Documentation

Close()

IMPORT_C voidClose()
This member function closes the phone book sub-session.
capability
None

ConstructL()

IMPORT_C voidConstructL()[protected]
Constructor.
capability
None

Open(RMobilePhone &, const TDesC &)

IMPORT_C TIntOpen(RMobilePhone &aPhone,
const TDesC &aStore
)

This function opens a RMobilePhoneBookStore sub-session from a previously opened RMobilePhone sub-session. The name of the phone book to open is passed in the aStore parameter. The type of valid phone books can be obtained by RMobilePhone::GetPhoneStoreInfo().

Parameters

RMobilePhone & aPhoneThe opened RMobilePhone sub-session
const TDesC & aStoreThe name of the phone book to open.

Open(RMobilePhone &, const TDesC &, const TDesC &)

IMPORT_C TIntOpen(RMobilePhone &aPhone,
const TDesC &aStore,
const TDesC &aMode
)

This method opens a RMobilePhoneBookStore subsession from RMobilePhone.

This API method overloads the normal RMobilePhoneBookStore::Open. The phonebook mode is indicated by the aMode parameter, which allows the client to distinguish between the different sets of phonebooks that can be present on the ICC or ME side. E.g. a client can open both the GSM ADN phonebook and the USIM ADN phonebook on a UICC. The client would then be able to switch on the fly between the GSM/global phonebook and the (active) USIM Application phonebook.

A UICC can comprise of many USIM applications and a GSM application. Only one of application can be active at any one point. The USIM applications contain their own phonebooks (ADN, FDN, etc..). To open a USIM Application phonebook, the USIM Application must be active. It is not possible to access a phonebook of a USIM Application that is not currently active.

This API method opens a RMobilePhoneBookStore sub-session from a previously opened RMobilePhone sub-session. The name of the phone book to open is passed in the aStore parameter. The names of known and valid phone books for this API methods are listed in the table below. The phone may not support all of these phone books so clients should check which are available using the method in the previous section 4.8.1.

Note for the TSY development: Internally ETel will pass to the TSY one TDesC variable containing: the phonebookname as defined in 8.4.1 for GSM and CDMA ICCs or the phonebookname followed by a delimiting character (i.e. the PHBOOK_DELIMITER defined in ETelMM.h) and the ICC type (i.e. UICC) for UMTS.

capability
None

Parameters

RMobilePhone & aPhoneThe opened RMobilePhone sub-session.
const TDesC & aStoreThe name of the phone book to open.
const TDesC & aModeThe phonebook mode.

Read(TRequestStatus &, TInt, TInt, TDes8 &)

IMPORT_C voidRead(TRequestStatus &aReqStatus,
TIntaIndex,
TIntaNumSlots,
TDes8 &aPBData
)const

This method reads one or more entries from a phonebook store. The reading will start at the slot specified by aIndex and will stop either after aNumSlots of slots have been read or no more whole phonebook entries can fit in the size of the supplied aPBData parameter.

If there are no used entries in the slots requested then KErrNotFound will be returned.

Example: If aIndex=1 and aNumSlots=1 then one slot (slot number 1) will be read and if used, this entry will be returned within aPBData.

capability
ReadUserData

Parameters

TRequestStatus & aReqStatusreturns the result code after the asynchronous call completes
TInt aIndexSpecifies the index to start reading from, must be >= 1.
TInt aNumSlotsSpecifies the number of slots to read, must be >= 1 and <= total number of slots.
TDes8 & aPBDataA descriptor that will contain the phonebook data in TLV format.

Write(TRequestStatus &, const TDesC8 &, TInt &)

IMPORT_C voidWrite(TRequestStatus &aReqStatus,
const TDesC8 &aPBData,
TInt &aIndex
)const

This member function writes one phonebook entry to the store. This member function is a specialised version of the base class RMobilePhoneStore::Write() and all clients of RMobilePhoneBookStore should use this specialised version rather than the base class version. The phonebook data will be in aPBData which will contain the encoded byte stream of a TLV format phonebook entry.

Note:

Use RTelSubSessionBase::CancelAsyncRequest(EMobilePhoneStoreWrite) to cancel a previously placed asynchronous Write request.

capability
WriteUserData

Parameters

TRequestStatus & aReqStatusOn return, KErrNone if successful, a system wide error code if not.
const TDesC8 & aPBDataThe encoded byte stream of TLV formatted phonebook data.
TInt & aIndexThe slot the TSY will store the entry, or if aIndex=-1 the TSY will store the entry in the first free location and then return this location within aIndex when it completes the request.

Member Enumerations Documentation

Enum anonymous

Enumerators

KMaxPBIDSize = 15

Enum TMobilePBFieldTags

The following Tag IDs are used to encode/decode the phonebook entries to/from the TLV format. Each field will have a unique identifier and will be followed by the field length. The type of data associated with the field is also specified below.

Some fields do not have any data and just serve as separators within the buffer
  • in these cases the Data Type column is set to not applicable (n/a).

Modes: Common

Enumerators

ETagPBNewEntry = 0xA0

Tag id for the beginning of a new phonebook entry.

Data type: n/a.

Modes: Common

ETagPBUniqueId = 0xB0

Tag id for the Unique ID field.

Data type: TUint16

Modes: WCDMA

ETagPBAdnIndex = 0xC0

Tag id for the Index within the ADN record.

Data type: TUint16

Modes: Common

ETagPBText = 0xC1

Tag id for a Text field within the ADN/ANR record.

Data type: TDes16

Modes: Common

ETagPBNumber = 0xC2

Tag id for a Number field within the ADN/ANR record.

Data type: TDes16

Modes: Common

ETagPBTonNpi = 0xC3

Tag id for a TON/NPI byte within the ADN/ANR record.

Data type: TUint8

Modes: Common

ETagPBBearerCap = 0xC4

Tag id for a Bearer Capability IE associated to the ADN/ANR record.

Data type: TDes8

Modes: GSM/WCDMA

ETagPBAnrStart = 0xC5

Tag id for the beginning of an Additional Number entry within the phonebook entry.

Data type: n/a

Modes: WCDMA

ETagPBSecondName = 0xC6

Tag id for the Second Name associated to the ADN record.

Data type: TDes16

Modes: WCDMA

ETagPBGroupName = 0xC7

Tag id for a Group Name associated to the ADN record.

Data type:TDes16

Modes: WCDMA

ETagPBEmailAddress = 0xC8

Tag id for an Email Address associated to the ADN record.

Data type: TDes16

Modes: WCDMA

ETagPBEntryControl = 0xC9

Tag id for the Entry Control byte associated to the ADN record.

Data type: TUint8

Modes: WCDMA

ETagPBHiddenInfo = 0xCA

Tag id for the Hidden Information byte associated to the ADN record.

Data type: TUint8

Modes: WCDMA

ETagPBDateTime = 0xCB
ETagPBDuration = 0xCC
ETagPBCallStatus = 0xCD
ETagPBEntryStatus = 0xCE

Enum TMobilePhoneBookCaps

Describes the specialized phone book capabilities.

Modes: Common

Enumerators

KCapsRestrictedWriteAccess = 0x00000001

New entries can only be written to (or deleted from) the phone book with the PIN2 password or equivalent.

Modes: Common

KCapsSecondNameUsed = 0x00000002

The phonebook supports the second name field.

Modes: WCDMA

KCapsAdditionalNumUsed = 0x00000004

The phonebook supports the additional number (with optional Text, TON, NPI and Bearer Capability) field.

Modes: WCDMA

KCapsGroupingUsed = 0x00000008

The phonebook supports the group name field.

Modes: WCDMA

KCapsEntryControlUsed = 0x00000010

The phonebook supports entry control and hidden flag fields.

Modes: WCDMA

KCapsEmailAddressUsed = 0x00000020

The phonebook supports the email address field.

Modes: WCDMA

KCapsBearerCapUsed = 0x00000040

The phonebook supports the bearer capability IE field.

Modes: WCDMA

KCapsSynchronisationUsed = 0x00000080
The phonebook supports retrieval of the phonebook's PBID and Change Counter
  • and for each entry its UID field.

Modes: WCDMA

Enum TMobilePhoneBookLocation

Described the location of the phone book.

Modes: Common for all

Enumerators

ELocationUnknown

The phonebook's location is unknown.

ELocationIccMemory

The phonebook is located in ICC (SIM/R-UIM) memory.

ELocationPhoneMemory

The phonebook is located in Phone (ME) memory.

ELocationExternalMemory

The phonebook is located in an external memory.

ELocationCombinedMemory

The phonebook entries are dispersed over a combination of memory locations.

Member Type Definitions Documentation

Typedef TMobilePhoneBookIdentity

typedef TBuf8< KMaxPBIDSize >TMobilePhoneBookIdentity

Defines a modifiable buffer descriptor to contain the phone book identity. Used in TMobilePhoneBookInfoV1.

Typedef TMobilePhoneBookInfoV1Pckg

typedef TPckg< TMobilePhoneBookInfoV1 >TMobilePhoneBookInfoV1Pckg

Packages the TMobilePhoneBookInfoV1 into a TMobilePhoneBookInfoV1Pckg.

Typedef TMobilePhoneBookInfoV2Pckg

typedef TPckg< TMobilePhoneBookInfoV2 >TMobilePhoneBookInfoV2Pckg

Packages the TMobilePhoneBookInfoV2 into a TMobilePhoneBookInfoV1Pckg.

Typedef TMobilePhoneBookInfoV5Pckg

typedef TPckg< TMobilePhoneBookInfoV5 >TMobilePhoneBookInfoV5Pckg

Packages the TMobilePhoneBookInfoV5 into a TMobilePhoneBookInfoV5Pckg.