1 /*

     2 * Copyright (c) 2008 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:   Base class for AppMngr2 plug-ins that define runtime types

    15 *

    16 */

    17 

    18 

    19 #ifndef C_APPMNGR2RUNTIME_H

    20 #define C_APPMNGR2RUNTIME_H

    21 

    22 #include <e32base.h>                    // CBase

    23 #include <apmrec.h>                     // CDataTypeArray

    24 

    25 class CAppMngr2AppInfo;

    26 class CAppMngr2PackageInfo;

    27 class CAppMngr2RecognizedFile;

    28 class MAppMngr2RuntimeObserver;

    29 class CAknIconArray;

    30 class CEikonEnv;

    31 

    32 

    33 /**

    34  *  ECom interface UID for AppMngr2 Runtime plugins

    35  */

    36 const TUid KAppMngr2PluginInterface = { 0x20016BF4 };

    37 

    38 

    39 /**

    40  * Base class for Application Manager Runtime plug-ins.

    41  * 

    42  * CAppMngr2Runtime class represents one Runtime plug-in. As it is abstract

    43  * class plug-in must provide the actual implementation using derived class.

    44  * 

    45  * Application Manager lists ECom plug-ins implementing KAppMngr2PluginInterface

    46  * and creates new CAppMngr2Runtime objects. Creating new CAppMngr2Runtime object

    47  * loads the Runtime plug-in's DLL and instantiates it.

    48  * 

    49  * After all Runtime plug-ins are loaded, Application Manager calls LoadIconsL()

    50  * to load plug-in specific icons, GetSupportedDataTypesL() to identify installation

    51  * files that this plug-in support, and GetAdditionalDirsToScanL() to get plug-in

    52  * specific directories that may contain installation files. Then Application Manager

    53  * scans directories and recognizes files in them, and proceeds to get installed

    54  * applications and installation packages. Installed applications are prompted from

    55  * each plug-in via GetInstalledAppsL() method. Each plug-in creates CAppMngr2AppInfo

    56  * derived objects to represent currently installed applications. Installation packages

    57  * are based on recognized files in scanned directories. Application Manager provides

    58  * list of files that match the supported data types via GetInstallationFilesL()

    59  * method, and the plug-in creates CAppMngr2PackageInfo objects representing

    60  * installation packages.

    61  * 

    62  * Application Manager monitors changes in scanned directories and known application

    63  * registeries. When a change is notified, Application Manager gets the latest data

    64  * using GetInstalledAppsL() and GetInstallationFilesL() methods again. If Application

    65  * Manager does not listen some specific registry, plug-in can notify change using

    66  * MAppMngr2RuntimeObserver interface.

    67  * 

    68  * @lib appmngr2pluginapi.lib

    69  * @since S60 v5.1

    70  */

    71 class CAppMngr2Runtime : public CBase

    72     {

    73 public:     // constructor and destructor

    74 

    75     /**

    76      * ECom object instantiation.

    77      * 

    78      * Loads the ECom plug-in DLL and instantiates new Runtime plug-in object.

    79      * 

    80      * @param aUid Specifices the concrete implementation

    81      * @param aObserver Observer implementing MAppMngr2RuntimeObserver functions

    82      * @return CAppMngr2Runtime  New Runtime plug-in object

    83      */

    84     IMPORT_C static CAppMngr2Runtime* NewL( TUid aImplementationUid,

    85             MAppMngr2RuntimeObserver &aObserver );

    86     

    87     /**

    88      * Destructs the ECom object and unloads the plug-in DLL.

    89      */

    90     IMPORT_C ~CAppMngr2Runtime();

    91 

    92 

    93 public:     // new functions

    94 

    95     /**

    96      * Runtime plug-in UID.

    97      * 

    98      * Returns UID that identifies the runtime plug-in

    99      * 

   100      * $return TUid  Runtime plug-in UID

   101      */

   102     IMPORT_C const TUid RuntimeUid() const;

   103 

   104     /**

   105      * Utility function to open resource file.

   106      * 

   107      * Adds nearest localized resource file to the list maintained by CCoeEnv.

   108      * Uses DriveInfo::EDefaultRom drive and KDC_RESOURCE_FILES_DIR directory

   109      * by default, if not defined in aFileName. Nearest extension language code

   110      * is obtained from BaflUtils::NearestLanguageFile(). Added resource files

   111      * must be deleted using CCoeEnv::DeleteResourceFile() function.

   112      * 

   113      * @param aFileName  Resource file name

   114      * @return TInt  Offset value for this resource file

   115      */

   116     IMPORT_C TInt AddNearestResourceFileL( const TDesC& aFileName );

   117 

   118     /**

   119      * Utility function to construct full bitmap file name.

   120      * 

   121      * Constructs the file name using DriveInfo::EDefaultRom drive,

   122      * KDC_APP_BITMAP_DIR directory, and given MBM/MIF file name.

   123      * 

   124      * The caller of this method is responsible to delete the retuned string.

   125      * 

   126      * @param aBitmapFile  MBM or MIF file name

   127      * @return HBufC*  Full file name for aBitmapFile

   128      */

   129     IMPORT_C HBufC* FullBitmapFileNameLC( const TDesC& aBitmapFile );

   130     

   131     /**

   132      * Utility function to return cached CEikonEnv reference.

   133      * 

   134      * @return CEikonEnv&  Reference to cached CEikonEnv::Static() instance

   135      */

   136     IMPORT_C CEikonEnv& EikonEnv();

   137     

   138     /**

   139      * Runtime observer.

   140      * 

   141      * Returns reference to object implementing MAppMngr2RuntimeObserver

   142      * interface. See appmngr2runtimeobserver.h for more info.

   143      * 

   144      * @return MAppMngr2RuntimeObserver&  Reference to observer

   145      */ 

   146     IMPORT_C MAppMngr2RuntimeObserver& Observer();

   147 

   148 public:     // new pure virtual functions

   149 

   150     /**

   151      * Load icons for this plug-in.

   152      * 

   153      * Plug-in specific icons are used when CAppMngr2InfoBase::IconIndex()

   154      * or CAppMngr2InfoBase::IndicatorIconIndex() return indexes to the

   155      * returned aIconArray.

   156      *

   157      * There are no default icons, so each plug-in must provide implementation

   158      * for LoadIconsL() method. 

   159      * 

   160      * @param aIconArray  Array where to append the loaded icons 

   161      */

   162     virtual void LoadIconsL( CAknIconArray& aIconArray ) = 0;

   163 

   164     /**

   165      * Supported data types for this plug-in.

   166      * 

   167      * Return MIME types that this Runtime plug-in supports for creating

   168      * installation packages (CAppMngr2PackageInfo objects). Application

   169      * Manager scans installation files and recognizes file types. Files

   170      * that match to the supported MIME types are provided to the plug-in

   171      * via GetInstallationFilesL() method.

   172      * 

   173      * Scanning and recognizing is implemented in Application Manager for

   174      * performance reasons. Plug-ins should not scan or recognize files as

   175      * Application Manager has done it already once and it provides list 

   176      * of files and their MIME types to the plug-ins.

   177      * 

   178      * @param aDataTypeArray  Array where to append supported data types   

   179      */

   180     virtual void GetSupportedDataTypesL( CDataTypeArray& aDataTypeArray ) = 0;

   181     

   182     /**

   183      * Define additional directories for installation file scanning.

   184      * 

   185      * By default all PathInfo::EInstallsPath directories in all non-remote

   186      * drives are scanned. Also KSWInstallerPackageFolder directory defined

   187      * in CenRep is scanned. Use this function to add more directories for

   188      * scanning. All directory names are checked with RFs::IsValidName() and

   189      * invalid names are ignored. Wild-cards (like '*') are not allowed in

   190      * directory names.

   191      * 

   192      * @param aFsSession  File server session 

   193      * @param aDirs  Array where to append additional directories to scan

   194      */

   195     IMPORT_C virtual void GetAdditionalDirsToScanL( RFs& aFsSession,

   196             RPointerArray<HBufC>& aDirs );

   197     

   198     /**

   199      * Create package info objects.

   200      * 

   201      * Package info objects represent installation files in "Installation

   202      * Files" view. Each package info object is displayed as a separate item.

   203      * Package info objects should be based on recognized installation files,

   204      * provided in aFileList array.

   205      * 

   206      * GetInstallationFilesL() may be called several times. It is called once

   207      * for each scanned directory that contains recognized files for this Runtime

   208      * plugin.

   209      *

   210      * This asynchronous request must be completed properly using the method

   211      * User::RequestComplete() even if the GetInstallationFilesL() itself has

   212      * been implemented in synchronous manner. Outstanding request may be

   213      * cancelled by calling CancelGetInstallationFiles().

   214      * 

   215      * @param aPackageInfos  Array where to append package info objects

   216      * @param aFileList  List of file names and corresponding MIME types

   217      * @param aFsSession  File server session

   218      * @param aStatus  Request status for the asynchronous request

   219      */

   220     virtual void GetInstallationFilesL(

   221             RPointerArray<CAppMngr2PackageInfo>& aPackageInfos,

   222             const RPointerArray<CAppMngr2RecognizedFile>& aFileList,

   223             RFs& aFsSession,

   224             TRequestStatus& aStatus ) = 0;

   225 

   226     /**

   227      * Cancel pending asynchronous GetInstallationFilesL() request.

   228      */

   229     virtual void CancelGetInstallationFiles() = 0;

   230     

   231     /**

   232      * Create application info objects.

   233      * 

   234      * Application info objects represent installed applications in "Installed"

   235      * view. Each application info object is displayed as a separate item.

   236      *

   237      * This asynchronous request must be completed properly using the method

   238      * User::RequestComplete() even if the GetInstalledAppsL() itself has

   239      * been implemented in synchronous manner. Outstanding request may be

   240      * cancelled by calling CancelGetInstalledApps().

   241      * 

   242      * @param aApps  Array where to add application info objects

   243      * @param aFsSession  File server session

   244      * @param aStatus  Request status for the asynchronous request

   245      */

   246     virtual void GetInstalledAppsL(

   247             RPointerArray<CAppMngr2AppInfo>& aApps,

   248             RFs& aFsSession,

   249             TRequestStatus& aStatus ) = 0;

   250     

   251     /**

   252      * Cancel pending asynchronous GetInstalledAppsL() request.

   253      */

   254     virtual void CancelGetInstalledApps() = 0;

   255 

   256 protected:  // new functions

   257     /**

   258      * Protected constructor exported for derived classes.

   259      */

   260     IMPORT_C CAppMngr2Runtime( MAppMngr2RuntimeObserver &aObserver );

   261 

   262 private:    // new functions

   263     void ConstructL( TUid aImplementationUid );

   264 

   265 private:    // data

   266     /**

   267      * ECom instance identifier key.

   268      */

   269     TUid iDtorIDKey;

   270 

   271     /**

   272      * Implementation UID that identifies the plugin.

   273      */

   274     TUid iRuntimeUid;

   275 

   276     /**

   277      * Application implementing observer interface.

   278      */

   279     MAppMngr2RuntimeObserver& iObserver;

   280 

   281     /**

   282      * CEikonEnv pointer, cached from CEikonEnv::Static().

   283      */

   284     CEikonEnv* iCachedEikonEnv;   // not owned

   285     };

   286 

   287 #endif // C_APPMNGR2RUNTIME_H

   288