/*

* Copyright (c) 2006 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:  Implementation of interface for Collection Utility

*

*/

#ifndef CMPXCOLLECTIONUTILITY_H

#define CMPXCOLLECTIONUTILITY_H

#include <mpxcollectionobserver.h>

#include <mpxcollectionmessage.h>

#include <mpxsession.h>

#include <mpxmessageobserver.h>

#include "mpxcollectionserverdefs.h"

#include "mpxcollectionutility.h"

class CMPXMessageMonitor;

class CMPXTaskQueue;

class CMPXMsgBuf;

class CMPXMedia;

/**

*  Implementation of collection utility interface

*/

NONSHARABLE_CLASS(CMPXCollectionUtility) : public CActive,

                                           public MMPXCollectionUtility,

                                           public MMPXMessageObserver,

                                           public MMPXCollection

    {

public:

    /**

    * Two-phased constructor

    *

    * @param aObs observer

    * @param aModeId collection mode id

    * @return object of constructed

    */

    static CMPXCollectionUtility* NewL(const TUid& aModeId,

                                       MMPXCollectionObserver* aObs);

    /**

    * Destructor

    */

    ~CMPXCollectionUtility();

private:

    /**

    * C++ constructor

    */

    CMPXCollectionUtility(MMPXCollectionObserver* aObs);

    /**

    * Second phase constructor

    *

    * @param aModeId collection mode id

    */

    void ConstructL(const TUid& aModeId);

public:

    /**

    *  From MMPXCollectionUtility

    *  The collection.

    *

    *  @return the collection

    */

    MMPXCollection& Collection();

    /**

    * From MMPXCollectionUtility

    * Retrieves the ID of the collection plugin which matched aUids best.

    * If multiple plugins match the aUids, the only one with high priority will

    * be returned

    *

    * @param aUids, selection criteria

    * @return TUid containing the implementation UID of the collection that

    * would be selected

    */

    TUid CollectionIDL(const TArray<TUid>& aUids);

    /**

    *  From MMPXCollectionUtility

    *  Frees up client side resources only; a collection is freed when there are no

    *  clients using it, and all resources are freed when the last client closes

    */

    void Close();

    /**

    *  From MMPXCollection

    *  Opens the collection in its current state

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer, i.e.contains other media objects

    *

    *  @param aMode, open mode

    */

    void OpenL(TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection at a specific index

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer, i.e.contains other media objects

    *

    *  @param aIndex, the index into the currently opened item list

    *  @param aMode, type of open mode

    */

    void OpenL(TInt aIndex,TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection at a specific level

    *

    *  @param aPath, the path of the collection

    *  @param aMode, open mode

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL()

    */

    void OpenL(const CMPXCollectionPath& aPath,

                TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection at a specific index

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer, i.e.contains other media objects which will

    *  contain the attribute values specified by aAttrs

    *

    *  @param aIndex, the index into the currently opened item list

    *  @param aAttrs, attributes requested.

    *  @param aMode, type of open mode

    */

    void OpenL(TInt aIndex,const TArray<TMPXAttribute>& aAttrs,

                TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection at a specific level

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer, i.e.contains other media objects which will

    *  contain the attribute values specified by aAttrs

    *

    *  @param aPath, the path of the collection

    *  @param aAttrs, attributes requested.

    *  @param aMode, type of open mode required

    */

    void OpenL(const CMPXCollectionPath& aPath,

    		   const TArray<TMPXAttribute>& aAttrs,

               TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection with a list of implementation uids to be matched.

    *  if current context matches the criteria, it will return existing browsing

    *  media; otherwise it will be back to root level and only plug-ins which

    *  match all provided uids will be returned, in priority order.

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin

    *  priority if mulitple plugins support aUids.

    *

    *  @param aUids, array of UIDs used to select collection plugins based on

    *  supported uids in plugin resource file.

    *  @param aMode, open mode

    */

    void OpenL(const TArray<TUid>& aUids,

    		   TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Opens the collection with an uid to be matched.

    *  if current context matches the criteria, it will return existing browsing

    *  media; otherwise it will be back to root level and only plug-ins which

    *  match the uid will be returned, in priority order.

    *

    *  Calls back MMPXCollectionObserver::HandleOpenL() with CMPXMedia object

    *  with ID KMPXMediaIdContainer. Returned plugins will be sorted by plugin

    *  priority if mulitple plugins support the uid.

    *

    *  @param aUid, single UID used to select a collection

    *  @param aMode, open mode

    */

    void OpenL(const TUid& aUid,

    		   TMPXOpenMode aMode=EMPXOpenDefault);

    /**

    *  From MMPXCollection

    *  Apply a filter to collection browsing; all subsequent calls

    *  to OpenL() will have this filter applied.

    *

    *  @param aFilter, the filter to apply, or NULL to remove current

    *  filter

    */

    void SetFilterL(CMPXFilter* aFilter);

    /**

    *  From MMPXCollection

    *  Current filter that is applied to collection browsing, i.e. results

    *  returned through MMPXCollectionObserver::HandleOpenL() callback from

    *  OpenL()

    *

    *  @return filter applied to browsing, or NULL if no filter applied

    */

    CMPXFilter* FilterL();

    /**

    *  From MMPXCollection

    *  Returns current collection plugin implementation UID

    *

    *  @return UID of the collection

    */

    TUid UidL() const;

    /**

    *  From MMPXCollection

    *  The path of the collection in its current state

    *

    *  @return the path of the collection

    */

    CMPXCollectionPath* PathL();

    /**

    *  From MMPXCollection

    *  Navigates back to the container of the current items

    *  Calls back MMPXCollectionObserver::HandleOpenL()

    */

    void BackL();

    /**

    *  From MMPXCollection

    *  Is this path on a 'remote' collection

    *

    *  @aParam aPath, the collection path

    *  @return ETrue if is remote collection, otherwise EFalse

    */

    TBool IsRemote(const CMPXCollectionPath& aPath);

    /**

    *  From MMPXCollection

    *  Stops any async operations that are currently under way

    */

    void CancelRequest();

    /**

    *  From MMPXCollection

    *  Adds item(s) to the collection

    *

    *  @param aNewProperties, Properties of the item

    */

    void AddL(const CMPXMedia& aNewProperties);

    /**

    *  From MMPXCollection

    *  Remove an item (or items under a group) from the collection

    *

    *  @param aPath, item(s) to remove

    *  @param aObs, observer callback for items deleted (Optional)

    */

    void RemoveL(const CMPXCollectionPath& aPath,

                 MMPXCollectionRemoveObserver* aObs = NULL );

        /**

    *  From MMPXCollection

    *  Removes item(s) to the collection

    *

    *  @param aProperties, Properties of the item

    */

    void RemoveL(const CMPXMedia& aProperties);

    /**

    *  From MMPXCollection

    *

    *  Sets/updates the media for the item

    *  Callback via EMediaChanged message if currently opened

    *

    *  @param aMedia, updated item

    *

    */

    void SetSyncL(const CMPXMedia& aMedia);

    /**

    *  From MMPXCollection

    *

    *  Sets/updates the media for the item, Asynchronous

    *  Callback via HandleCollectionMessage, AsyncOp complete

    *

    *  @param aMedia, new value

    *

    */

    void SetL(const CMPXMedia& aMedia);

    /**

    * Find a list of media properties based on a search criteria

    * The types of supported "queries" are plugin dependent

    *

    * @param aMedia, criteria to search on

    * @param aAttrs, attributes to return

    * @param aObs, observer for find callback

    * Callback via MMPXCollectionFindObserver::HandleFindL();

    */

    void FindAllL(const CMPXMedia& aMedia,

                  const TArray<TMPXAttribute>& aAttrs,

                  MMPXCollectionFindObserver& aObs);

    /**

    * Find a list of media properties based on a search criteria

    * The types of supported "queries" are plugin dependent

    * This is a SYNCHRONOUS METHOD, use only if necessary.

    * @param aMedia, criteria to search on

    * @param aAttrs, attributes to return

    */

    CMPXMedia* FindAllL(const CMPXMedia& aMedia,

                        const TArray<TMPXAttribute>& aAttrs);

    /**

    *  From MMPXCollection

    *  Retrieve media for the item specified in the path

    *  Note: if selection is set in aPath, HandleMedia will return an array of

    *        media of current selected items.

    *        if no selection is set in aPath, HandleMedia will return media

    *        properities of current item.

    *

    *  @param aPath, the path of the collection

    *  @param aAttrs, attributes requested.

    *  @aParam aSpecs, specifications for attributes

    *  @param aFilter, filter to apply

    *

    *  Calls back MMPXCollectionObserver::HandleMediaL()

    */

    void MediaL(const CMPXCollectionPath& aPath,

                const TArray<TMPXAttribute>& aAttrs,

                CMPXAttributeSpecs* aSpecs=NULL,

                CMPXFilter* aFilter=NULL);

    /**

    * From MMPXCollection

    * Broadcasts an event to all observers

    * @param aMsg event to broadcast

    * @param aData data to accompany the event

    */

    void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData );

    /**

    * From MMPXCollection

    * Send a Command to the collection server

    * aCmd, command to handle

    * aData, some data about event (event specific, optional)

    */

    void CommandL(TMPXCollectionCommand aCmd, TInt aData = 0);

    /**

    * From MMPXCollection

    *  Send a command to the collection server

    *

    *  @param aCmd, command to handle

    */

    void CommandL(CMPXCommand& aCmd);

    /**

    * From MMPXCollection

    * Retrieves the set of supported file types

    * @param aArray Array to fill with the data

    */

    void GetSupportedTypesL( RPointerArray<CMPXCollectionType>& aArray );

    /**

    * From MMPXCollection

    * Retrieves the capabilities for the current collection context

    * @arg aCapability, bitmask of the capabilities supported.

    */

    void GetSupportedCapabilitiesL(TCollectionCapability& aCapability);

    /**

    * From MMPXCollection

    * Retrieves the real collection UID based on a predefined UID

    * @param aCollection, UID for lookup, defined in "mpxcollectionframeworkdefs.h"

    * @return TUid containing the real implementation UID

    */

    TUid CollectionIDL(TUid& aCollection);

    /**

    * From MMPXCollection

    * Adds a message subscription for this client.

    * @param aSubscription subscription to be added

    */

    void AddSubscriptionL(const CMPXSubscription& aSubscription);

    /**

    * From MMPXCollection

    * Removes a message subscription for this client.

    * @param aSubscription subscription to be removed.

    */

    void RemoveSubscriptionL(const CMPXSubscription& aSubscription);

    /**

    * From MMPXCollection

    * Removes all message subscriptions for this client.

    */

    void ClearSubscriptionsL();

    /**

    * From MMPXMessageObserver

    * Message received

    * @param aMsgData message data

    * @param aError error code

    */

    void MessageReceived(TInt aMsgData, TInt aError);

    /**

    * From CActive

    * Handles an active object's request completion event

    */

    void RunL();

    /**

    * From CActive

    * Implements cancellation of an outstanding request.

    */

   void DoCancel();

    /**

    * From CActive

    * Handles a leave occurring in the request completion event handler RunL()

    *

    * @param aError error code

    */

    TInt RunError(TInt aError);

private:

    /**

    *  Add a request to the task queue and run the next queue if no outstanding

    *  task

    *

    *  @param aFunction function code

    *  @param aObs, observer to callback asynchronously

    *  @param aParamData data

    *  @param aBuf, extra data in buffer, ownership transferred.

    *  @param aPtr, pointer to a object

    *  @param aAlivePtr1, object to keep alive for a task

                         ownership transferred

    *  @param aAlivePtr2, same as aAlivePtr1

    */

    void AddRequestL(TMPXCollectionServerOp aFunction,

                     TAny* aObs,

                     TInt aParamData=0,

                     CBufBase* aBuf=NULL,

                     TAny* aPtr=NULL,

                     CBase* aAlivePtr1=NULL,

                     CBase* aAlivePtr2=NULL);

    /**

    *  Send next request to server

    */

    void ExecuteNextRequest();

    /**

    *  Handle message from message queue

    *  @param aMsgData message data

    *  @param aError error code

    */

    void HandleMessageL(TInt aMsgData, TInt aError);

    /**

     * Handles error in RunL

     *

     * @param aError error code

     */

    void HandleRunErrorL(TInt aError);

#ifdef _ENABLE_GUARD_TIMER

    /**

     *  Gaurd timer callback

     *

     *  @param aPtr pointer the this

     */

    static TInt GuardTimerCallback(TAny* aPtr);

#endif

private:

    MMPXCollectionObserver* iObserver;

    CMPXMessageMonitor* iMsgMonitor;

    CMPXTaskQueue* iTaskQueue;

    RMPXSession iMcs;

    CMPXMedia* iCurrentEntries;

    CBufBase* iBuffer;

    CArrayFixBase* iArray;

    TPckgBuf<TInt> iSizePckg;

    TPckgBuf<TInt> iSelectionPckg;

    TPckgBuf<TInt> iCompletePckg;

    TPckgBuf<TInt> iPropertiesSizePckg;

    TInt iSelection;

    TBool iCallbackOngoing; // is client processing callback?

    // Keep alive pointers on global heap

    CMPXMedia* iMedia;

    CMPXMedia* iMediaOnError; // media object while handling error

#ifdef _ENABLE_GUARD_TIMER

    CPeriodic* iGuardTimer; //guard timer for async request

#endif

    };

#endif // CMPXCOLLECTIONUTILITY_H