/*

* 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:  Maintains sessions to paths

*

*/

#ifndef CMPXCOLLECTIONCLIENTCONTEXT_H

#define CMPXCOLLECTIONCLIENTCONTEXT_H

#include <mpxcollectionpluginobserver.h>

#include <mpxtaskqueueobserver.h>

#include <mpxcmn.h>

#include <mpxcommand.h>

#include <mpxfilter.h>

#include <mpxattributespecs.h>

#include <mpxmessagequeue.h>

#include "mpxcollectioncache.h"

class CMPXClientList;

class CMPXCollectionPath;

class CMPXCollectionEngine;

class CMPXCollectionPlugin;

class MMPXCollectionEngineObserver;

class CMPXActiveTaskQueue;

class CMPXMedia;

class CMPXCollectionCache;

class CMPXCollectionClientContext : public CBase,

                                    public MMPXCollectionPluginObserver,

                                    public MMPXTaskQueueObserver

    {

public: // DATA type

    enum TContextType

        {

        EContextBrowse, // context for browing

        EContextMedia, // context for media properties

        EContextRemove, // context for removing paths

        EContextCount

        };

public:

    /**

    *  Two-phase constructor

    *

    *  @param aEngine reference to collection engine

    *  @param aModeId mode id

    *  @return object created

    */

    static CMPXCollectionClientContext* NewL(CMPXCollectionEngine& aEngine,

        CMPXCollectionCache& aCache, const TUid& aModeId);

    /**

    *  Destructor

    *

    */

    ~CMPXCollectionClientContext();

    /**

    *  Open collection by path

    *

    *  @param aPath collection path. Ownership transferred if not leave

    *  @param aMode, open mode

    *  @param aCallback callback

    *  @leave KErrArgument if aPath is not valid, or other system error

    */

    IMPORT_C void OpenL(CMPXCollectionPath* aPath,

                        TInt aMode,

                        MMPXCollectionEngineObserver* aCallback);

    /**

    *  Open collection by index

    *

    *  @param aIndex the index to current browse path

    *  @param aMode, open mode

    *  @param aAttrs, media attributes requested

    *  @param aCallback callback

    *  @leave system error

    */

    IMPORT_C void OpenL(TInt aIndex,

                        TInt aMode,

                        const TArray<TMPXAttribute>& aAttrs,

                        MMPXCollectionEngineObserver* aCallback);

    /**

    *  Open collection by uids. Collections which match the uids will be returned.

    *

    *  @param aUids a list of uids to be matched

    *  @param aMode, open mode

    *  @param aCallback callback

    *  @leave KErrNotReady if current browse path is invalid,

    *         KErrArgument if aIndex is out of range

    *         or other system error

    */

    IMPORT_C void OpenL(const TArray<TUid>& aUids,

                        TInt aMode,

                        MMPXCollectionEngineObserver* aCallback);

    /**

     *  Request current content of browse context

     *

     *  @param aMode, open mode

     *  @param aCallback callback

     *  @leave system error

     */

    IMPORT_C void OpenL(TInt aMode, MMPXCollectionEngineObserver* aCallback);

    /**

     *  Back to previous level

     *  @param aCallback callback

     *  @leave system error

     */

    IMPORT_C void BackL(MMPXCollectionEngineObserver* aCallback);

    /**

     *  Media request command

     *

     *  @param aCmd  command of media request

     *  @param aCallback callback

     *  @leave KErrArgument if aCmd is not valid, or other system error

     */

    IMPORT_C void MediaL(const CMPXCommand& aCmd,

                         MMPXCollectionEngineObserver* aCallback);

    /**

     *  Add a media

     *

     *  @param aMedia media object

     *  @leave system error

     */

    IMPORT_C void AddL(const CMPXMedia& aMedia);

    /**

     *  Remove a media

     *

     *  @param aMedia media object

     *  @leave system error

     */

    IMPORT_C void RemoveL(const CMPXMedia& aMedia);

    /**

     *  Update a media

     *

     *  @param aMedia media object

     *  @leave system error

     */

    IMPORT_C void SetL(const CMPXMedia& aMedia);

    /**

     *  Remove media by path

     *

     *  @param aPath collection path. Ownership transferred if not leave

     *  @param aCallback callback

     *  @leave KErrArgument if aPath is not valid, or other system error

     */

    IMPORT_C void RemoveL(CMPXCollectionPath* aPath,

                          MMPXCollectionEngineObserver* aCallback);

    /**

    *  Return plugin uid

    *

    *  @return plugin uid

    */

    IMPORT_C TUid PluginId() const;

    /**

    *  Return current collection path

    *

    *  @return collection path

    */

    IMPORT_C const CMPXCollectionPath& Path() const;

    /**

    *  Cancel all requests from aCallback

    *

    *  @param aCallback callback

    */

    IMPORT_C void CancelRequest(MMPXCollectionEngineObserver* aCallback);

    /**

    *  Attach another client to this object. aName is the unique name of the

    *  client, used for identifying the client and passing messages; aId is the

    *  thread id of the client of the interface (not the server session)

    *

    *  @param aId thread id of the client

    *  @param aMsgQueue message queue for the client

    *  @leave The function leaves with one of the system wide error codes,

    *         if the operation fails.

    */

    IMPORT_C void AddClientL(TThreadId aId,

                             CMPXMessageQueue* aMsgQueue);

    /**

    *  Remove the client from the context. aName is the unique name of the

    *  client, used for identifying the client and passing messages.

    *

    *  @param aMsgQueue message queue for the client

    */

    IMPORT_C void RemoveClient(const CMPXMessageQueue& aMsgQueue);

    /**

    * Get the supported attributes of the current plugin using by the context

    * @return TCollectionCapability bit mask flag

    */

    IMPORT_C TCollectionCapability GetCapabilities();

    /**

     *  Find all

     *

     *  @param aMedia media object of matching criteria, Ownership transferred

     *  @param aBuf, buffer data, array of attributes for results,

     *               Ownership transferred if find asynchronously

     *  @param aCallback callback

     *  @leave system error

     */

    IMPORT_C void FindAllL(const CMPXMedia& aMedia,

                           CBufBase* aBuf,

                           MMPXCollectionEngineObserver* aCallback);

   /** DEPRECATE, Use CommandL(CMPXCommand)

    *  Find all synchronously

    *

    *  @param aMedia media object of matching criteria

    *  @param aBuf, buffer data, array of attributes for results

    *  @leave system error

    *  @return results of the search

    */

    IMPORT_C CMPXMedia* FindAllSyncL(const CMPXMedia& aMedia,

                                     const CBufBase& aBuf);

    /**

     * Set the current filter applied to browsing

     */

    IMPORT_C void SetFilterL(const CMPXFilter* aFilter);

    /**

    * Get the current filter applied to browsing

    * @return filter

    */

    IMPORT_C const CMPXFilter* Filter() const;

    /** DEPRECATED

     * Handle a collection command

     * @param aCmd, command to handle

     * @param aData, optional data

     */

    IMPORT_C void CommandL(TMPXCollectionCommand aCmd, TInt aData);

    /**

     * Handle a collection command

     * @param aCmd, command to handle

     * @param aCallback callback

     * @param aMsgQueue Message Queue for the client

     * @leave KErrNotReady if not collection opened, or system error

     */

    IMPORT_C void CommandL(const CMPXCommand& aCmd,

                           MMPXCollectionEngineObserver* aCallback,

                           const CMPXMessageQueue& aMsgQueue);

    /**

    *  Does this thread have a shareable client?  If yes, a default mode

    *  connection can bind to it.

    *

    *  @param aId thread id of the client

    *  @return ETrue, if shareableclient is in the client list

    */

    TBool HasShareableClient(TThreadId aId);

    /**

    *  Notify the client of a collection event

    *  @param aMsg Message type

    *  @param aData some data

    */

    void NotifyL( TMPXCollectionBroadCastMsg aMsg, TInt aData );

    /**

    * Get the mode id of the context

    * @return collection mode id

    */

    const TUid& ModeId() const;

    /**

    * Handle message from plug-in

    *

    * @param aMsg, message from the plug-in

    * @param aError, error code

    * @param aNotifyOthers, indicates whether to notify other client contexts

    *        that the collection has changed

    */

    void DoHandleMessage(CMPXMessage* aMsg,

                         TInt aError,

                         TBool aNotifyOthers);

private: // From base classes

    ///////////////////////////////////////////////////////////////////////////

    // From MMPXCollectionPluginObserver

    /**

    * Handle message from plug-in

    *

    * @param aMessage, message from the plug-in, Ownership not transferred.

    * @param aError error code

    */

    void HandleMessage(CMPXMessage* aMsg, TInt aError);

    /**

    * Handle opening group contents

    *

    * @param aMedia media, Ownership not transferred.

    * @param aErr error code

    */

    void HandleOpen(CMPXMedia* aMedia, TInt aErr);

    /**

     * Handle opening a group, e.g. an artist

     *

     * @param aMedia media object returned. NULL will be returned if error.

     *        Ownership not transferred.

     * @param aPath full path to to current level. Including top level node as well.

     *         NULL will be returned if error. Ownership not transferred

     * @param aErr error code

     */

    void HandleOpen(CMPXMedia* aMedia,

                    const CMPXCollectionPath* aPath,

                    TInt aErr);

    /**

    * Handle opening an item

    *

    * @param aPath selected item, Ownership not transferred.

    * @param aErr error code

    */

    void HandleOpen(CMPXCollectionPath* aPath, TInt aErr);

    /**

    *  Handle media

    *

    *  @param aMedia media Ownership not transferred.

    *  @param aError error code

    */

    void HandleMedia(CMPXMedia* aMedia, TInt aError);

    /**

     *  Handle completion of a asynchronous command

     *

     *  @param aCommandResult result of the command, NULL if error

     * Ownership not transferred.

     *  @param aError error code

     */

     void HandleCommandComplete(CMPXCommand* aCommandResult,

                                TInt aError);

    /**

    * Handle Find results

    * @param aMedia media item(s), Ownership not transferred.

    * @param aError, error code

    */

    void HandleFindAll(CMPXMedia* aMedia, TInt aError);

     /**

    * Handles remove results

    * @param aUriArray, NULL if the plugin does not use concept of URI

    *                   else, contains the file path to delete a file

    * @param aError, error code

    */

    void HandleRemove(const CDesCArray& aUriArray, TInt aError);

    ///////////////////////////////////////////////////////////////////////////

    // From MMPXTaskQueueObserver

    /**

    * Execute a task

    * @param aTask task number

    * @param aParamData, parameter

    * @param aPtrData, any object

    * @param aBuf, buffer containing externalized parameters for the task.

    * @param aCallback call back function pointer

    * @param aCObject1 object 1 owned by task queue

    * @param aCObject2 object 2 owned by task queue

    */

    void ExecuteTask(TInt aTask,

                     TInt aParamData,

                     TAny* aPtrData,

                     const CBufBase& aBuf,

                     TAny* aCallback,

                     CBase* aCObject1,

                     CBase* aCObject2);

    /**

    * @see MMPXTaskQueueObserver

    */

    void HandleTaskError(TInt aTask,

                         TAny* aPtrData,

                         TAny* aCallback,

                         TInt aError);

private:

    /**

    *  Open current level of collection

    *

    */

    void OpenL();

    /**

    *  Back to upper level

    *

    */

    void BackL();

    /**

    *  Reopen current level

    *

    */

    void ReOpenL();

    /**

    * Find Media Request

    * @param aMedia, searching criteria

    * @param aBuf, buffered data

    * @param aPlugin, plug to handle the find all

    * @param aResult, sync finding result

    * @param aSync, flag to indicate sync or async find

    */

    void FindAllL(const CMPXMedia& aMedia,

                  const CBufBase& aBuf,

                  CMPXCollectionPlugin& aPlugin,

                  CMPXMedia** aResult = NULL,

                  TBool aSync = EFalse);

    /**

    * Initialize

    * @param aCallback callback when initialization completes

    */

    void InitL(MMPXCollectionEngineObserver* aCallback);

    /**

    * Execute a task

    * @param aTask task number

    * @param aParamData, parameter

    * @param aPtrData, any object

    * @param aCallback call back function pointer

    * @param aBuf buffer data

    * @param aCObject1 object 1 owned by task queue

    * @param aCObject2 object 2 owned by task queue

    * @param aPlugin out parameter, plugin of the task.

    */

    void ExecuteTaskL(TInt aTask,

                      TInt aParamData,

                      TAny* aPtrData,

                      TAny* aCallback,

                      const CBufBase& aBuf,

                      CBase* aCObject1,

                      CBase* aCObject2,

                      CMPXCollectionPlugin*& aPlugin);

    /**

    * Handle error of execution

    * @param aPlugin plugin object

    * @param aErr error number

    * @param aUnuserPlugin ETrue decrement reference count of plugin

    */

    void HandleError(CMPXCollectionPlugin& aPlugin,

                     TInt aErr,

                     TBool aUnusePlugin=EFalse);

    /**

    * Resolve plugin

    * @param aPath, Collection path

    * @param aUid implementation uid of the plugin associated with the path

    */

    void ResolvePluginL(const CMPXCollectionPath& aPath, TUid& aUid);

    /**

    * Resolve plugin for FindAllL

    *

    * @param aMedia media object contains matching criteria

    * @param aPlugin, plugin reutrned

    */

    void ResolvePluginL(const CMPXMedia& aMedia,

                        CMPXCollectionPlugin*& aPlugin);

    /**

    * Add a media into the collection

    * Unpacks a media item group

    * @param aOp, operation code

    * @param aMedia, media object representing a list or a file

    */

    void DoUpdateMediaL(TInt aOp, const CMPXMedia& aMedia);

    /**

    * Add/Remove/Set an "item" into the collection

    * @param aOp, operation code

    * @param aMedia, single media "item"

    */

    void DoHandleItemL(TInt aOp, const CMPXMedia& aMedia);

    /**

    * Handle a synchronous collection command

    * @param aCmd, command to handle

    * @param aPlugin, plugin to prococess the command

    */

    void DoHandleSyncCommandL(const CMPXCommand& aCmd,

                              const CMPXMessageQueue& aMsgQueue,

                              CMPXCollectionPlugin* aPlugin=NULL);

    /**

    * Handle a select collection command

    * @param aCmd, command to handle

    */

    void DoHandleSelectCommandL(const CMPXCommand& aCmd);

    /**

    * Handle opening group contents

    *

    * @param aMedia media

    * @param aPath full path to current level

    * @param aCallback callback of the open request