Class RPhoneBookSession

class RPhoneBookSession : public RSessionBase;

Support

Supported from 7.0

Description

Provides the CPhoneBookSyncPlugin class 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 RPhoneBookSession Provides the CPhoneBookSyncPlugin class access to a session with the Phonebook Synchronizer Server RSessionBase Client-side handle to a session with a server

Defined in RPhoneBookSession:
CancelRequest(), Close(), Connect(), DeleteContact(), DoSynchronisation(), EAutoCurrentIcc, EAutoSameIcc, ECacheValid, EManual, ESyncGroupId, ESyncTemplateId, EUnsynchronised, GetContactFormat(), GetPhoneBookCacheState(), GetPhoneBookId(), GetSyncMode(), MapContactFormatToInternalL(), RPhoneBookSession(), RPhoneBookSession(), SetSyncMode(), SetTypeOfNumber(), TContactFieldsV1, TContactFieldsV1Pckg, TPhonebookSyncMode, TSyncIdType, TSyncState, UpdateLookuptable(), ValidateContact(), Version(), WriteContact(), __DbgCheckHeap(), __DbgFailNext(), __DbgMarkEnd(), __DbgMarkHeap(), iSyncPtrHolder

Inherited from RHandleBase:
Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

RPhoneBookSession();

Description

Standard constructor.

TInt Connect();

Description

Connects the client to the Phonebook Synchronizer Server. It 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 Synchronizer Server thread within the C32 process.

Return value

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

void Close();

Description

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

TVersion Version() const;

Description

Returns the current version of the Phonebook Synchronizer Server.

Return value

TVersion The version of the Phonebook Synchronizer Server.

void DoSynchronisation(TRequestStatus& aReqStatus);

Description

Executes a manual synchronization of the ICC phonebook entries.

Parameters

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

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

Description

Test whether the read, edit or search operation specified by the aOp parameter is valid.

Parameters

MContactSynchroniser::TValidateOperation aOperation The operation to validate. TContactItemId aId The contact item that the validation is done against.

Return value

TInt KErrNone if the operation is valid, or an error code (such as KErrAccessDenied or KErrNotFound) if the operation is not valid for that contact item.

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

Description

Writes the contact item to the ICC card. Can be used yo 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 Synchronizer Server will use the first empty slot and aSlotNumber will contain the slot number used on completion.

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.

TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType);

Description

Returns the requested UID. This is the ID type spedified by aIdType which can be either the template ID or the group ID.

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.

TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot);

Description

Update its look-up table with the new contact ID. This method is called when a new entry has been added to the Contacts Database by a client other than the Phonebook Synchronizer Server, because the server can do the update when it knows what the UID of the newly added contact was. The Phonebook Synchronizer 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.

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. Future API enhancement will add a TContactFieldsV2 to contain the new USIM phonebook fields.

Parameters

TDes8& aContactFields On return, the packaged TContactFieldsV1 with the supported field.

Return value

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

TInt GetSyncMode(TPhonebookSyncMode& aSyncMode);

Description

Returns the current setting for the synchronization mode, used by the Phonebook Synchronizer Server at start-up to determine its synchronization policy.

Parameters

TPhonebookSyncMode& aSyncMode On return, the synchronization 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.

TInt SetSyncMode(TPhonebookSyncMode aSyncMode);

Description

Sets a new value for the synchronization mode, used by the Phonebook Synchronizer Server at start-up to determine its synchronization policy.

Parameters

TPhonebookSyncMode aSyncMode The new synchronization 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.

TInt GetPhoneBookCacheState(TSyncState& aState);

Description

Returns the current state of the Phonebook Synchronizer server cache.

Parameters

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

Return value

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

void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel);

Description

Cancels a previously issued asynchronous request.

Parameters

TPhonebookSyncRequestCancel aReqToCancel The request to be cancelled.

class TContactFieldsV1;

Description

The contact fields that can be stored within the phonebook.

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

Construction and destruction

---

TContactFieldsV1()

TContactFieldsV1();

Description

Standard constructor.

Member functions

---

ExtensionId()

TInt ExtensionId() const;

Description

Returns the Phonebook Synchronizer API extension number of the class.

Return value

TInt On return, 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

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.

Internal members

---

iExtensionId

protected: TInt iExtensionId;

Description

This member is internal and not intended for use.

TPhonebookSyncMode

Description

The synchronization mode.

EAutoCurrentIcc Automatic synchronization will be performed with the current ICC. EAutoSameIcc Automatic synchronization will only be performed if the current ICC is the same as the last ICC to be synchonised. EManual Manual synchronization 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.

TSyncIdType

Description

Phonebook identity.

ESyncGroupId Used to allocate a new entry to the right group in the Contacts Database. ESyncTemplateId Used to allocate new ICC entries in the Contacts Database.

typedef TPckg<TContactFieldsV1> TContactFieldsV1Pckg;

Description

A packaged instance of TContactFieldsV1.

private: RPhoneBookSession(const RPhoneBookSession& aSession);

Description

This member is internal and not intended for use.

private: TInt MapContactFormatToInternalL(const CContactICCEntry& aContactItem);

Description

This member is internal and not intended for use.

TInt __DbgMarkHeap();

Description

This member is internal and not intended for use.

TInt __DbgCheckHeap(TInt aCount);

Description

This member is internal and not intended for use.

TInt __DbgMarkEnd(TInt aCount);

Description

This member is internal and not intended for use.

TInt __DbgFailNext(TInt aCount);

Description

This member is internal and not intended for use.

private: void SetTypeOfNumber(const TDesC& aNumber);

Description

This member is internal and not intended for use.

private: CPBSyncPtrHolder* iSyncPtrHolder;

Description

This member is internal and not intended for use.