/*

* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef MCLFCONTENTLISTINGENGINE_H

#define MCLFCONTENTLISTINGENGINE_H

//  INCLUDES

#include <CLFContentListing.h>

#include <e32std.h>

// FORWARD DECLARATIONS

class MCLFContentListingEngineExt;

class MCLFChangedItemObserver;

class MCLFItemListModel;

class MCLFOperationObserver;

class TResourceReader;

class MCLFProcessObserver;

// CLASS DECLARATION

/**

*  Content Listing Engine.

*  With Content Listing Engine, client can create item list models,

*  add an observer to get notifications of changed items and

*  send update notifications to server.

*  Client can create an instance this class with ContentListingFactory.<br><br>

*  Usage:

*

*  @code

*

*  // Create a new instance with Content Listing Factory

*  MCLFContentListingEngine* engine =

*                    ContentListingFactory::NewContentListingEngineLC();

*

*  // Add changed item observer

*  engine->AddChangedItemObserverL( *myObserver );

*

*  // Send update notification when item is changed.

*  engine->UpdateItemsL();

*

*  // Remember to remove the observer, when it is deleted

*  engine->RemoveChangedItemObserver( *myObserver );

*

*  @endcode

*

*  @lib ContentListingFramework.lib

*  @since S60 3.1

*/

class MCLFContentListingEngine

    {

    public: // Constructors and destructor

        /**

        * Destructor.

        */

        virtual ~MCLFContentListingEngine() {}

    public: // New functions

        /**

        * Create a new instance of the Item List Model.

        * @since S60 3.1

        * @param aObserver Reference to an Operation Observer

        * @return New instance of the Item List Model.

        *         Ownership is transfered to the client application.

        */

        virtual MCLFItemListModel* CreateListModelLC(

                        MCLFOperationObserver& aObserver ) = 0;

        /**

        * Create a new instance of Item List Model from the application

        * resource.

        * @since S60 3.1

        * @param aObserver Reference to an Operation Observer.

        * @param aResource Resource reader to list model resource.

        *                  Use resource struct CLF_LIST_MODEL. See

        *                  CLFContentListing.rh

        * @return New instance of Item List Model.

        *         Ownership is transfered to the client application.

        */

        virtual MCLFItemListModel* CreateListModelLC(

                        MCLFOperationObserver& aObserver,

                        TResourceReader& aResource ) = 0;

        /**

        * Add a changed item observer to the Engine.

        * Changed item observer will notify you when items are changed, added

        * or removed. Remember to remove the observer before you delete

        * observer object.

        * @since S60 3.1

        * @param aObserver Changed item observer to be added

        */

        virtual void AddChangedItemObserverL(

                        MCLFChangedItemObserver& aObserver ) = 0;

        /**

        * Remove a changed item observer from the Engine.

        * @since S60 3.1

        * @param aObserver Changed item observer to be removed

        */

        virtual void RemoveChangedItemObserver(

                        MCLFChangedItemObserver& aObserver ) = 0;

        /**

        * Add CLF process observer.

        * Remember to remove the observer before delete the observer object.

        * @since S60 3.1

        * @param aObserver Process observer to be added

        */

        virtual void AddCLFProcessObserverL(

                        MCLFProcessObserver& aObserver ) = 0;

        /**

        * Remove CLF process observer.

        * @since S60 3.1

        * @param aObserver Process observer to be removed

        */

        virtual void RemoveCLFProcessObserver(

                        MCLFProcessObserver& aObserver ) = 0;

        /**

        * Send item update notification.

        * Client must use this method when media item(s) is changed or deleted.

        * This method call will request the CLF server to update its list

        * of items. Unneccesary update notifications should be avoided because

        * they generate load to the system!

        * @since S60 3.1

        */

        virtual void UpdateItemsL() = 0;

        /**

        * Send item update notification.

        * Client must use this method when media item(s) is changed or deleted.

        * This method call will request the CLF server to update items that are

        * defined in the TArray.

        * @since S60 3.1

        * @param aItemIDArray List of Item IDs of modified items

        */

        virtual void UpdateItemsL(

                        const TArray<TCLFItemId>& aItemIDArray ) = 0;

        /**

        * Send item update notification.

        * Client must use this method when media item(s) is changed or deleted.

        * @param aSemanticId Sematic ID is transfered to server plugins

        * @param aOpaqueData Opaque data is transfered to server plugins

        * @since S60 3.1

        */

        virtual void UpdateItemsL(

                        TInt aSemanticId,

                        const TDesC8& aOpaqueData ) = 0;

    private: // Extension interface

        /**

        * This member is internal and not intended for use.

        */

        virtual MCLFContentListingEngineExt* Extension() { return NULL; }

    };

#endif      // MCLFCONTENTLISTINGENGINE_H

// End of File