Class RPhoneBookSession

class RPhoneBookSession : public RSessionBase;

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.

Derivation

• RHandleBase - A handle to an object

• RSessionBase - Client-side handle to a session with a server

• RPhoneBookSession - Provides the CPhoneBookSyncPlugin client access to a session with the Phonebook Synchronizer Server

Members

Defined in RPhoneBookSession:
CancelRequest(), CancelRequest(), Close(), Connect(), DeleteContact(), DoSynchronisation(), DoSynchronisation(), EAutoCurrentIcc, EAutoSameIcc, ECacheValid, EErrorDuringSync, EManual, ESyncGroupId, ESyncTemplateId, EUnsynchronised, GetContactFormat(), GetFreeSlotsL(), GetFreeSlotsL(), GetLastSyncError(), GetLastSyncError(), GetNumSlots(), GetNumSlots(), GetPhoneBookCacheState(), GetPhoneBookCacheState(), GetPhoneBookId(), GetPhoneBookId(), GetSlotId(), GetSlotId(), GetSyncMode(), GetSyncMode(), NotifyPhBkCacheStateChange(), NotifyPhBkCacheStateChange(), RPhoneBookSession(), SetSyncMode(), SetSyncMode(), ShutdownServer(), TContactFieldsV1, TContactFieldsV1Pckg, TContactFieldsV2, TContactFieldsV2Pckg, TContactFieldsV3, TContactFieldsV3Pckg, TPhonebookSyncMode, TSyncIdType, TSyncState, TTemplateAndBufferSize, UpdateLookuptable(), UpdateLookuptable(), ValidateContact(), Version(), WriteContact(), WriteContact(), __DbgCheckHeap(), __DbgFailNext(), __DbgMarkEnd(), __DbgMarkHeap()

Inherited from RHandleBase:
Attributes(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

IMPORT_C RPhoneBookSession();

Description

Standard constructor.

Capability:

Illegal

IMPORT_C TInt Connect();

Description

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

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C void Close();

Description

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

Capability:

Illegal

IMPORT_C TVersion Version() const;

Description

Returns the current version of the Phonebook Synchroniser Server.

Return value

TVersion The version of the Phonebook Synchroniser Server.

Capability:	ReadUserData
Capability:	WriteUserData

IMPORT_C TInt ShutdownServer(TBool aUnconditionally);

Description

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

TBool aUnconditionally If 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

TInt KErrNone if successful, a system-wide error code if not.

Capability:	ReadUserData
Capability:	WriteUserData

IMPORT_C void DoSynchronisation(TRequestStatus &aReqStatus);

Description

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

Parameters

TRequestStatus &aReqStatus On completion, KErrNone if successful, a system-wide error code if not.

Capability:

ReadUserData

IMPORT_C TInt ValidateContact(MContactSynchroniser::TValidateOperation aOperation, TContactItemId aId);

Description

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

MContactSynchroniser::TValidateOperation aOperation Holds the type of check, search, edit, read. TContactItemId aId The contact model UID of the record stored in the database.

Return value

TInt KErrNone if operation was successful, otherwise return error

Capability:

WriteUserData

IMPORT_C void WriteContact(TRequestStatus &aReqStatus, CContactICCEntry &aContactItem, TInt &aSlotNumber);

Description

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

TRequestStatus &aReqStatus On completion, KErrNone if successful, a system-wide error code if not. CContactICCEntry &aContactItem The contact item to write to the ICC card. TInt &aSlotNumber The 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

IMPORT_C void DeleteContact(TRequestStatus &aReqStatus, TContactItemId aId);

Description

Deletes the contact item from the ICC card.

Parameters

TRequestStatus &aReqStatus On completion, KErrNone if successful, a system-wide error code if not. TContactItemId aId The contact item to delete.

Capability:

Illegal

IMPORT_C TInt GetPhoneBookId(TContactItemId &aId, TSyncIdType aIdType);

Description

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

TContactItemId &aId On return, the contact ID. TSyncIdType aIdType The type of ID requested.

Return value

TInt KErrNone, if the UID is successfully returned or an error code if the UID does not exist or can not be accessed.

Capability:

Illegal

IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot);

