Collapse all Symbian^3 Product Developer Library

RPhoneBookSession Class Reference

class RPhoneBookSession : public RSessionBase

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.

Inherits from

RPhoneBookSession
- RSessionBase
  - RHandleBase

Nested Classes and Structures

Public Member Functions
	RPhoneBookSession()
IMPORT_C TInt	Connect()
IMPORT_C void	DoSynchronisation(TRequestStatus &)
IMPORT_C void	DoSynchronisation(TRequestStatus &, TUid)
IMPORT_C TInt	GetLastSyncError(TInt &)
IMPORT_C TInt	GetLastSyncError(TInt &, TUid)
IMPORT_C TInt	GetNumSlots(TInt &)
IMPORT_C TInt	GetNumSlots(TInt &, TUid)
IMPORT_C TInt	GetPhoneBookCacheState(TSyncState &)
IMPORT_C TInt	GetPhoneBookCacheState(TSyncState &, TUid)
IMPORT_C TInt	GetPhoneBookId(TContactItemId &, TSyncIdType)
IMPORT_C TInt	GetSlotId(TInt, TContactItemId &)
IMPORT_C TInt	GetSlotId(TInt, TContactItemId &, TUid)
IMPORT_C TInt	GetSyncMode(TPhonebookSyncMode &)
IMPORT_C void	NotifyPhBkCacheStateChange(TRequestStatus &)
IMPORT_C void	NotifyPhBkCacheStateChange(TRequestStatus &, TUid)
IMPORT_C TInt	SetSyncMode(TPhonebookSyncMode)
IMPORT_C TInt	SetSyncMode(TPhonebookSyncMode, TUid)
IMPORT_C TInt	ShutdownServer(TBool)
IMPORT_C TInt	UpdateLookuptable(TContactItemId, TInt)
IMPORT_C TInt	UpdateLookuptable(TContactItemId, TInt, TUid)
IMPORT_C TInt	ValidateContact(MContactSynchroniser::TValidateOperation, TContactItemId)
IMPORT_C TVersion	Version()
IMPORT_C void	WriteContact(TRequestStatus &, CContactICCEntry &, TInt &)
IMPORT_C void	WriteContact(TRequestStatus &, CContactICCEntry &, TInt &, TUid &)
IMPORT_C TInt	__DbgFailNext(TInt)
IMPORT_C TInt	__DbgMarkEnd(TInt)
IMPORT_C TInt	__DbgMarkHeap()

Private Member Functions
	RPhoneBookSession(const RPhoneBookSession &)

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

Public Member Enumerations
enum	TPhonebookSyncMode { EAutoCurrentIcc, EAutoSameIcc, EManual }
enum	TSyncIdType { ESyncGroupId, ESyncTemplateId }
enum	TSyncState { EUnsynchronised, ECacheValid, EErrorDuringSync }

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Public Member Type Definitions
typedef	TPckg< TContactFieldsV1 > TContactFieldsV1Pckg
typedef	TPckg< TContactFieldsV2 > TContactFieldsV2Pckg
typedef	TPckg< TContactFieldsV3 > TContactFieldsV3Pckg

Private Attributes
CSyncClientData *	iData

Inherited Attributes
	RHandleBase::iHandle

Constructor & Destructor Documentation

RPhoneBookSession()

IMPORT_C

RPhoneBookSession

(

)

Standard constructor.

RPhoneBookSession(const RPhoneBookSession &)

RPhoneBookSession

(

const RPhoneBookSession &

aSession

)

[private]

Parameters

const RPhoneBookSession & aSession

Member Functions Documentation

Connect()

IMPORT_C TInt

Connect

(

)

DoSynchronisation(TRequestStatus &)

IMPORT_C void

DoSynchronisation

(

TRequestStatus &

aReqStatus

)

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

capability: ReadUserData

capability: WriteUserData

Parameters

TRequestStatus & aReqStatus

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

DoSynchronisation(TRequestStatus &, TUid)

IMPORT_C void	DoSynchronisation	(	TRequestStatus &	aReqStatus,
			TUid	aPhonebookUid
		)

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

capability: ReadUserData

capability: WriteUserData

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.

GetLastSyncError(TInt &)

IMPORT_C TInt

GetLastSyncError

(

TInt &

aError

)

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

capability: None

Parameters

TInt & aError

Last server cache sync error

