/*

 * 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 <e32base.h>

 #include <f32file.h>

 #include <bamdesca.h>

 #include <BADESCA.H> 

 // 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<MVPbkStoreContact*>& 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