// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
// which accompanies this distribution, and is available
// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// Phonebook Synchroniser API header file.
// Describes the Phonebook Synchroniser API for use by clients of the
// Phonebook Synchroniser Server.
//
//
/**
@file
@publishedAll
@released
*/
#ifndef __PHBKSYNC_H__
#define __PHBKSYNC_H__
#include <e32std.h>
#include <cntdef.h>
#include <cntdb.h>
#include <cntitem.h>
#include <cntfldst.h>
/**
* Index not supplied.
*/
const TInt KSyncIndexNotSupplied=-1;
//
// TUid Phonebook Types used by Contacts Model
//
#define KUidIccPhonebookNotSpecifiedValue 0x101F7874
#define KUidIccGlobalAdnPhonebookValue 0x101F7875
#define KUidIccGlobalSdnPhonebookValue 0x101F7876
#define KUidIccGlobalLndPhonebookValue 0x101F7877
#define KUidUsimAppAdnPhonebookValue 0x101F7878
#define KUidIccGlobalFdnPhonebookValue 0x101FB2AF
const TUid KUidIccPhonebookNotSpecified = {KUidIccPhonebookNotSpecifiedValue};
const TUid KUidIccGlobalAdnPhonebook = {KUidIccGlobalAdnPhonebookValue};
const TUid KUidIccGlobalSdnPhonebook = {KUidIccGlobalSdnPhonebookValue};
const TUid KUidIccGlobalLndPhonebook = {KUidIccGlobalLndPhonebookValue};
const TUid KUidUsimAppAdnPhonebook = {KUidUsimAppAdnPhonebookValue};
const TUid KUidIccGlobalFdnPhonebook = {KUidIccGlobalFdnPhonebookValue};
/**
* Types of cancel requests for the asynchronous server requests.
*
* @see RPhoneBookSession::CancelRequest
*/
enum TPhonebookSyncRequestCancel
{
/** Cancel the asynchronous RPhoneBookSession::DoSynchronisation() request */
EDoSynchronisationCancelClient,
/** Cancel the asynchronous RPhoneBookSession::DeleteContact() request */
ESyncDeleteCntFromICCCancelClient,
/** Cancel the asynchronous RPhoneBookSession::WriteContact() request */
ESyncWriteCntToICCCancelClient,
/** Cancel the asynchronous RPhoneBookSession::NotifyPhBkCacheStateChange() request */
ESyncNotifyCacheStateChangeCancelClient
};
/**
* Class to hold the contact field formats.
*
* @publishedAll
* @released
*/
class TContactFieldFormat
{
public:
TContactFieldFormat(TInt aLength, TInt aCount, TBool aDisplayed);
public:
/** The maximum length (i.e. number of characters) of the field. If the field is
not a string type this attribute should be ignored. */
TInt iLength;
/** The maximum number of instances of this field within an item. This is set to
-1 if this is unlimited. */
TInt iCount;
/** Indicates whether this is displayed or hidden. */
TBool iDisplayed;
};
//
// Forward declare the internal data storage class.
//
class CSyncClientData;
/**
* 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.
*
* @publishedAll
* @released
*/
class RPhoneBookSession : public RSessionBase
{
public:
/**
* Structure holding the template ID and buffer size. The client has
* no need to use this structure.
*
* @deprecated
*/
struct TTemplateAndBufferSize
{
TContactItemId templateId;
TInt bufferSize;
};
/**
* The synchronisation mode for phonebooks when the server starts.
*/
enum TPhonebookSyncMode
{
/** Automatic synchronisation will be performed. */
EAutoCurrentIcc,
/** Automatic synchronisation will only be performed if the current ICC is
the same as the last ICC to be synchonised. */
EAutoSameIcc,
/** Manual synchronisation will be performed when requested. */
EManual
};
/**
* The phonebook cache state.
*/
enum TSyncState
{
/** The server has not yet populated the Contacts Database. */
EUnsynchronised,
/** The server has finished populating the Contacts Database. */
ECacheValid,
/** The server encountered an error populating the Contacts Database. */
EErrorDuringSync
};
/**
* Specifies format of phonebook fields within an ICC phonebook entry.
*
* @publishedAll
* @released
*/
class TContactFieldsV1
{
public:
/**
* Enumeration to describe the version ID of the Phonebook Synchronizer.
*/
enum TContactFieldsExtensionId
{
/** Phonebook Synchronizer version 1 */
KPhBkSyncTContactFieldsV1,
/** Phonebook Synchronizer version 2 */
KPhBkSyncTContactFieldsV2,
/** Phonebook Synchronizer version 3 */
KPhBkSyncTContactFieldsV3
};
/**
* Returns the Phonebook Synchronizer API extension number of the class.
*
* @return The version ID from TContactFieldsExtensionId.
*/
IMPORT_C TInt ExtensionId() const;
/**
* Standard constructor.
*/
IMPORT_C TContactFieldsV1();
public:
/** The format of the name field within an ICC phonebook entry. */
TContactFieldFormat iNameField;
/** The format of the number field within an ICC phonebook entry. */
TContactFieldFormat iNumberField;
/** The format of the ICC slot number field within an ICC phonebook entry. */
TContactFieldFormat iIccSlotField;
protected:
TInt iExtensionId;
};
/**
* A packaged instance of TContactFieldsV1.
*/
typedef TPckg<TContactFieldsV1> TContactFieldsV1Pckg;
/**
* Specifies format of phonebook fields within an UICC phonebook entry
*
* @publishedAll
* @released
*/
class TContactFieldsV2 : public TContactFieldsV1
{
public:
IMPORT_C TContactFieldsV2();
public:
/** The format of any additional number fields within an ICC phonebook entry. */
TContactFieldFormat iAdditionalNumString;
/** The format of group field within an ICC phonebook entry. */
TContactFieldFormat iGroupField;
/** The format of email field within an ICC phonebook entry. */
TContactFieldFormat iEmailField;
/** The UID of the phonebook. */
TUid iPhonebook;
};
/**
* A packaged instance of TContactFieldsV2.
*/
typedef TPckg<TContactFieldsV2> TContactFieldsV2Pckg;
/**
* Specifies additional format information for phonebook fields within a
* UICC phonebook entry.
*
* @publishedAll
* @released
*/
class TContactFieldsV3 : public TContactFieldsV2
{
public:
IMPORT_C TContactFieldsV3();
public:
/** The format of an addition number's text field within an ICC phonebook entry. */
TContactFieldFormat iAdditionalNumAlphaString;
/** The format of the second name field within an ICC phonebook entry. */
TContactFieldFormat iSecondNameField;
};
/**
* A packaged instance of TContactFieldsV3.
*/
typedef TPckg<TContactFieldsV3> TContactFieldsV3Pckg;
/**
* The phonebook ID type requested from a phonebook. There are two types of IDs
* (group IDs and template IDs).
*
* @see RPhoneBookSession::GetPhoneBookId()
*/
enum TSyncIdType
{
/** Used to allocate a new entry to the right group in the Contacts Database. */
ESyncGroupId,
/** Used to define new ICC entries in the Contacts Database. */
ESyncTemplateId
};
public:
IMPORT_C RPhoneBookSession();
IMPORT_C TInt Connect();
IMPORT_C void Close();
IMPORT_C TVersion Version() const;
IMPORT_C TInt ShutdownServer (TBool aUnconditionally);
//
// Single (ADN) phonebook support and functions not requiring a phonebook UID.
//
IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus);
IMPORT_C TInt ValidateContact(MContactSynchroniser::TValidateOperation aOperation, TContactItemId aId);
IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem,
TInt& aSlotNumber);
IMPORT_C void DeleteContact(TRequestStatus& aReqStatus, TContactItemId aId);
IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType);
IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot);
IMPORT_C TInt GetContactFormat(TDes8& aContactFields);
IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode);
IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode);
IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState);
IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel);
IMPORT_C TInt GetLastSyncError(TInt& aError);
IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus);
IMPORT_C TInt GetNumSlots(TInt& aNumSlots) const;
IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots) const;
IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId) const;
//
// Multiple phonebooks support. These should be used in preference to the above
// ADN specific versions.
//
IMPORT_C void DoSynchronisation(TRequestStatus& aReqStatus, TUid aPhonebookUid);
IMPORT_C void WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem,
TInt& aSlotNumber, TUid& aPhonebookUid);
IMPORT_C TInt GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType, TUid aPhonebookUid);
IMPORT_C TInt UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot, TUid aPhonebookUid);
IMPORT_C TInt GetSyncMode(TPhonebookSyncMode& aSyncMode, TUid aPhonebookId);
IMPORT_C TInt SetSyncMode(TPhonebookSyncMode aSyncMode, TUid aPhonebookId);
IMPORT_C TInt GetPhoneBookCacheState(TSyncState& aState, TUid aPhonebookId);
IMPORT_C void CancelRequest(TPhonebookSyncRequestCancel aReqToCancel, TUid aPhonebookId);
IMPORT_C TInt GetLastSyncError(TInt& aError, TUid aPhonebookId);
IMPORT_C void NotifyPhBkCacheStateChange(TRequestStatus& aStatus, TUid aPhonebookId);
IMPORT_C TInt GetNumSlots(TInt& aNumSlots, TUid aPhonebookId) const;
IMPORT_C void GetFreeSlotsL(RArray<TInt>& aFreeSlots, TUid aPhonebookId) const;
IMPORT_C TInt GetSlotId(TInt aSlot, TContactItemId& aId, TUid aPhonebookId) const;
//
// Memory checking functionality for Debug builds only.
//
IMPORT_C TInt __DbgMarkHeap();
IMPORT_C TInt __DbgCheckHeap(TInt aCount);
IMPORT_C TInt __DbgMarkEnd(TInt aCount);
IMPORT_C TInt __DbgFailNext(TInt aCount);
private:
RPhoneBookSession(const RPhoneBookSession& aSession);
private:
/* Temporary data used by the session. */
CSyncClientData* iData;
};
#endif