GetLastSyncError(TInt &, TUid)

IMPORT_C TInt	GetLastSyncError	(	TInt &	aError,
			TUid	aPhonebookId
		)

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

capability: None

Parameters

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

GetNumSlots(TInt &)

IMPORT_C TInt

GetNumSlots

(

TInt &

aNumSlots

)

const

Parameters

TInt & aNumSlots

GetNumSlots(TInt &, TUid)

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

Parameters

TInt & aNumSlots
TUid aPhonebookId

GetPhoneBookCacheState(TSyncState &)

IMPORT_C TInt

GetPhoneBookCacheState

(

TSyncState &

aState

)

Parameters

TSyncState & aState

GetPhoneBookCacheState(TSyncState &, TUid)

IMPORT_C TInt	GetPhoneBookCacheState	(	TSyncState &	aState,
			TUid	aPhonebookId
		)

Parameters

TSyncState & aState
TUid aPhonebookId

GetPhoneBookId(TContactItemId &, TSyncIdType)

IMPORT_C TInt	GetPhoneBookId	(	TContactItemId &	aId,
			TSyncIdType	aIdType
		)

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.

capability: None

Parameters

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

GetSlotId(TInt, TContactItemId &)

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

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

capability: None

Parameters

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

GetSlotId(TInt, TContactItemId &, TUid)

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

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

capability: None

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

GetSyncMode(TPhonebookSyncMode &)

IMPORT_C TInt

GetSyncMode

(

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.

capability: None

Parameters

TPhonebookSyncMode & aSyncMode

On return, the synchronisation mode.

NotifyPhBkCacheStateChange(TRequestStatus &)

IMPORT_C void

NotifyPhBkCacheStateChange

(

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.

capability: None

Parameters

TRequestStatus & aStatus

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

NotifyPhBkCacheStateChange(TRequestStatus &, TUid)

IMPORT_C void	NotifyPhBkCacheStateChange	(	TRequestStatus &	aStatus,
			TUid	aPhonebookId
		)

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.

capability: None

Parameters

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

SetSyncMode(TPhonebookSyncMode)

IMPORT_C TInt

SetSyncMode

(

TPhonebookSyncMode

aSyncMode

)

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.

capability: None

Parameters

TPhonebookSyncMode aSyncMode

The new synchronisation mode.

SetSyncMode(TPhonebookSyncMode, TUid)

IMPORT_C TInt	SetSyncMode	(	TPhonebookSyncMode	aSyncMode,
			TUid	aPhonebookId
		)

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.

capability: None

Parameters

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

ShutdownServer(TBool)

IMPORT_C TInt

ShutdownServer

(

TBool

aUnconditionally

)

Parameters

TBool aUnconditionally

UpdateLookuptable(TContactItemId, TInt)

IMPORT_C TInt	UpdateLookuptable	(	TContactItemId	aNewUid,
			TInt	aIccSlot
		)

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.

capability: None

Parameters

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

UpdateLookuptable(TContactItemId, TInt, TUid)

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

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

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.

capability: None

Parameters

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

ValidateContact(MContactSynchroniser::TValidateOperation, TContactItemId)

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

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.

capability: ReadUserData

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.

Version()

IMPORT_C TVersion

Version

(

)

const

Returns the current version of the Phonebook Synchroniser Server.

capability: None

WriteContact(TRequestStatus &, CContactICCEntry &, TInt &)

IMPORT_C void	WriteContact	(	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.

capability: WriteUserData

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.

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

IMPORT_C void	WriteContact	(	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.

capability: WriteUserData

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.

__DbgFailNext(TInt)

IMPORT_C TInt

__DbgFailNext

(

TInt

aCount

)

Parameters

TInt aCount

__DbgMarkEnd(TInt)

IMPORT_C TInt

__DbgMarkEnd

(

TInt

aCount

)

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

capability: None

Parameters

TInt aCount

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

__DbgMarkHeap()

IMPORT_C TInt

__DbgMarkHeap

(

)

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

capability: None

Member Enumerations Documentation

Enum TPhonebookSyncMode

The synchronisation mode for phonebooks when the server starts.

Enumerators

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

RPhoneBookSession::GetPhoneBookId()

Enumerators

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.

Enumerators

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.

Member Type Definitions 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 Data Documentation

CSyncClientData * iData

CSyncClientData *

iData

[private]