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