/*

* 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>

// 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