Description

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

TContactItemId aNewUid The contact use for the update. TInt aIccSlot The ICC slot number to match the Contacts UID.

Return value

TInt 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:

Illegal

IMPORT_C TInt GetContactFormat(TDes8 &aContactFields);

Description

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

TDes8 &aContactFields On return, the packaged TContactFieldsV1/V2/V3 is filled with the supported field information.

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C TInt GetSyncMode(TPhonebookSyncMode &aSyncMode);

Description

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

TPhonebookSyncMode &aSyncMode On return, the synchronisation mode.

Return value

TInt 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:

Illegal

IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode);

Description

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

TPhonebookSyncMode aSyncMode The new synchronisation mode.

Return value

TInt 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:

Illegal

IMPORT_C TInt GetPhoneBookCacheState(TSyncState &aState);

Description

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

Parameters

TSyncState &aState On return, the state of the phonebook synchroniser cache.

Return value

TInt KErrNone if the state is successfully retrieved, or an error code if the server is unable to process the request.

Capability:

Illegal

IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel);

Description

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

Parameters

TPhonebookSyncRequestCancel aReqToCancel The request to be cancelled.

Capability:

Illegal

IMPORT_C TInt GetLastSyncError(TInt &aError);

Description

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

Parameters

TInt &aError Last server cache sync error

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus &aStatus);

Description

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

TRequestStatus &aStatus On completion, KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C TInt GetNumSlots(TInt &aNumSlots) const;

Description

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

Parameters

TInt &aNumSlots The number of slots.

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C void GetFreeSlotsL(RArray< TInt > &aFreeSlots) const;

Description

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

Parameters

RArray< TInt > &aFreeSlots On return, an array of slots numbers that are free.

Capability:

Illegal

IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId &aId) const;

Description

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

Parameters

TInt aSlot The slot number on which the request is made. TContactItemId &aId The contact Id of the slot number.

Return value

TInt KErrNotFound if the UID is not found.

Capability:	ReadUserData
Capability:	WriteUserData

IMPORT_C void DoSynchronisation(TRequestStatus &aReqStatus, TUid aPhonebookUid);

Description

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

Parameters

TRequestStatus &aReqStatus On completion, KErrNone if successful, a system-wide error code if not. TUid aPhonebookUid TUid of the ICC phonebook to be synchronised.

Capability:

WriteUserData

IMPORT_C void WriteContact(TRequestStatus &aReqStatus, CContactICCEntry &aContactItem, TInt &aSlotNumber, TUid &aPhonebookUid);

Description

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

TRequestStatus &aReqStatus On completion, KErrNone if successful, a system-wide error code if not. CContactICCEntry &aContactItem Contacts ICC entry. TInt &aSlotNumber Allocated slot number. TUid &aPhonebookUid UID of the ICC phonebook.

Capability:

Illegal

IMPORT_C TInt GetPhoneBookId(TContactItemId &aId, TSyncIdType aIdType, TUid aPhonebookUid);

Description

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

TContactItemId &aId Contacts UID TSyncIdType aIdType Type of Contacts UID TUid aPhonebookUid TUid of the ICC phonebook

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot, TUid aPhonebookUid);

Description

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

TContactItemId aNewUid Contact UID number unique per entry TInt aIccSlot ICC slot value TUid aPhonebookUid Type of ICC phonebook

Return value

TInt KErrNone if operation was successful, otherwise return error

Capability:

Illegal

IMPORT_C TInt GetSyncMode(TPhonebookSyncMode &aSyncMode, TUid aPhonebookId);

Description

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

TPhonebookSyncMode &aSyncMode On return Will contain the current synchronisation mode. TUid aPhonebookId TUid of the ICC phonebook

Return value

TInt KErrNone if operation was successful, otherwise return error.

Capability:

Illegal

IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode, TUid aPhonebookId);

Description

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

TPhonebookSyncMode aSyncMode Current synchronisation mode TUid aPhonebookId TUid of the ICC phonebook

Return value

TInt KErrNone if operation was successful, otherwise return error

Capability:

Illegal

