diff -r 000000000000 -r ba25891c3a9e appinstall_plat/appmngr2runtimeapi/inc/appmngr2infobase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/appinstall_plat/appmngr2runtimeapi/inc/appmngr2infobase.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,385 @@ +/* +* Copyright (c) 2008 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: Base class definitions for items displayed in AppMngr2 +* +*/ + + +#ifndef C_APPMNGR2INFOBASE_H +#define C_APPMNGR2INFOBASE_H + +#include // CBase +#include // CEikMenuPaneItem::SData + +class CAppMngr2Runtime; + +enum TAppMngr2Location + { + EAppMngr2LocationPhone, + EAppMngr2LocationMemoryCard, + EAppMngr2LocationMassStorage + }; + +/** + * CAppMngr2InfoBase is the base class for objects representing: + * - installed applications and + * - installation packages (aka installation files). + * + * Installed applications and installation packages are displayed in the + * Appliction Manager UI using the data that Runtime plug-ins provide with + * CAppMngr2InfoBase derived objects. Application Manager gets the data via + * GetInstalledAppsL() and GetInstallationFilesL() metods in CAppMngr2Runtime + * class. + * + * CAppMngr2InfoBase contains the common functionality for both installed + * applications and installation packages. Derived classes CAppMngr2AppInfo + * and CAppMngr2PackageInfo are placeholders for more specific functionality. + * + * CAppMngr2InfoBase, as well as CAppMngr2AppInfo and CAppMngr2PackageInfo, + * are abstracts classes. Runtime plug-ins must provide the actual implementation + * by using derived classes. + * + * @lib appmngr2pluginapi.lib + * @since S60 v5.1 + */ +class CAppMngr2InfoBase : public CBase + { +public: // constructor and destructor + void ConstructL(); + ~CAppMngr2InfoBase(); + +public: // new functions + /** + * Reference to the CAppMngr2Runtime object of this plugin. + * + * @return CAppMngr2Runtime& Runtime object + */ + IMPORT_C CAppMngr2Runtime& Runtime() const; + + /** + * Icon index of this item (installed application or installation package). + * + * Items are displayed in a list in the UI. Each item has an icon image, + * two labels (name and details) and an optional small indicator icon. + * IconIndex() method provides index for the icon image. + * + * Icon index can be either: + * - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method + * - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh + * + * If item has a specific icon that no other items use, return value + * EAppMngr2UseSpecificIcon and load the specific icon via SpecificIconL(). + * + * There are no default icons, each plug-in must provide implementation + * for IconIndex() method. + * + * @return TInt Icon index + */ + virtual TInt IconIndex() const = 0; + + /** + * Optional specific icon for this item. + * + * Returns new icon specific for the item. Note that this method is not + * used unless IconIndex() method returns EAppMngr2UseSpecificIcon value. + * + * The caller of this method is responsible to delete the returned + * icon object. + * + * Default implementation leaves with KErrNotSupported. Plug-in must + * override it if IconIndex() returns EAppMngr2UseSpecificIcon value. + * + * If the same icon bitmap is used in many items, it is more efficient + * to load it once in CAppMngr2Runtime::LoadIconsL() and return icon + * indexes form IconIndex() method. + * + * @return CGulIcon Item specific icon + */ + IMPORT_C virtual CGulIcon* SpecificIconL() const; + + /** + * Name of this item. + * + * Items are displayed in a list in the UI. The list uses two labels + * (name and details) for each item. Descriptor that the Name() method + * returns is displayed as the first label (the 1st line of the item). + * + * @return const TDesC& Displayable name + */ + virtual const TDesC& Name() const = 0; + + /** + * Details (size) of this item. + * + * Items are displayed in a list in the UI. The list uses two labels + * (name and details) for each item. Descriptor that the Details() method + * returns is displayed as the second label (the 2nd line of the item). + * + * Plug-ins can use SizeStringWithUnitsL() method to create details + * string to display the item size in UI. + * + * @returns const TDesC& Displayable additional information line + */ + virtual const TDesC& Details() const = 0; + + /** + * Indicator icon index of this item. + * + * Icon index can be either: + * - default icon index defined in TAppMngr2IconIndex in AppMngr2Common.hrh + * - index to icon array loaded in CAppMngr2Runtime::LoadIconsL() method + * - special value EAppMngr2UseSpecificIcon defined in AppMngr2Common.hrh + * + * Default implementation returns the default icon indexes based on + * the value of iLocation member variable, so plug-ins usually does not + * need to override this method. + * + * If EAppMngr2UseSpecificIcon value is returned, SpecificIndicatorIconL() + * method is called to get the indicator icon. + * + * @return TInt Index to the icon array, or a TAppMngr2IconIndex value + */ + IMPORT_C virtual TInt IndicatorIconIndex() const; + + /** + * Optional specific indicator icon for this item. + * + * Returns new indicator icon specific for the item. Note that this + * method is not used unless IndicatorIconIndex() method returns + * special EAppMngr2UseSpecificIcon value. + * + * The caller of this method is responsible to delete the returned + * icon object. + * + * Default implementation leaves with KErrNotSupported. Plug-in must + * override it if IndicatorIconIndex() returns EAppMngr2UseSpecificIcon. + * + * If the same icon bitmap is used in many items, it is more efficient + * to load it once in CAppMngr2Runtime::LoadIconsL() and return icon + * indexes form IconIndex() method. + * + * @return CGulIcon Item specific icon + */ + IMPORT_C virtual CGulIcon* SpecificIndicatorIconL() const; + + /** + * ShowOnTop highlight status of this item. + * + * Returns ETrue if this item should be highlighted (e.g. displayed + * separately on top of other items in installation files/installed + * applications list). All items are displayed in alphabetical order. + * If ShowOnTop flag is set, then the item is displayed before other + * items (or in completely separate list of highligted items). All + * separately displayed items are listed in alphabetical order too. + * + * @return TBool ETrue, if this item should be displayed separately + */ + IMPORT_C TBool IsShowOnTop() const; + + /** + * Optional specific menu items for this item. + * + * If the item supports specific menu commands, return the menu pane + * data. Plug-in can use ReadMenuItemDataFromResourceL() method to + * read menu pane data from resources. Menu commands are run via + * HandleCommandL() method. + * + * The caller of this method is responsible to delete the returned + * CEikMenuPaneItem::SData data structs. + * + * Default implementation is empty. + * + * @param aMenuCmds Array where plug-in specific menu items are added + */ + IMPORT_C virtual void GetMenuItemsL( RPointerArray& aMenuCmds ); + + /** + * Enable generic menu commands for this item. + * + * Generic menu commands are defined in TAppMngr2GenericCommands enum in + * AppMngr2Common.hrh. Generic commands are hidden from the menu if the + * currently selected item does not support them. Return ETrue for those + * command ids that are supported by this item. Generic commands are + * run via HandleCommandL() method. + * + * @param aCmdId Generic command id + * @return TBool ETrue if command aCmdId is supported + */ + IMPORT_C virtual TBool SupportsGenericCommand( TInt aCmdId ); + + /** + * Optional specific middle softkey command for this item. + * + * If the item supports specific middle softkey command, return TBUF + * resource id (for the command label) and command id. Item specific + * command is run via HandleCommandL() method when user presses the + * middle softkey. + * + * Default middle softkey command is used, if plug-in does not override it. + * + * @param aResourceId Command label to be displayed in UI (TBUF resource) + * @param aCommandId Command id to be passed to HandleCommandL + */ + IMPORT_C virtual void GetMiddleSoftkeyCommandL( TInt& aResourceId, TInt& aCommandId ); + + /** + * Starts asynchronously a user invoked command. + * + * The command can be a generic one or specific to the plug-in. The ids + * for the generic commands are defined in AppMngr2Common.hrh (see the + * enumeration TAppMngr2GenericCommand). The plug-in specific commands + * are defined via GetMenuItemsL() and GetMiddleSoftkeyCommandL() methods. + * + * The caller of this method must call HandleCommandResultL() after the + * asynchronous request has been completed. + * + * This asynchronous request must be completed properly using the method + * User::RequestComplete() even if the command itself has been implemented + * in synchronous manner. + * + * @param aCommandId Id of the command to be run + * @param aStatus Active object request status + */ + virtual void HandleCommandL( TInt aCommandId, TRequestStatus& aStatus ) = 0; + + /** + * Handles the completion result of an asynchronous command. + * + * This method is provided so that the plug-in may decide upon handling + * possible errors encountered during the command processing (note that + * the completion status is received directly by the caller of the method + * HandleCommandL() and not by this plug-in). These actions may include + * for example closing open sessions and deleting objects. + * + * This function should leave if an error note should be displayed in + * the UI (e.g. KErrNoMemory). Note that the result may be KErrCancel + * or SwiUI::KSWInstErrUserCancel if the user cancelled the operation. + * + * @param aResult Completion code, KErrNone or some error code + */ + virtual void HandleCommandResultL( TInt aResult ) = 0; + + /** + * Cancels the current asynchronous command. + * + * This method may be called at any time when an asynchronous command + * is started using HandleCommandL() method. It must cancel the running + * command as quickly as possible. + */ + virtual void CancelCommand() = 0; + + /** + * Utility function to create displayable string that contains size + * followed by kilobyte (kB), megabyte (MB) or gigabyte (GB) units. + * + * Size is rounded and formatted using the relevant unit, for example + * SizeStringWithUnitsL( 5120 ) returns "5 kB". + * + * The caller of this method is responsible to delete the returned string. + * + * @param aSizeInBytes Item size + * @return HBufC* New string that contains displayable size string + */ + IMPORT_C HBufC* SizeStringWithUnitsL( TInt64 aSizeInBytes ); + + /** + * Utility function to construct CEikMenuPaneItem from MENU_ITEM resource. + * + * @param aResourceId MENU_ITEM resource id + * @param aMenuItem CEikMenuPaneItem::SData struct that is filled in + */ + IMPORT_C void ReadMenuItemDataFromResourceL( TInt aResourceId, + CEikMenuPaneItem::SData& aMenuItem ); + + /** + * Returns the location of installation file or installed application. + * + * Remote drives are not supported. Derived class must fill in the + * iLocation member variable to provide data for this function. + * + * @return TAppMngr2Location Location of the item + */ + IMPORT_C TAppMngr2Location Location() const; + + /** + * Returns the drive where installation file is located, or where + * installed application is installed. + * + * Derived class must fill in the iLocationDrive member variable + * to provide data for this function. + * + * @return TDriveUnit Drive where the item is located + */ + IMPORT_C TDriveUnit LocationDrive() const; + +protected: // new functions + /** + * Constructor, not exported because used via CAppMngr2AppInfo and CAppMngr2PackageInfo + */ + CAppMngr2InfoBase( CAppMngr2Runtime& aRuntime, RFs& aFsSession ); + +protected: // data + /** + * Location of this item. + * + * Default implementation of IndicatorIconIndex() function uses this + * value to return the default indicator icon index. See also the + * Location() function defined above. + */ + TAppMngr2Location iLocation; + + /** + * Drive of this item. + * + * Location drive defines the drive where this item resides (either + * installation package is stored, or application is installed). + * CAppMngr2InfoIterator uses this value to display the drive + * in "Details" dialog. See also the LocationDrive() function + * defined above. + */ + TDriveUnit iLocationDrive; + + /** + * ShowOnTop (highlight) flag. + * + * If ShowOnTop flag is ETrue, the item is highlighted in UI. It + * may be displayed on top of other items in installed application + * or installation files list, or it may be displayed in separate + * list of highlighted items. + * + * For example, untrusted installed applications can be highlighted. + * + * + * The + * item should indicate the reason why it is not displayed normally + * when iShowOnTop is set to ETrue (e.g. use special icon). + * See also the IsShowOnTop() function defined above. + */ + TBool iShowOnTop; + + /** + * File server session, provided by framework when item is created. + */ + RFs& iFs; + +private: // data + /** + * Reference to CAppMngr2Runtime class for this item. + * See also the Runtime() function defined above. + */ + CAppMngr2Runtime& iRuntime; + }; + +#endif // C_APPMNGR2INFOBASE_H +