williamr@4: /* williamr@4: * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: The contact manager for accessing different stores. williamr@4: * Initialization: a client gives an array of store URIs (Virtual williamr@4: * offers some URIs, see VPbkStoreUriLiterals.h) when creating williamr@4: * a manager. The client uses store list to open all stores. williamr@4: * williamr@4: */ williamr@4: williamr@4: williamr@4: #ifndef CVPBKCONTACTMANAGER_H williamr@4: #define CVPBKCONTACTMANAGER_H williamr@4: williamr@4: williamr@4: // INCLUDES williamr@4: #include williamr@4: #include williamr@4: #include williamr@4: #include williamr@4: williamr@4: // FORWARD DECLARATIONS williamr@4: class MVPbkFieldTypeList; williamr@4: class MVPbkContactManagerObserver; williamr@4: class MVPbkContactStoreList; williamr@4: class CVPbkContactStoreList; williamr@4: class MVPbkStoreContact; williamr@4: class MVPbkContactLink; williamr@4: class MVPbkContactOperationBase; williamr@4: class MVPbkSingleContactOperationObserver; williamr@4: class MVPbkBatchOperationObserver; williamr@4: class MVPbkContactFindObserver; williamr@4: class MVPbkContactViewBase; williamr@4: class CVPbkContactViewDefinition; williamr@4: class MVPbkContactStore; williamr@4: class TVPbkContactStoreUriPtr; williamr@4: class CVPbkContactStoreDomainList; williamr@4: class MVPbkContactViewObserver; williamr@4: class MVPbkContactLinkArray; williamr@4: class MVPbkContactAttributeManager; williamr@4: class CVPbkContactStoreUriArray; williamr@4: class MVPbkContactFindFromStoresObserver; williamr@4: williamr@4: // CLASS DECLARATIONS williamr@4: williamr@4: /** williamr@4: * Virtual Phonebook Contact Manager. Contact Manager is the root access point williamr@4: * to Virtual Phonebook engine functionality. The client can specify the list williamr@4: * of stores in the constructor he/she is interested in or load additional williamr@4: * plug-ins later on. In addition to loading the implementing plug-ins the williamr@4: * client must open the stores. Clients should share the contact manager williamr@4: * instance within their context, otherwise e.g. field types from two williamr@4: * different instances will not produce the matches as the matching is williamr@4: * based on pointer comparison. williamr@4: * williamr@4: * Examples of absolute URI stores: williamr@4: * Default contact database: "cntdb://contacts.cdb" williamr@4: * LDAP store: "ldap://www.telnumbers.com/" williamr@4: * The URI scheme name is used to resolve a store capable of supporting williamr@4: * this type of store. The actual store implementations are ECom plugins. williamr@4: * williamr@4: * @lib VPbkEng.lib williamr@4: */ williamr@4: class CVPbkContactManager : public CBase williamr@4: { williamr@4: public: // Constructors and destructor williamr@4: /** williamr@4: * Creates a contact manager instance and loads the plug-ins that can williamr@4: * handle the stores corresponding to the aURIList. williamr@4: * @param aURIList Universal Resource Identifier list of the stores williamr@4: * to be loaded initially. williamr@4: * @param aFs File system handle. NULL opens a new connection. williamr@4: * @return Contact manager instance. williamr@4: */ williamr@4: IMPORT_C static CVPbkContactManager* NewL( williamr@4: const CVPbkContactStoreUriArray& aURIList, williamr@4: RFs* aFs = NULL); williamr@4: williamr@4: /** williamr@4: * Creates a contact manager instance and loads the plug-ins that can williamr@4: * handle the stores corresponding to the aURIList. williamr@4: * @param aSecurityInfo Security info from caller to be passed for stores. williamr@4: * Stores can check security info and deside williamr@4: * if client can use service. williamr@4: * @param aURIList Universal Resource Identifier list of the stores williamr@4: * to be loaded initially. williamr@4: * @param aFs File system handle. NULL opens a new connection. williamr@4: * @return Contact manager instance. williamr@4: */ williamr@4: IMPORT_C static CVPbkContactManager* NewL( williamr@4: TSecurityInfo aSecurityInfo, williamr@4: const CVPbkContactStoreUriArray& aURIList, williamr@4: RFs* aFs = NULL); williamr@4: williamr@4: /** williamr@4: * Destructor. williamr@4: */ williamr@4: ~CVPbkContactManager(); williamr@4: williamr@4: public: // Interface williamr@4: /** williamr@4: * The contact manager owns a master list of field types that clients williamr@4: * use. The store implementation then maps their native types williamr@4: * to Virtual Phonebook types. Clients don't create field type objects williamr@4: * themselves but use always references to types offered williamr@4: * by this function. williamr@4: * williamr@4: * @return The global list of field types. williamr@4: */ williamr@4: IMPORT_C const MVPbkFieldTypeList& FieldTypes() const; williamr@4: williamr@4: /** williamr@4: * The contact store list is used to handle a set of stores. williamr@4: * After creation of manager the client can use the list to open williamr@4: * all stores. williamr@4: * williamr@4: * @return The list of available contact stores. williamr@4: */ williamr@4: IMPORT_C MVPbkContactStoreList& ContactStoresL(); williamr@4: williamr@4: /** williamr@4: * Loads a store plug-in for given URI and adds aURI williamr@4: * to the list of stores handled by this manager. williamr@4: * If there is no store plug-in for the aURI then nothing changes. williamr@4: * williamr@4: * @param aURI the store URI to be loaded. williamr@4: */ williamr@4: IMPORT_C void LoadContactStoreL(const TVPbkContactStoreUriPtr& aURI); williamr@4: williamr@4: /** williamr@4: * Attribute manager is used for handling contact attributes like williamr@4: * speed dialing or defaults. williamr@4: * williamr@4: * @returns The contact attribute manager. williamr@4: */ williamr@4: IMPORT_C MVPbkContactAttributeManager& ContactAttributeManagerL(); williamr@4: williamr@4: /** williamr@4: * Creates a new contact view specified by the view definition. williamr@4: * The view can not be used before it has notified the observer williamr@4: * that it is ready. williamr@4: * williamr@4: * @param aObserver the observer for view events. williamr@4: * @param aViewDefinition Definition of the view to create williamr@4: * @param aSortOrder a list of field types that defines fields williamr@4: * that are used in sorting. View contacts williamr@4: * have these fields. However, the store can have restrictions williamr@4: * for types that can be used in the sort order. williamr@4: * The sort order has no effect for shared views that have williamr@4: * already been created. williamr@4: * williamr@4: * @see CVPbkSortOrder williamr@4: * @return Newly created view. williamr@4: * If NULL CleanupStack pop is still needed williamr@4: */ williamr@4: IMPORT_C MVPbkContactViewBase* CreateContactViewLC( williamr@4: MVPbkContactViewObserver& aObserver, williamr@4: const CVPbkContactViewDefinition& aViewDefinition, williamr@4: const MVPbkFieldTypeList& aSortOrder) const; williamr@4: williamr@4: /** williamr@4: * Retrieves asynchronously a contact that is individualized by williamr@4: * a contact link. Delete the operation for canceling. williamr@4: * williamr@4: * @param aLink a link to the contact williamr@4: * @param aObserver operation observer williamr@4: * @return New handle to the operation williamr@4: * @Asynchronous williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* RetrieveContactL( williamr@4: const MVPbkContactLink& aLink, williamr@4: MVPbkSingleContactOperationObserver& aObserver) const; williamr@4: williamr@4: /** williamr@4: * Creates an array of links corresponding to a packaged link or links. williamr@4: * Packed links have been obtained by packing a link or a link array williamr@4: * and they can be used for example for IPC but not for saving links. williamr@4: * Loads the store plug-ins that are capable of creating the williamr@4: * appropriate links. williamr@4: * williamr@4: * @param aPackedLinks packed links williamr@4: * @return A link array. williamr@4: * @see MVPbkContactLink::PackLC williamr@4: * @see MVPbkContactLinkArray::PackLC williamr@4: */ williamr@4: IMPORT_C MVPbkContactLinkArray* CreateLinksLC( williamr@4: const TDesC8& aPackedLinks) const; williamr@4: williamr@4: /** williamr@4: * Internalizes a permanent link or links. An externalized link williamr@4: * has been created using MVPbkStreamable interface from williamr@4: * MVPbkContactLink. williamr@4: * Loads the store plug-ins that are capable of creating the williamr@4: * appropriate links. williamr@4: * williamr@4: * @param aStream a stream that contains a link or links. williamr@4: * @return A link array williamr@4: * @see MVPbkContactLink::Streamable williamr@4: */ williamr@4: IMPORT_C MVPbkContactLinkArray* CreateLinksLC( williamr@4: RReadStream& aStream) const; williamr@4: williamr@4: /** williamr@4: * Deletes contacts defined in link array asynchronously. williamr@4: * williamr@4: * @param aContactLinks Contacts to delete williamr@4: * @param aObserver Operation observer williamr@4: * @return New handle to the operation williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* DeleteContactsL( williamr@4: const MVPbkContactLinkArray& aContactLinks, williamr@4: MVPbkBatchOperationObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Commits all contacts in aContacts asynchronously. williamr@4: * williamr@4: * @see MVPbkStoreContact::CommitL williamr@4: * @param aContacts Contacts to commit. williamr@4: * @param aObserver Operation observer. williamr@4: * @return New handle to the operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* CommitContactsL( williamr@4: const TArray& aContacts, williamr@4: MVPbkBatchOperationObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Copies all contacts in aContactLinks to aTargetStore asynchronously. williamr@4: * If aTargetStore is NULL, contacts are copied to the store where williamr@4: * they already are, ie. the contacts are duplicated. williamr@4: * williamr@4: * @param aContactLinks Array of contact links to duplicate. williamr@4: * @param aTargetStore Target store to copy contacts to. williamr@4: * If NULL this behaves like duplicate. williamr@4: * @param aObserver Observer for the copying process. williamr@4: * @return New handle to the operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* CopyContactsL( williamr@4: const MVPbkContactLinkArray& aContactLinks, williamr@4: MVPbkContactStore* aTargetStore, williamr@4: MVPbkBatchOperationObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Searches the contact stores for a phone number using williamr@4: * defined amount of digits from the end of the number asynchronously. williamr@4: * The store implementations determine, which field types are included williamr@4: * in the search. williamr@4: * williamr@4: * @param aPhoneNumber Phone number to search for. williamr@4: * @param aMaxMatchDigits Maximum number of digits to match williamr@4: * from the end of the number. williamr@4: * @param aObserver Observer for the find process. williamr@4: * @return New handle to the find operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* MatchPhoneNumberL( williamr@4: const TDesC& aPhoneNumber, williamr@4: TInt aMaxMatchDigits, williamr@4: MVPbkContactFindObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Searches the contact stores for a contact that contains williamr@4: * the given string in one of the field defined by given williamr@4: * field type list asynchronously. williamr@4: * NOTE: In some cases the find matches also other fields than williamr@4: * those specified in aFieldTypes. Always loop through the williamr@4: * results to check match in the required fields. williamr@4: * williamr@4: * @param aSearchString String to search for. williamr@4: * @param aFieldTypes List of field types that the search will include. williamr@4: * a field type list: use CVPbkFieldTypeRefsList and williamr@4: * append the types that are needed from williamr@4: * the master field type list (FieldTypes()) williamr@4: * to the reference list. Selection can be done williamr@4: * in a dynamic way using CVPbkFieldTypeSelector or williamr@4: * static way using resource ids of the field types. williamr@4: * @param aObserver Observer for the find process. williamr@4: * @return New handle to the find operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* FindL( williamr@4: const TDesC& aSearchString, williamr@4: const MVPbkFieldTypeList& aFieldTypes, williamr@4: MVPbkContactFindObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Finds a string containing text that is stored in one or more williamr@4: * fields asynchronously. Client can give multiple find words. williamr@4: * All the words must match to separated data. E.g. if there are williamr@4: * two find words: "Jo" and "Jo" then field data "John Johnson" williamr@4: * matches but "John Doe" doesn't if the word parser uses williamr@4: * white space as a word separator. williamr@4: * williamr@4: * NOTE: The accuracy of the results depends on the implementation williamr@4: * of the store to carry out the find operation. The performance williamr@4: * can also vary depending on the store. williamr@4: * williamr@4: * @param aSearchStrings strings that are compared to field data. williamr@4: * @param aFieldTypes types of the fields that are used. Constructing williamr@4: * a fieldtype list: use CVPbkFieldTypeRefsList and williamr@4: * append the types that are needed from williamr@4: * the master fieldtype list (FieldTypes()) williamr@4: * to the reference list. Selection can be done williamr@4: * in a dynamic way using CVPbkFieldTypeSelector or williamr@4: * static way using resource ids of the fieldtypes. williamr@4: * williamr@4: * @param aObserver an observer for asynchronous operation. williamr@4: * @param aWordParserCallBack a client implementation of word parser williamr@4: * function that separates the field data williamr@4: * into words. Parameter to function is williamr@4: * TVPbkWordParserParam. williamr@4: * @return New handle to the find operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* FindL( williamr@4: const MDesC16Array& aSearchStrings, williamr@4: const MVPbkFieldTypeList& aFieldTypes, williamr@4: MVPbkContactFindFromStoresObserver& aObserver, williamr@4: const TCallBack& aWordParserCallBack ); williamr@4: williamr@4: /** williamr@4: * Compresses all stores asynchronously. williamr@4: * NOTE: Not all stores are able to implement compression to their williamr@4: * repositories. williamr@4: * williamr@4: * @param aObserver Operation observer. williamr@4: * @return New handle to the operation. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* CompressStoresL( williamr@4: MVPbkBatchOperationObserver& aObserver); williamr@4: williamr@4: /** williamr@4: * Returns the file server session of the contact manager. williamr@4: * williamr@4: * @return File server session of the contact manager. williamr@4: */ williamr@4: IMPORT_C RFs& FsSession(); williamr@4: williamr@4: williamr@4: /** williamr@4: * Finds a string containing text that is stored in one or more williamr@4: * fields asynchronously. Client can give multiple find words. williamr@4: * All the words must match to separated data. E.g. if there are williamr@4: * two find words: "Jo" and "Jo" then field data "John Johnson" williamr@4: * matches but "John Doe" doesn't if the word parser uses williamr@4: * white space as a word separator. williamr@4: * williamr@4: * NOTE: The accuracy of the results depends on the implementation williamr@4: * of the store to carry out the find operation. The performance williamr@4: * can also vary depending on the store. williamr@4: * williamr@4: * @param aSearchStrings strings that are compared to field data. williamr@4: * @param aFieldTypes types of the fields that are used. Constructing williamr@4: * a fieldtype list: use CVPbkFieldTypeRefsList and williamr@4: * append the types that are needed from williamr@4: * the master fieldtype list (FieldTypes()) williamr@4: * to the reference list. Selection can be done williamr@4: * in a dynamic way using CVPbkFieldTypeSelector or williamr@4: * static way using resource ids of the fieldtypes. williamr@4: * williamr@4: * @param aObserver an observer for asynchronous operation. williamr@4: * @param aWordParserCallBack a client implementation of word parser williamr@4: * function that separates the field data williamr@4: * into words. Parameter to function is williamr@4: * TVPbkWordParserParam. williamr@4: * @param aStoreEntriesArray an array that lists the store entries williamr@4: * @return New handle to the find operation or NULL if it could not be created. williamr@4: */ williamr@4: IMPORT_C MVPbkContactOperationBase* FindL( williamr@4: const MDesC16Array& aSearchStrings, williamr@4: const MVPbkFieldTypeList& aFieldTypes, williamr@4: MVPbkContactFindFromStoresObserver& aObserver, williamr@4: const TCallBack& aWordParserCallBack, williamr@4: const CDesC16ArrayFlat& aStoreEntriesArray ); williamr@4: williamr@4: private: // Implementation williamr@4: CVPbkContactManager( TSecurityInfo aSecurityInfo, RFs* aFs ); williamr@4: void ConstructL(const CVPbkContactStoreUriArray& aURIList); williamr@4: MVPbkContactStore* FindStore(const TVPbkContactStoreUriPtr& aURI) const; williamr@4: MVPbkContactViewBase* CreateOptimizedCompositeViewLC( williamr@4: MVPbkContactViewObserver& aObserver, williamr@4: const CVPbkContactViewDefinition& aViewDefinition, williamr@4: const MVPbkFieldTypeList& aSortOrder) const; williamr@4: MVPbkContactViewBase* CreateCompositeViewLC( williamr@4: MVPbkContactViewObserver& aObserver, williamr@4: const CVPbkContactViewDefinition& aViewDefinition, williamr@4: const MVPbkFieldTypeList& aSortOrder) const; williamr@4: williamr@4: private: // Data williamr@4: /// Own: Security info for client. williamr@4: TSecurityInfo iSecurityInfo; williamr@4: /// Own: File system handle williamr@4: RFs iFs; williamr@4: /// Own: File system handle that is owned williamr@4: RFs iOwnFs; williamr@4: /// Own: Global Phonebook field types williamr@4: MVPbkFieldTypeList* iFieldTypes; williamr@4: /// Own: List of contact stores williamr@4: CVPbkContactStoreDomainList* iContactStoreDomains; williamr@4: /// Own: Contact attribute manager williamr@4: MVPbkContactAttributeManager* iAttributeManager; williamr@4: /// Own: an internal class for loading stores williamr@4: class CContactStoreLoader; williamr@4: CContactStoreLoader* iStoreLoader; williamr@4: }; williamr@4: williamr@4: #endif // CVPBKCONTACTMANAGER_H williamr@4: williamr@4: // End of file