IMPORT_C TInt GetPhoneBookCacheState(TSyncState &aState, TUid aPhonebookId);

Description

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

Parameters

TSyncState &aState Current state of the phonebook cache TUid aPhonebookId Type of ICC phonebook

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:	ReadUserData
Capability:	WriteUserData

IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel, TUid aPhonebookId);

Description

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

TPhonebookSyncRequestCancel aReqToCancel Request to be cancelled. TUid aPhonebookId UID of the ICC phonebook.

Capability:

Illegal

IMPORT_C TInt GetLastSyncError(TInt &aError, TUid aPhonebookId);

Description

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

Parameters

TInt &aError Last server cache sync error. TUid aPhonebookId UID of the ICC phonebook.

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus &aStatus, TUid aPhonebookId);

Description

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

TRequestStatus &aStatus On completion, KErrNone if successful, a system-wide error code if not. TUid aPhonebookId UID of the ICC phonebook.

Capability:

Illegal

IMPORT_C TInt GetNumSlots(TInt &aNumSlots, TUid aPhonebookId) const;

Description

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

Parameters

TInt &aNumSlots The number of slots. TUid aPhonebookId Type of ICC phonebook

Return value

TInt KErrNone if successful, a system-wide error code if not.

Capability:

Illegal

IMPORT_C void GetFreeSlotsL(RArray< TInt > &aFreeSlots, TUid aPhonebookId) const;

Description

Get the slots that are free in the requested phonebook.

Parameters

RArray< TInt > &aFreeSlots On return, an array of slots numbers that are free. TUid aPhonebookId Type of ICC phonebook

Capability:

Illegal

IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId &aId, TUid aPhonebookId) const;

Description

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

Parameters

TInt aSlot The slot number on which the request is made. TContactItemId &aId The contact Id of the slot number. TUid aPhonebookId Type of ICC phonebook

Return value

TInt KErrNotFound if the UID is not found.

Capability:

Illegal

IMPORT_C TInt __DbgMarkHeap();

Description

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

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgCheckHeap(TInt aCount);

Description

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

Parameters

TInt aCount The number of heap cells expected to be allocated at the current nest level.

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgMarkEnd(TInt aCount);

Description

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

Parameters

TInt aCount The number of heap cells expected to remain allocated at the current nest level.

Return value

TInt

Capability:

Illegal

IMPORT_C TInt __DbgFailNext(TInt aCount);

Description

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

Parameters

TInt aCount Determines when the allocation will fail.

Return value

TInt

class TContactFieldsV1;

Description

Specifies format of phonebook fields within an ICC phonebook entry.

Members

Defined in RPhoneBookSession::TContactFieldsV1:
ExtensionId(), KPhBkSyncTContactFieldsV1, KPhBkSyncTContactFieldsV2, KPhBkSyncTContactFieldsV3, TContactFieldsExtensionId, TContactFieldsV1(), iExtensionId, iIccSlotField, iNameField, iNumberField

Construction and destruction

---

TContactFieldsV1()

IMPORT_C TContactFieldsV1();

Description

Standard constructor.

Member functions

---

ExtensionId()

IMPORT_C TInt ExtensionId() const;

Description

Returns the Phonebook Synchronizer API extension number of the class.

Return value

TInt The version ID from TContactFieldsExtensionId.

Member enumerations

---

Enum TContactFieldsExtensionId

TContactFieldsExtensionId

Description

Enumeration to describe the version ID of the Phonebook Synchronizer.

KPhBkSyncTContactFieldsV1 Phonebook Synchronizer version 1 KPhBkSyncTContactFieldsV2 Phonebook Synchronizer version 2 KPhBkSyncTContactFieldsV3 Phonebook Synchronizer version 3

Member data

---

iNameField

TContactFieldFormat iNameField;

Description

The format of the name field within an ICC phonebook entry.

---

iNumberField

TContactFieldFormat iNumberField;

Description

The format of the number field within an ICC phonebook entry.

---

iIccSlotField

TContactFieldFormat iIccSlotField;

Description

The format of the ICC slot number field within an ICC phonebook entry.

---

iExtensionId

protected: TInt iExtensionId;

Description

