1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Definition of the session to the Menu

    15 *

    16 */

    17 

    18 

    19 #ifndef __MCSMENU_H__

    20 #define __MCSMENU_H__

    21 

    22 #include <e32base.h>

    23 #include "mcsinternaltypes.h"

    24 class TMenuItem;

    25 class CMenuItem;

    26 class CMenuOperation;

    27 class CMenuFilter;

    28 

    29 /**

    30  *  Menu session.

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

    32  *  @lib mcsmenu.lib

    33  *  @since S60 v5.0

    34  */

    35 NONSHARABLE_CLASS( RMenu ): public RSessionBase

    36     {

    37 

    38     /** 

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

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

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

    42     * overwritten very soon!

    43     */

    44     friend class CMenuItem;

    45 

    46 public:

    47 

    48     /**

    49     * Constructor.

    50     * @since S60 v5.0

    51     * @capability None.

    52     * @throws None.

    53     * @panic None.

    54     */

    55     RMenu() { iData = NULL; }

    56 

    57     /**

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

    59     * @since S60 v5.0

    60     * @capability None.

    61     * @throws None.

    62     * @panic None.

    63     */

    64     IMPORT_C void Close();

    65 

    66     /**

    67     * Open the session.

    68     * @since S60 v5.0

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

    70     * @capability ECapabilityReadDeviceData.

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

    72     * @panic None.

    73     */

    74     IMPORT_C void OpenL( const TDesC& aName );

    75 

    76     /**

    77     * Get ID of the root folder.

    78     * @since S60 v5.0

    79     * @return ID of the root folder.

    80     * @capability ECapabilityReadDeviceData.

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

    82     * @panic None.

    83     */

    84     IMPORT_C TInt RootFolderL();

    85 

    86     /**

    87     * Get list of items.

    88     * @since S60 v5.0

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

    90     * (new items are appended).

    91     * @param aFolder Get items from this folder.

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

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

    94     * children only.

    95     * @capability ECapabilityReadDeviceData.

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

    97     * @panic None.

    98     */

    99     IMPORT_C void GetItemsL(

   100         RArray<TMenuItem>& aItemArray,

   101         TInt aFolder,

   102         const CMenuFilter* aFilter = NULL,

   103         TBool aRecursive = EFalse );

   104 

   105     /**

   106      * Get array of running applications

   107      */

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

   109     

   110     /**

   111     * Remove item.

   112     * @since S60 v5.0

   113     * @param aId ID of item to be removed.

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

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

   116     * @return Asynchronous operation. Owned by the caller.

   117     * @capability ECapabilityWriteDeviceData.

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

   119     * @panic None.

   120     */

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

   122 

   123     /**

   124     * Move items to another folder.

   125     * @since S60 v5.0

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

   127     * the same folder.

   128     * @param aFolder Target folder.

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

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

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

   132     * append to the end.

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

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

   135     * @return Asynchronous operation. Owned by the caller.

   136     * @capability ECapabilityWriteDeviceData.

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

   138     * @panic None.

   139     */

   140     IMPORT_C CMenuOperation* MoveToFolderL(

   141         const RArray<TInt>& aItems,

   142         TInt aFolder,

   143         TInt aMoveBefore,

   144         TRequestStatus& aStatus );

   145 

   146     /**

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

   148     * @since S60 v5.0

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

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

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

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

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

   154     * @return Asynchronous operation. Owned by the caller.

   155     * @capability ECapabilityWriteDeviceData.

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

   157     * @panic None.

   158     */

   159     IMPORT_C CMenuOperation* ReorderL(

   160         TInt aId,

   161         TInt aMoveBefore,

   162         TRequestStatus& aStatus );

   163 

   164     /**

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

   166     * @since S60 v5.0

   167     * @capability ECapabilityAllFiles.

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

   169     * @panic None.

   170     */

   171     IMPORT_C void ResourceMark();

   172 

   173     /**

   174     * Check that the number of allocated object through this session

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

   176     * @since S60 v5.0

   177     * @capability ECapabilityAllFiles.

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

   179     * @panic None.

   180     */

   181     IMPORT_C void ResourceCheck();

   182 

   183     /**

   184     * Get number of allocated object through this session.

   185     * @since S60 v5.0

   186     * @return Number of allocated object through this session.

   187     * @capability ECapabilityAllFiles.

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

   189     * @panic None.

   190     */

   191     IMPORT_C TInt ResourceCount();

   192 

   193     /**

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

   195     * implementation for the UDEB server.

   196     * @since S60 v5.0

   197     * @param aType Type of heap failure simulation.

   198     * @param aRate Rate of failure.

   199     * @capability ECapabilityAllFiles.

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

   201     * @panic None.

   202     */

   203     IMPORT_C void __DbgSetAllocFail

   204         ( RAllocator::TAllocFail aType, TInt aRate );

   205 

   206 private:

   207 

   208     /**

   209     * Connect session.

   210     * @return Error code.

   211     */

   212     TInt ConnectSession();

   213 

   214     /**

   215     * Get item attribute value.

   216     * @param aId Item ID.

   217     * @param aAttrName. Attribute name.

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

   219     * Owner is the caller.

   220     */

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

   222 

   223     

   224     /**

   225     * Get item attribute name list.

   226     * @param aId Item ID.

   227     * @param aList Attribute item list.

   228     */

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

   230 

   231     /**

   232     * Get item header.

   233     * @param aId Item ID.

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

   235     */

   236     const TMenuItem& GetHdrL( TInt aId );

   237 

   238     /**

   239     * Handle command.

   240     * @param aItem Item.

   241     * @param aCommand Command.

   242     * @param aParams. Command parameters.

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

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

   245     * @return Asynchronous operation. Owned by the caller.

   246     */

   247     CMenuOperation* HandleCommandL(

   248         CMenuItem& aItem,

   249         const TDesC8& aCommand,

   250         const TDesC8& aParams,

   251         TRequestStatus& aStatus );

   252 

   253 private:    // data

   254     

   255     class TData;

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

   257 

   258     };

   259 

   260 #endif // __MCSMENU_H__