RPhoneBookSession Class Reference

#include <app/phbksync.h>

Link against: phbksyncsvr.lib

class RPhoneBookSession : public RSessionBase, public RSessionBase
Public Member Type Definitions
typedef TPckg< TContactFieldsV1 > TContactFieldsV1Pckg
typedef TPckg< TContactFieldsV2 > TContactFieldsV2Pckg
typedef TPckg< TContactFieldsV3 > TContactFieldsV3Pckg
Public Member Enumerations
enumTPhonebookSyncMode { EAutoCurrentIcc, EAutoSameIcc, EManual }
enumTSyncIdType { ESyncGroupId, ESyncTemplateId }
enumTSyncState { EUnsynchronised, ECacheValid, EErrorDuringSync }
Public Member Functions
RPhoneBookSession()
IMPORT_C voidCancelRequest(TPhonebookSyncRequestCancel)
IMPORT_C voidCancelRequest(TPhonebookSyncRequestCancel, TUid)
IMPORT_C voidClose()
IMPORT_C TIntConnect()
IMPORT_C voidDeleteContact(TRequestStatus &, TContactItemId)
IMPORT_C voidDoSynchronisation(TRequestStatus &)
IMPORT_C voidDoSynchronisation(TRequestStatus &, TUid)
IMPORT_C TIntGetContactFormat(TDes8 &)
IMPORT_C voidGetFreeSlotsL(RArray< TInt > &)
IMPORT_C voidGetFreeSlotsL(RArray< TInt > &, TUid)
IMPORT_C TIntGetLastSyncError(TInt &)
IMPORT_C TIntGetLastSyncError(TInt &, TUid)
IMPORT_C TIntGetNumSlots(TInt &)
IMPORT_C TIntGetNumSlots(TInt &, TUid)
IMPORT_C TIntGetPhoneBookCacheState(TSyncState &)
IMPORT_C TIntGetPhoneBookCacheState(TSyncState &, TUid)
IMPORT_C TIntGetPhoneBookId(TContactItemId &, TSyncIdType)
IMPORT_C TIntGetPhoneBookId(TContactItemId &, TSyncIdType, TUid)
IMPORT_C TIntGetSlotId(TInt, TContactItemId &)
IMPORT_C TIntGetSlotId(TInt, TContactItemId &, TUid)
IMPORT_C TIntGetSyncMode(TPhonebookSyncMode &)
IMPORT_C TIntGetSyncMode(TPhonebookSyncMode &, TUid)
IMPORT_C voidNotifyPhBkCacheStateChange(TRequestStatus &)
IMPORT_C voidNotifyPhBkCacheStateChange(TRequestStatus &, TUid)
IMPORT_C TIntSetSyncMode(TPhonebookSyncMode)
IMPORT_C TIntSetSyncMode(TPhonebookSyncMode, TUid)
IMPORT_C TIntShutdownServer(TBool)
IMPORT_C TIntUpdateLookuptable(TContactItemId, TInt)
IMPORT_C TIntUpdateLookuptable(TContactItemId, TInt, TUid)
IMPORT_C TIntValidateContact(MContactSynchroniser::TValidateOperation, TContactItemId)
IMPORT_C TVersionVersion()
IMPORT_C voidWriteContact(TRequestStatus &, CContactICCEntry &, TInt &)
IMPORT_C voidWriteContact(TRequestStatus &, CContactICCEntry &, TInt &, TUid &)
IMPORT_C TInt__DbgCheckHeap(TInt)
IMPORT_C TInt__DbgFailNext(TInt)
IMPORT_C TInt__DbgMarkEnd(TInt)
IMPORT_C TInt__DbgMarkHeap()
Inherited Attributes
RHandleBase::iHandle
Inherited Enumerations
RHandleBase:TAttributes
RSessionBase:TAttachMode
Inherited Functions
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RSessionBase::CreateSession(RServer2,const TVersion &)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy *,TRequestStatus *)
RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Open(TInt,TOwnerType)
RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
RSessionBase::Send(TInt)const
RSessionBase::Send(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt)const
RSessionBase::SendReceive(TInt,TRequestStatus &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSessionBase::SetReturnedHandle(TInt)
RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
RSessionBase::ShareAuto()
RSessionBase::ShareProtected()

Detailed Description

Provides the CPhoneBookSyncPlugin client access to a session with the Phonebook Synchronizer Server.

A handle to an RPhoneBookSession enables the plug-in class to perform IPC communications with the server.

Member Type Definition Documentation

Typedef TContactFieldsV1Pckg

typedef TPckg< TContactFieldsV1 >TContactFieldsV1Pckg

A packaged instance of TContactFieldsV1.

Typedef TContactFieldsV2Pckg

typedef TPckg< TContactFieldsV2 >TContactFieldsV2Pckg

A packaged instance of TContactFieldsV2.

Typedef TContactFieldsV3Pckg

typedef TPckg< TContactFieldsV3 >TContactFieldsV3Pckg

A packaged instance of TContactFieldsV3.

Member Enumeration Documentation

Enum TPhonebookSyncMode

The synchronisation mode for phonebooks when the server starts.

EnumeratorValueDescription
EAutoCurrentIcc

Automatic synchronisation will be performed.

EAutoSameIcc

Automatic synchronisation will only be performed if the current ICC is the same as the last ICC to be synchonised.

EManual

Manual synchronisation will be performed when requested.

Enum TSyncIdType

The phonebook ID type requested from a phonebook. There are two types of IDs (group IDs and template IDs).

See also: RPhoneBookSession::GetPhoneBookId()

EnumeratorValueDescription
ESyncGroupId

Used to allocate a new entry to the right group in the Contacts Database.

ESyncTemplateId

Used to define new ICC entries in the Contacts Database.

Enum TSyncState

The phonebook cache state.

EnumeratorValueDescription
EUnsynchronised

The server has not yet populated the Contacts Database.

ECacheValid

The server has finished populating the Contacts Database.

EErrorDuringSync

The server encountered an error populating the Contacts Database.

Constructor & Destructor Documentation

RPhoneBookSession ( )

IMPORT_CRPhoneBookSession()

Standard constructor.

Member Function Documentation

CancelRequest ( TPhonebookSyncRequestCancel )

IMPORT_C voidCancelRequest(TPhonebookSyncRequestCancelaReqToCancel)

Cancels a previously issued asynchronous request on the Global/GSM ADN phonebook.

Parameters
aReqToCancelThe request to be cancelled.
Capability
None

CancelRequest ( TPhonebookSyncRequestCancel, TUid )

IMPORT_C voidCancelRequest(TPhonebookSyncRequestCancelaReqToCancel,
TUidaPhonebookId
)

Cancels a previously issued asynchronous request. The request to be cancelled is specified by the aReqToCancel parameter and the ICC phonebook for which the request needs to be cancelled is specified by the aPhonebookUid parameter.

Parameters
aReqToCancelRequest to be cancelled.
aPhonebookIdUID of the ICC phonebook.
Capability
ReadUserData
WriteUserData

Close ( )

IMPORT_C voidClose()

Reimplemented from RHandleBase::Close()

Closes the client's session with the Phonebook Synchroniser Server.

Capability
None

Connect ( )

IMPORT_C TIntConnect()

Connects the client to the Phonebook Synchroniser Server.

This must be used before any of the other methods listed in this API section. The first client to call this method will cause the initiation of the Phonebook Synchroniser Server within its own executable process.

Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

DeleteContact ( TRequestStatus &, TContactItemId )

IMPORT_C voidDeleteContact(TRequestStatus &aReqStatus,
TContactItemIdaId
)

Deletes the contact item from the ICC card.

Parameters
aReqStatusOn completion, KErrNone if successful, a system-wide error code if not.
aIdThe contact item to delete.
Capability
WriteUserData

DoSynchronisation ( TRequestStatus & )

IMPORT_C voidDoSynchronisation(TRequestStatus &aReqStatus)

Executes a manual synchronisation of the Global/GSM ADN phonebook entries.

Parameters
aReqStatusOn completion, KErrNone if successful, a system-wide error code if not.
Capability
ReadUserData
WriteUserData

DoSynchronisation ( TRequestStatus &, TUid )

IMPORT_C voidDoSynchronisation(TRequestStatus &aReqStatus,
TUidaPhonebookUid
)

Instructs the Phonebook Synchroniser Server to start a manual synchronisation of the ICC phonebook specified by the aPhonebook parameter.

Parameters
aReqStatusOn completion, KErrNone if successful, a system-wide error code if not.
aPhonebookUidTUid of the ICC phonebook to be synchronised.
Capability
ReadUserData
WriteUserData

GetContactFormat ( TDes8 & )

IMPORT_C TIntGetContactFormat(TDes8 &aContactFields)

Returns information about the supported fields within an ICC phonebook entry.

The TContactFieldFormat type defines the information available for each field and TContactFieldsV1 is a collection of this information for all supported field types. The client can use the field information to tailor its UI so that user can only enter fields with the maximum number of supported characters.

The only fields supported by GSM ADN phonebook are the name, number and ICC slot number, so these are the only fields included in TContactFieldsV1.

TContactFieldsV2 is used to contain the new USIM phonebook fields.

TContactFieldsV3 is an extension of TContactFieldsV2 and contains additional information on the fields supported by the USIM phonebooks.

Parameters
aContactFieldsOn return, the packaged TContactFieldsV1/V2/V3 is filled with the supported field information.
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetFreeSlotsL ( RArray< TInt > & )

IMPORT_C voidGetFreeSlotsL(RArray< TInt > &aFreeSlots)const

Get the slots that are free in the Global/GSM ADN phonebook.

Parameters
aFreeSlotsOn return, an array of slots numbers that are free.
Capability
None

GetFreeSlotsL ( RArray< TInt > &, TUid )

IMPORT_C voidGetFreeSlotsL(RArray< TInt > &aFreeSlots,
TUidaPhonebookId
)const

Get the slots that are free in the requested phonebook.

Parameters
aFreeSlotsOn return, an array of slots numbers that are free.
aPhonebookIdType of ICC phonebook
Capability
None

GetLastSyncError ( TInt & )

IMPORT_C TIntGetLastSyncError(TInt &aError)

Returns the last server cache sync error for the Global/GSM ADN phonebook.

Parameters
aErrorLast server cache sync error
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetLastSyncError ( TInt &, TUid )

IMPORT_C TIntGetLastSyncError(TInt &aError,
TUidaPhonebookId
)

Return the last server cache sync error for the requested phonebook.

Parameters
aErrorLast server cache sync error.
aPhonebookIdUID of the ICC phonebook.
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetNumSlots ( TInt & )

IMPORT_C TIntGetNumSlots(TInt &aNumSlots)const

Gets the total number of slots on the Global/GSM ADN phonebook.

Parameters
aNumSlotsThe number of slots.
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetNumSlots ( TInt &, TUid )

IMPORT_C TIntGetNumSlots(TInt &aNumSlots,
TUidaPhonebookId
)const

Gets the total number of slots on the specified ICC phonebook.

Parameters
aNumSlotsThe number of slots.
aPhonebookIdType of ICC phonebook
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetPhoneBookCacheState ( TSyncState & )

IMPORT_C TIntGetPhoneBookCacheState(TSyncState &aState)

Returns the current state of the Phonebook Synchroniser server cache for the Global/GSM ADN phonebook.

Parameters
aStateOn return, the state of the phonebook synchroniser cache.
Return Value
KErrNone if the state is successfully retrieved, or an error code if the server is unable to process the request.
Capability
None

GetPhoneBookCacheState ( TSyncState &, TUid )

IMPORT_C TIntGetPhoneBookCacheState(TSyncState &aState,
TUidaPhonebookId
)

Return the current phonebook server cache state for the ICC phonebook specified by the aPhonebook parameter.

Parameters
aStateCurrent state of the phonebook cache
aPhonebookIdType of ICC phonebook
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetPhoneBookId ( TContactItemId &, TSyncIdType )

IMPORT_C TIntGetPhoneBookId(TContactItemId &aId,
TSyncIdTypeaIdType
)

Returns the requested UID for the ID type belonging to the Global/GSM ADN phonebook. This is the ID type spedified by aIdType, which can be either the template ID or the group ID for an ICC entry belonging to the Global/GSM ADN phonebook, depending on the type supplied by aIdType.

Parameters
aIdOn return, the contact ID.
aIdTypeThe type of ID requested.
Return Value
KErrNone, if the UID is successfully returned or an error code if the UID does not exist or can not be accessed.
Capability
None

GetPhoneBookId ( TContactItemId &, TSyncIdType, TUid )

IMPORT_C TIntGetPhoneBookId(TContactItemId &aId,
TSyncIdTypeaIdType,
TUidaPhonebookUid
)

Return either the current group or template ID (depending on the type supplied by aIdType) for the ICC entries belonging to the ICC phonebook specified by the aPhonebookUid parameter.

Parameters
aIdContacts UID
aIdTypeType of Contacts UID
aPhonebookUidTUid of the ICC phonebook
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
None

GetSlotId ( TInt, TContactItemId & )

IMPORT_C TIntGetSlotId(TIntaSlot,
TContactItemId &aId
)const

Get the Contacts UID of a particular slot in the Global/GSM ADN phonebook.

Parameters
aSlotThe slot number on which the request is made.
aIdThe contact Id of the slot number.
Return Value
KErrNotFound if the UID is not found.
Capability
None

GetSlotId ( TInt, TContactItemId &, TUid )

IMPORT_C TIntGetSlotId(TIntaSlot,
TContactItemId &aId,
TUidaPhonebookId
)const

Get the Contacts UID of a particular slot in the requested phonebook.

Parameters
aSlotThe slot number on which the request is made.
aIdThe contact Id of the slot number.
aPhonebookIdType of ICC phonebook
Return Value
KErrNotFound if the UID is not found.
Capability
None

GetSyncMode ( TPhonebookSyncMode & )

IMPORT_C TIntGetSyncMode(TPhonebookSyncMode &aSyncMode)

Returns the current setting for the synchronisation mode of the Global/GSM ADN phonebook, used by the Phonebook Synchroniser Server at start-up to determine if the phonebook should be automatically synchronised.

Parameters
aSyncModeOn return, the synchronisation mode.
Return Value
KErrNone if the setting is successfully returned in aSyncMode, or an error code if the setting does not exist or can not be accessed.
Capability
None

GetSyncMode ( TPhonebookSyncMode &, TUid )

IMPORT_C TIntGetSyncMode(TPhonebookSyncMode &aSyncMode,
TUidaPhonebookId
)

Returns the current setting for the Synchonisation Mode of the ICC phonebook specified by aPhonebookUid and used by the Phonebook Synchroniser Server at start-up to determine if the phonebook should be automatically synchronised.

Parameters
aSyncModeOn return Will contain the current synchronisation mode.
aPhonebookIdTUid of the ICC phonebook
Return Value
KErrNone if operation was successful, otherwise return error.
Capability
None

NotifyPhBkCacheStateChange ( TRequestStatus & )

IMPORT_C voidNotifyPhBkCacheStateChange(TRequestStatus &aStatus)

Registers the notification for a change in the Global/GSM ADN phonebook cache state.

Note:

The client should call GetPhoneBookCacheState() in order to get the new state of the synchroniser.

Parameters
aStatusOn completion, KErrNone if successful, a system-wide error code if not.
Capability
None

NotifyPhBkCacheStateChange ( TRequestStatus &, TUid )

IMPORT_C voidNotifyPhBkCacheStateChange(TRequestStatus &aStatus,
TUidaPhonebookId
)

Registers the notification for a change in the Phone book cache state.

Note:

The client should call GetPhoneBookCacheState() in order to get the new state of the synchroniser.

Parameters
aStatusOn completion, KErrNone if successful, a system-wide error code if not.
aPhonebookIdUID of the ICC phonebook.
Capability
None

SetSyncMode ( TPhonebookSyncMode )

IMPORT_C TIntSetSyncMode(TPhonebookSyncModeaSyncMode)

Sets a new value for the synchronisation mode of the Global/GSM ADN phonebook, used by the Phonebook Synchroniser Server at start-up to determine its synchronisation policy.

If the mode is changing to EAutoCurrentIcc and no sync has yet been performed, then an automatic sync will be performed.

Parameters
aSyncModeThe new synchronisation mode.
Return Value
KErrNone if the setting specified by aSyncMode is successfully changed, or an error code if the setting does not exist or can not be accessed.
Capability
None

SetSyncMode ( TPhonebookSyncMode, TUid )

IMPORT_C TIntSetSyncMode(TPhonebookSyncModeaSyncMode,
TUidaPhonebookId
)

Set a new value for the Synchonisation Mode of the ICC phonebook specified by aPhonebookUid, used by the Phonebook Synchroniser Server at start-up to determine its synchronisation policy.

Parameters
aSyncModeCurrent synchronisation mode
aPhonebookIdTUid of the ICC phonebook
Return Value
KErrNone if operation was successful, otherwise return error
Capability
None

ShutdownServer ( TBool )

IMPORT_C TIntShutdownServer(TBoolaUnconditionally)

Requests the shutdown of the server when the last client disconnects. There is no support for immediate shutdown functionality. This API call can only be executed if the server is compiled as a debug release.

Parameters
aUnconditionallyIf true, subsequent connection requests from any client will be honoured delaying shutdown until they disconnect. If untrue, all subsequent connect requests will be denied.
Return Value
KErrNone if successful, a system-wide error code if not.
Capability
ReadUserData
WriteUserData

UpdateLookuptable ( TContactItemId, TInt )

IMPORT_C TIntUpdateLookuptable(TContactItemIdaNewUid,
TIntaIccSlot
)

Updates the Phonebook Synchroniser's look-up table with the new contact ID in the Global/GSM ADN phonebook.

This function should be called when a new entry has been added to the Contacts Database by a client other than the Phonebook Synchroniser Server, so the server can know what the UID of the newly added contact was.

The Phonebook Synchroniser plug-in should extract the appropriate details from the item (e.g. item UID and slot number) and call the Phonebook server to update the look-up tables.

Parameters
aNewUidThe contact use for the update.
aIccSlotThe ICC slot number to match the Contacts UID.
Return Value
KErrNone if the look-up table update succeeded, or an error code (such as KErrArgument) if the operation failed for that ICC slot number.
Capability
None

UpdateLookuptable ( TContactItemId, TInt, TUid )

IMPORT_C TIntUpdateLookuptable(TContactItemIdaNewUid,
TIntaIccSlot,
TUidaPhonebookUid
)

Updates the Phonebook Synchroniser's look-up table with the new contact ID in the ICC phonebook specified by the aPhonebookUid parameter

This function should be called when a new entry has been added to the Contacts Database by a client other than the Phonebook Synchroniser Server, so the server can know what the UID of the newly added contact was.

The Phonebook Synchroniser plug-in should extract the appropriate details from the item (e.g. item UID and slot number) and call the Phonebook server to update the look-up tables.

Parameters
aNewUidContact UID number unique per entry
aIccSlotICC slot value
aPhonebookUidType of ICC phonebook
Return Value
KErrNone if operation was successful, otherwise return error
Capability
None

ValidateContact ( MContactSynchroniser::TValidateOperation, TContactItemId )

IMPORT_C TIntValidateContact(MContactSynchroniser::TValidateOperationaOperation,
TContactItemIdaId
)

Instructs the Phonebook Synchroniser Server to verify the access to the ICC contact item stored in the Contacts database. The server is responsible for mapping the UID to the phonebook this item belongs to.

Parameters
aOperationHolds the type of check, search, edit, read.
aIdThe contact model UID of the record stored in the database.
Return Value
KErrNone if operation was successful, otherwise return error
Capability
ReadUserData

Version ( )

IMPORT_C TVersionVersion()const

Returns the current version of the Phonebook Synchroniser Server.

Return Value
The version of the Phonebook Synchroniser Server.
Capability
None

WriteContact ( TRequestStatus &, CContactICCEntry &, TInt & )

IMPORT_C voidWriteContact(TRequestStatus &aReqStatus,
CContactICCEntry &aContactItem,
TInt &aSlotNumber
)

Writes the contact item to the Global/GSM ADN phonebook. This can be used to edit an existing contact or to create a new contact.

Parameters
aReqStatusOn completion, KErrNone if successful, a system-wide error code if not.
aContactItemThe contact item to write to the ICC card.
aSlotNumberThe slot number to write to contact into. If set to KSyncIndexNotSupplied the Phonebook Synchroniser Server will use the first empty slot and aSlotNumber will contain the slot number used on completion.
Capability
WriteUserData

WriteContact ( TRequestStatus &, CContactICCEntry &, TInt &, TUid & )

IMPORT_C voidWriteContact(TRequestStatus &aReqStatus,
CContactICCEntry &aContactItem,
TInt &aSlotNumber,
TUid &aPhonebookUid
)

Write the contact item supplied in the aContactItem parameter to the ICC phonebook specified by aPhonebookUid.

This method is used to edit an existing or write new entry to the ICC phonebook. When editing an existing entry the slot number will be supplied in aContactItem, whereas for new entries the new slot number will be returned in the aSlotNumber parameter. Similarly for new entries the phonebook UID will be returned in the aPhonebookUid parameter.

Parameters
aReqStatusOn completion, KErrNone if successful, a system-wide error code if not.
aContactItemContacts ICC entry.
aSlotNumberAllocated slot number.
aPhonebookUidUID of the ICC phonebook.
Capability
WriteUserData

__DbgCheckHeap ( TInt )

IMPORT_C TInt__DbgCheckHeap(TIntaCount)

Performs a heap mark check in the Phonebook Sync Server and Background Sync Engine threads.

Parameters
aCountThe number of heap cells expected to be allocated at the current nest level.
Capability
None

__DbgFailNext ( TInt )

IMPORT_C TInt__DbgFailNext(TIntaCount)

Set a heap fail next condition in the Phonebook Sync Server and Background Sync Engine threads.

Parameters
aCountDetermines when the allocation will fail.
Capability
None

__DbgMarkEnd ( TInt )

IMPORT_C TInt__DbgMarkEnd(TIntaCount)

Perfom a heap mark end check in the Phonebook Sync Server and Background Sync Engine threads.

Parameters
aCountThe number of heap cells expected to remain allocated at the current nest level.
Capability
None

__DbgMarkHeap ( )

IMPORT_C TInt__DbgMarkHeap()

Set a heap mark in the Phonebook Sync Server and Background Sync Engine threads.

Capability
None