class TContactFieldsV2 : public RPhoneBookSession::TContactFieldsV1;

Description

Specifies format of phonebook fields within an UICC phonebook entry

Derivation

• RPhoneBookSession::TContactFieldsV1 - Specifies format of phonebook fields within an ICC phonebook entry

• RPhoneBookSession::TContactFieldsV2 - Specifies format of phonebook fields within an UICC phonebook entry

Members

Defined in RPhoneBookSession::TContactFieldsV2:
TContactFieldsV2(), iAdditionalNumString, iEmailField, iGroupField, iPhonebook

Inherited from RPhoneBookSession::TContactFieldsV1:
ExtensionId(), KPhBkSyncTContactFieldsV1, KPhBkSyncTContactFieldsV2, KPhBkSyncTContactFieldsV3, TContactFieldsExtensionId, iExtensionId, iIccSlotField, iNameField, iNumberField

Construction and destruction

---

TContactFieldsV2()

IMPORT_C TContactFieldsV2();

Description

Standard constructor.

Member data

---

iAdditionalNumString

TContactFieldFormat iAdditionalNumString;

Description

The format of any additional number fields within an ICC phonebook entry.

---

iGroupField

TContactFieldFormat iGroupField;

Description

The format of group field within an ICC phonebook entry.

---

iEmailField

TContactFieldFormat iEmailField;

Description

The format of email field within an ICC phonebook entry.

---

iPhonebook

TUid iPhonebook;

Description

The UID of the phonebook.

class TContactFieldsV3 : public RPhoneBookSession::TContactFieldsV2;

Description

Specifies additional format information for phonebook fields within a UICC phonebook entry.

Derivation

• RPhoneBookSession::TContactFieldsV1 - Specifies format of phonebook fields within an ICC phonebook entry

• RPhoneBookSession::TContactFieldsV2 - Specifies format of phonebook fields within an UICC phonebook entry

• RPhoneBookSession::TContactFieldsV3 - Specifies additional format information for phonebook fields within a UICC phonebook entry

Members

Defined in RPhoneBookSession::TContactFieldsV3:
TContactFieldsV3(), iAdditionalNumAlphaString, iSecondNameField

Inherited from RPhoneBookSession::TContactFieldsV1:
ExtensionId(), KPhBkSyncTContactFieldsV1, KPhBkSyncTContactFieldsV2, KPhBkSyncTContactFieldsV3, TContactFieldsExtensionId, iExtensionId, iIccSlotField, iNameField, iNumberField

Inherited from RPhoneBookSession::TContactFieldsV2:
iAdditionalNumString, iEmailField, iGroupField, iPhonebook

Construction and destruction

---

TContactFieldsV3()

IMPORT_C TContactFieldsV3();

Description

Standard constructor.

Member data

---

iAdditionalNumAlphaString

TContactFieldFormat iAdditionalNumAlphaString;

Description

The format of an addition number's text field within an ICC phonebook entry.

---

iSecondNameField

TContactFieldFormat iSecondNameField;

Description

The format of the second name field within an ICC phonebook entry.

struct TTemplateAndBufferSize;

Description

Structure holding the template ID and buffer size. The client has no need to use this structure.

Members

Defined in RPhoneBookSession::TTemplateAndBufferSize:
bufferSize, templateId

Member data

---

templateId

TContactItemId templateId;

Description

---

bufferSize

TInt bufferSize;

Description

TPhonebookSyncMode

Description

The synchronisation mode for phonebooks when the server starts.

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.

TSyncState

Description

The phonebook cache state.

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.

TSyncIdType

Description

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

See also:

• RPhoneBookSession::GetPhoneBookId()

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.

typedef TPckg<TContactFieldsV1> RPhoneBookSession::TContactFieldsV1Pckg;

Description

A packaged instance of TContactFieldsV1.

typedef TPckg<TContactFieldsV2> RPhoneBookSession::TContactFieldsV2Pckg;

Description

A packaged instance of TContactFieldsV2.

typedef TPckg<TContactFieldsV3> RPhoneBookSession::TContactFieldsV3Pckg;

Description

A packaged instance of TContactFieldsV3.