S60 3rd Edition API Reference: cpbkcontactengine.h Source File

00001 /*
00002 * ============================================================================
00003 *  Name     : CPbkContactEngine.h from PbkEng.dll
00004 *  Part of  : PbkEng.dll
00005 *
00006 *  Description:
00007 *     Represents a connection to the Phonebook contact database
00008 *  Version:
00009 *
00010 *  Copyright (C) 2002 Nokia Corporation.
00011 *  This material, including documentation and any related
00012 *  computer programs, is protected by copyright controlled by
00013 *  Nokia Corporation. All rights are reserved. Copying,
00014 *  including reproducing, storing,  adapting or translating, any
00015 *  or all of this material requires the prior written consent of
00016 *  Nokia Corporation. This material also contains confidential
00017 *  information which may not be disclosed to others without the
00018 *  prior written consent of Nokia Corporation.
00019 * ============================================================================
00020 */
00021 
00022 #ifndef __CPBKCONTACTENGINE_H__
00023 #define __CPBKCONTACTENGINE_H__
00024 
00025 //  INCLUDES
00026 #include <e32base.h>        // CBase
00027 #include <cntdef.h>         // TContactItemId
00028 #include <cntdbobs.h>       // MContactDbObserver
00029 #include <f32file.h>        // RFs
00030 #include "PbkFields.hrh"    // TPbkFieldId
00031 
00032 
00033 // FORWARD DECLARATIONS
00034 class CContactDatabase;
00035 class MIdleFindObserver;
00036 class MPbkContactDbObserver;
00037 class CContactGroup;
00038 class CPbkFieldsInfo;
00039 class CPbkContactItem;
00040 class CPbkContactIter;
00041 class CPbkContactChangeNotifier;
00042 class CPbkIdleFinder;
00043 class MPbkCompressUi;
00044 class CPbkConstants;
00045 class MPbkContactNameFormat;
00046 class MPbkFieldDataArray;
00047 class CContactViewBase;
00048 class CContactItem;
00049 class RSharedDataClient;
00050 class TResourceReader;
00051 class CPbkEngineExtension;
00052 class CPbkSortOrderManager;
00053 #start_since SINCE_3_1_SDK
00054 class CPbkSINDHandlerInterface;
00055 #end_since SINCE_3_1_SDK
00056 
00057 
00058 // CLASS DECLARATION
00059 
00068 class   CPbkContactEngine :
00069         public CBase,
00070         private MContactDbObserver
00071     {
00072     public: // Constructors and destructor
00085                 IMPORT_C static CPbkContactEngine* NewL(RFs* aFs=NULL);
00086 
00105                 IMPORT_C static CPbkContactEngine* NewL
00106             (const TDesC& aFileName, TBool aReplace=EFalse, RFs* aFs=NULL);
00107 
00121         IMPORT_C static CPbkContactEngine* ReplaceL(RFs* aFs=NULL);
00122 
00130                 ~CPbkContactEngine();
00131 
00132     public: // Accessors
00142         IMPORT_C static CPbkContactEngine* Static();
00143 
00151         IMPORT_C CContactDatabase& Database();
00152 
00158         IMPORT_C const CPbkFieldsInfo& FieldsInfo();
00159 
00164         IMPORT_C RFs& FsSession() const;
00165 
00166     public:  // Creating contacts
00171         IMPORT_C CPbkContactItem* CreateEmptyContactL();
00172 
00184         IMPORT_C TContactItemId AddNewContactL
00185             (CPbkContactItem& aContact, TBool aImmediateNotify=EFalse);
00186 
00197         IMPORT_C TContactItemId DuplicateContactL
00198             (TContactItemId aId, TBool aImmediateNotify=EFalse);
00199 
00200     public:  // Reading contacts
00215         IMPORT_C CPbkContactItem* ReadContactL
00216             (TContactItemId aContactId, const CPbkFieldIdArray* aFieldTypes=NULL);
00217 
00232         IMPORT_C CPbkContactItem* ReadContactLC
00233             (TContactItemId aContactId, const CPbkFieldIdArray* aFieldTypes=NULL);
00234 
00244         IMPORT_C CPbkContactItem* ReadMinimalContactLC(TContactItemId aContactId);
00245 
00254         IMPORT_C CPbkContactIter* CreateContactIteratorLC
00255             (TBool aUseMinimalRead=EFalse);
00256 
00257     public:  // Modifying contacts
00264         IMPORT_C CPbkContactItem* OpenContactL(TContactItemId aContactId);
00265 
00276         IMPORT_C CPbkContactItem* OpenContactLCX(TContactItemId aContactId);
00277 
00289         IMPORT_C void CommitContactL
00290             (CPbkContactItem& aContact, TBool aImmediateNotify=EFalse);
00291 
00297         IMPORT_C void CloseContactL(TContactItemId aContactId);
00298 
00299     public:  // Deleting contacts
00309         IMPORT_C void DeleteContactL
00310             (TContactItemId aContactId, TBool aImmediateNotify=EFalse);
00311 
00321         IMPORT_C void DeleteContactsL
00322             (const CContactIdArray& aContactIds, TBool aImmediateNotify=EFalse);
00323 
00330         IMPORT_C void DeleteContactsOnBackgroundL
00331             (const CContactIdArray& aContactIds);
00332 
00333     public:  // Contact groups
00342         IMPORT_C CContactGroup* CreateContactGroupL
00343             (const TDesC& aGroupLabel,TBool aInTransaction=EFalse);
00344 
00352         IMPORT_C void AddContactToGroupL
00353             (TContactItemId aItemId, TContactItemId aGroupId);
00354 
00362         IMPORT_C void RemoveContactFromGroupL
00363             (TContactItemId aItemId, TContactItemId aGroupId);
00364 
00372         IMPORT_C CContactGroup* ReadContactGroupL(TContactItemId aId);
00373 
00381         IMPORT_C CContactGroup* OpenContactGroupL(TContactItemId aId);
00382 
00391         IMPORT_C CContactGroup* OpenContactGroupLCX(TContactItemId aId);
00392 
00403         IMPORT_C void CommitContactGroupL(CContactGroup& aGroup, TBool aImmediateNotify=EFalse);
00404 
00414         IMPORT_C void DeleteContactGroupL
00415             (TContactItemId aContactId, TBool aImmediateNotify=EFalse);
00416 
00417     public:  // Speed dials
00427         IMPORT_C void SetFieldAsSpeedDialL
00428             (CPbkContactItem& aItem, TInt aFieldIndex, TInt aSpeedDialPosition);
00429 
00437         IMPORT_C TContactItemId GetSpeedDialFieldL
00438             (TInt aSpeedDialPosition, TDes& aPhoneNumber) const;
00439 
00447         IMPORT_C void RemoveSpeedDialFieldL
00448             (TContactItemId aContactId, TInt aSpeedDialPosition);
00449 
00458         IMPORT_C TBool IsSpeedDialAssigned
00459             (const CPbkContactItem& aItem, TInt aFieldIndex) const;
00460 
00461     public:  // Contact views
00469         IMPORT_C CContactViewBase& AllContactsView();
00470 
00478         IMPORT_C CContactViewBase& AllGroupsViewL();
00479 
00487         IMPORT_C CContactViewBase& FilteredContactsViewL(TInt aFilter);
00488 
00489     public:  // Events
00501         IMPORT_C CPbkContactChangeNotifier* CreateContactChangeNotifierL
00502             (MPbkContactDbObserver* aObserver);
00503 
00504     public:  // Contact name formatting
00514         IMPORT_C HBufC* GetContactTitleL(const CPbkContactItem& aItem) const;
00515 
00525         IMPORT_C HBufC* GetContactTitleOrNullL
00526             (const MPbkFieldDataArray& aContactData);
00527 
00538         IMPORT_C TBool IsTitleField(TPbkFieldId aFieldId) const;
00539 
00547         IMPORT_C MPbkContactNameFormat& ContactNameFormat() const;
00548 
00553         IMPORT_C const TDesC& UnnamedTitle() const;
00554 
00555     public: // Searching
00565         IMPORT_C CContactIdArray* MatchPhoneNumberL
00566             (const TDesC& aNumber, const TInt aMatchLengthFromRight);
00567 
00583         IMPORT_C CContactIdArray* FindLC
00584             (const TDesC& aText, const CPbkFieldIdArray* aFieldTypes=NULL);
00585 
00605             IMPORT_C CPbkIdleFinder* FindAsyncL(
00606             const TDesC& aText,
00607             const CPbkFieldIdArray* aFieldTypes=NULL,
00608             MIdleFindObserver *aObserver=NULL);
00609 
00610     public:  // Phonebook internal API
00621         IMPORT_C void SetCompressUi(MPbkCompressUi* aCompressiUi);
00622 
00633         IMPORT_C TBool CheckCompress();
00634 
00643         IMPORT_C void CompressL();
00644 
00655         IMPORT_C void CancelCompress();
00656 
00668         IMPORT_C void CheckFileSystemSpaceAndCompressL();
00669 
00675                 enum TPbkNameOrder
00676                         {
00677                         EPbkNameOrderLastNameFirstName = 0, 
00678                         EPbkNameOrderFirstNameLastName 
00679 #start_since SINCE_3_1_SDK
00680                         ,EPbkNameOrderNotDefined 
00681 #end_since SINCE_3_1_SDK
00682                         };
00683 
00690                 IMPORT_C void SetNameDisplayOrderL(TPbkNameOrder aNameOrder);
00691 
00698                 IMPORT_C TPbkNameOrder NameDisplayOrderL();
00699 
00706                 IMPORT_C CPbkConstants* Constants();
00707 
00712         const CPbkSortOrderManager& SortOrderManager() const;
00713 
00714 
00723                 IMPORT_C void SetNameSeparatorL(TChar aSeparator);
00724 
00732                 IMPORT_C TChar NameSeparator() const;
00733 
00734 
00735 
00736     private:  // from MContactDbObserver
00737         void HandleDatabaseEventL(TContactDbObserverEvent aEvent);
00738 
00739     private:  // Interface for CPbkContactChangeNotifier
00740         friend class CPbkContactChangeNotifier;
00741         void AddObserverL(MPbkContactDbObserver* aObserver);
00742         void RemoveObserver(MPbkContactDbObserver* aObserver);
00743         void SendEventToAllObservers(const TContactDbObserverEvent& aEvent);
00744 
00745     private:  // Implementation
00746                 CPbkContactEngine();
00747                 void ConstructL(const TDesC* aFileName, TBool aReplace, RFs* aFs);
00748         void ConnectFsL(RFs* aRfs);
00749         void ReadResourcesL(TBool& aSettingsVisibility);
00750         void CreateDbConnectionL(const TDesC* aFileName, 
00751                                  TBool aReplace, 
00752                                  TInt& aDbOpenError,
00753                                  TBool aSettingsVisible);
00754         void SendImmidiateEventToAllObservers(
00755             TContactDbObserverEventType aEventType,
00756             TContactItemId aContactId, TBool aSendEvent);
00757         void doDeleteContactL(TContactItemId aContactId);
00758         class CContactDbConnection;
00759         friend class CContactDbConnection;
00760                 friend class CPbkSharedDataObserver;
00761 
00762     private:  // Data
00764         RFs iFs;
00766         RFs iOwnFs;
00768                 CContactDbConnection* iDbConnection;
00770         CArrayPtr<MPbkContactDbObserver>* iObservers;
00772         CPbkFieldsInfo* iPbkFieldsInfo;
00774         CPbkConstants* iPbkConstants;
00776         RSharedDataClient* iSharedDataClient;
00778         TInt iFreeSpaceRequiredToDelete;
00780         CPbkEngineExtension* iExtension;
00782         TBool iUseSeparator;
00784         TChar iSeparator;
00786         TUid iDtorIDKey;
00788         CPbkSINDHandlerInterface* iSINDHandler;
00789 
00790 
00791 
00792     };
00793 
00794 // __CPBKCONTACTENGINE_H__
00795 #endif
00796 
00797 // End of File