/*

 * Copyright (c) 2006-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:  An interface for text based contact view filtering.

 *

 */

 #ifndef M_MVPBKCONTACTVIEWFILTERING_H

 #define M_MVPBKCONTACTVIEWFILTERING_H

 #include <e32def.h>

 #include <bamdesca.h>

 // FORWARDS DECLARATIONS

 class MVPbkContactViewBase;

 class MVPbkContactViewObserver;

 class MVPbkContactBookmarkCollection;

 /**

  * An interface for text based contact view filtering.

  *

  * Contact views can support filtering based on search string and

  * always included contacts by implementing this interface.

  *

  * A view stack usage:

  *

  * The client can create a stack structure of filtered views. E.g

  *

  * 1) Client creates a filtered view using find text "J"

  * 2) It then waits that the new view becomes ready.

  * 3) Then it uses the new view to create next level view for "Jo".

  * 4) The client waits that the new view becomes ready.

  * 5) The client again uses the new view for creating third level view "Joe"

  * 6) After the third filtered view becomes ready the client has 4 views:

  *    The base view that includes all the contacts and 3 filtered views

  *    for texts "J", "Jo" and "Joe". It's up to store implementation

  *    to optimize the used resources in case the store supports thousands

  *    of contacts.

  *

  * If client uses always included contacts then they must be same for all

  * views in a stack.

  *

  * View events must come in order: bottom view first.

  */

 class MVPbkContactViewFiltering

     {

 public:

     /**

      * Creates a new filtered view asynchronously.

      * 

      * The parent view will be filtered according to given criteria and

      * then the client will be notified via MVPbkContactViewObserver.

      * The parent view must be ready before creating a new filtered view,

      * The created view must be destroyed before the parent view and

      * not vice versa.

      *

      * @param aObserver The observer that will be notified when the view

      *                  is ready. Client shouldn't use the view before

      *                  it has been notified.

      * @param aFindWords An array of words that must match to the contact.

      * @param aAlwaysIncluded Contacts that must be in the view

      *                        even they don't match to aFindWords.

      *                        This an optional parameter. Give

      *                        NULL if not needed. Client must keep

      *                        the instance alive while the view exists.

      * @return a filtered view that must also support view filtering.

      */

     virtual MVPbkContactViewBase* CreateFilteredViewLC( 

             MVPbkContactViewObserver& aObserver,

             const MDesCArray& aFindWords,

             const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;

     /**

      * Updates an existing filtered view asynchronously. 

      * 

      * This must be implemented by the views that were previously

      * created by CreateFilteredViewLC. Otherwise leaves with KErrNotSupported.

      *

      * @param aFindWords an array of words that must match to the contact.

      * @param aAlwaysIncluded Contacts that must be in the view

      *                        even they don't match to aFindWords.

      *                        This an optional parameter. Give

      *                        NULL if not needed. Client must keep

      *                        the instance alive while the view exists.

      * @exception KErrNotSupported if the view itself is not a filtered view.

      */

     virtual void UpdateFilterL( 

             const MDesCArray& aFindWords,

             const MVPbkContactBookmarkCollection* aAlwaysIncluded ) = 0;

     /**

      * Returns an extension point for this interface or NULL.

      *

      * @param aExtensionUid no extensions defined currently.

      * @return an extension point for this interface or NULL.

      */

     virtual TAny* ContactViewFilteringExtension(TUid /*aExtensionUid*/) 

         { return NULL; }

 protected:

     /**

      * Virtual Phonebook client doesn't own this instance.

      */

 	~MVPbkContactViewFiltering() {}

     };

 #endif // M_MVPBKCONTACTVIEWFILTERING_H