/*

* Copyright (c) 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:  Definition of the session to the Menu

*

*/

#ifndef __MCSMENU_H__

#define __MCSMENU_H__

#include <e32base.h>

#include "mcsinternaltypes.h"

class TMenuItem;

class CMenuItem;

class CMenuOperation;

class CMenuFilter;

/**

 *  Menu session.

 *  The menu is an ID-based tree structure of menu folders and items.

 *  @lib mcsmenu.lib

 *  @since S60 v5.0

 */

NONSHARABLE_CLASS( RMenu ): public RSessionBase

    {

    /** 

    * RMenu acts on behalf on CMenuItem (CMenuItem is not a subsession object).

    * Data returned by the methods below usually exists in the transfer

    * buffer -> use it immediately or copy, because the buffer will be

    * overwritten very soon!

    */

    friend class CMenuItem;

public:

    /**

    * Constructor.

    * @since S60 v5.0

    * @capability None.

    * @throws None.

    * @panic None.

    */

    RMenu() { iData = NULL; }

    /**

    * Close the session. Safe to call if not open.

    * @since S60 v5.0

    * @capability None.

    * @throws None.

    * @panic None.

    */

    IMPORT_C void Close();

    /**

    * Open the session.

    * @since S60 v5.0

    * @param aName Name of the menu content to open.

    * @capability ECapabilityReadDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C void OpenL( const TDesC& aName );

    /**

    * Get ID of the root folder.

    * @since S60 v5.0

    * @return ID of the root folder.

    * @capability ECapabilityReadDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C TInt RootFolderL();

    /**

    * Get list of items.

    * @since S60 v5.0

    * @param aItemArray Array receiving item list. Existing content not touched

    * (new items are appended).

    * @param aFolder Get items from this folder.

    * @param aFilter Filter criteria or NULL for unfiltered results.

    * @param aRecursive ETrue to recurse folders, EFalse for immediate

    * children only.

    * @capability ECapabilityReadDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C void GetItemsL(

        RArray<TMenuItem>& aItemArray,

        TInt aFolder,

        const CMenuFilter* aFilter = NULL,

        TBool aRecursive = EFalse );

    /**

     * Get array of running applications

     */

    IMPORT_C void GetRunningAppsL( RArray<TUid>& aArray );    

    /**

    * Remove item.

    * @since S60 v5.0

    * @param aId ID of item to be removed.

    * @param aStatus Observer request status. When the operation completes,

    * this status will be completed with the resulting error code.

    * @return Asynchronous operation. Owned by the caller.

    * @capability ECapabilityWriteDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C CMenuOperation* RemoveL( TInt aId, TRequestStatus& aStatus );

    /**

    * Move items to another folder.

    * @since S60 v5.0

    * @param aItems ID-s of items to be to be moved. All items must be in

    * the same folder.

    * @param aFolder Target folder.

    * @param aMoveBefore. In the target folder, items will be inserted before

    * this item (if found). If the target folder contains no item with that ID,

    * the moved items are appended to the end of existing items. Pass 0 to

    * append to the end.

    * @param aStatus Observer request status. When the operation completes,

    * this status will be completed with the resulting error code.

    * @return Asynchronous operation. Owned by the caller.

    * @capability ECapabilityWriteDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C CMenuOperation* MoveToFolderL(

        const RArray<TInt>& aItems,

        TInt aFolder,

        TInt aMoveBefore,

        TRequestStatus& aStatus );

    /**

    * Move item to a different position in its current folder.

    * @since S60 v5.0

    * @param aId ID-s of item to be to be reordered.

    * @param aMoveBefore. Move the item before this item (if found).

    * If aMoveBefore is not found, the aItem is moved to the end.

    * @param aStatus Observer request status. When the operation completes,

    * this status will be completed with the resulting error code.

    * @return Asynchronous operation. Owned by the caller.

    * @capability ECapabilityWriteDeviceData.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C CMenuOperation* ReorderL(

        TInt aId,

        TInt aMoveBefore,

        TRequestStatus& aStatus );

    /**

    * Start checking the number of allocated object through this session.

    * @since S60 v5.0

    * @capability ECapabilityAllFiles.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C void ResourceMark();

    /**

    * Check that the number of allocated object through this session

    * matches the same of when the last call to ResourceMark was made.

    * @since S60 v5.0

    * @capability ECapabilityAllFiles.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C void ResourceCheck();

    /**

    * Get number of allocated object through this session.

    * @since S60 v5.0

    * @return Number of allocated object through this session.

    * @capability ECapabilityAllFiles.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C TInt ResourceCount();

    /**

    * Simulate a heap allocation failure for server heap. Has empty

    * implementation for the UDEB server.

    * @since S60 v5.0

    * @param aType Type of heap failure simulation.

    * @param aRate Rate of failure.

    * @capability ECapabilityAllFiles.

    * @throws System-wide error codes if an error occurs.

    * @panic None.

    */

    IMPORT_C void __DbgSetAllocFail

        ( RAllocator::TAllocFail aType, TInt aRate );

private:

    /**

    * Connect session.

    * @return Error code.

    */

    TInt ConnectSession();

    /**

    * Get item attribute value.

    * @param aId Item ID.

    * @param aAttrName. Attribute name.

    * @return Attribute value, or NULL if attribute is not defined.

    * Owner is the caller.

    */

    HBufC* GetAttributeL( TInt aId, const TDesC& aAttrName );

    /**

    * Get item attribute name list.

    * @param aId Item ID.

    * @param aList Attribute item list.

    */

    void GetAttributeListL( TInt aId, RArray<TAttributeName>& aList );

    /**

    * Get item header.

    * @param aId Item ID.

    * @return Item header. The header is in the transfer buffer, copy it.

    */

    const TMenuItem& GetHdrL( TInt aId );

    /**

    * Handle command.

    * @param aItem Item.

    * @param aCommand Command.

    * @param aParams. Command parameters.

    * @param aStatus Observer request status. When the operation completes,

    * this status will be completed with the resulting error code.

    * @return Asynchronous operation. Owned by the caller.

    */

    CMenuOperation* HandleCommandL(

        CMenuItem& aItem,

        const TDesC8& aCommand,

        const TDesC8& aParams,

        TRequestStatus& aStatus );

private:    // data

    class TData;

    TData* iData; ///< Private data. Own.

    };

#endif // __MCSMENU_H__