diff -r 000000000000 -r ba25891c3a9e appinstall_plat/appmngr2runtimeapi/inc/appmngr2runtime.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/appinstall_plat/appmngr2runtimeapi/inc/appmngr2runtime.h Thu Dec 17 08:51:10 2009 +0200 @@ -0,0 +1,288 @@ +/* +* 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 for AppMngr2 plug-ins that define runtime types +* +*/ + + +#ifndef C_APPMNGR2RUNTIME_H +#define C_APPMNGR2RUNTIME_H + +#include // CBase +#include // CDataTypeArray + +class CAppMngr2AppInfo; +class CAppMngr2PackageInfo; +class CAppMngr2RecognizedFile; +class MAppMngr2RuntimeObserver; +class CAknIconArray; +class CEikonEnv; + + +/** + * ECom interface UID for AppMngr2 Runtime plugins + */ +const TUid KAppMngr2PluginInterface = { 0x20016BF4 }; + + +/** + * Base class for Application Manager Runtime plug-ins. + * + * CAppMngr2Runtime class represents one Runtime plug-in. As it is abstract + * class plug-in must provide the actual implementation using derived class. + * + * Application Manager lists ECom plug-ins implementing KAppMngr2PluginInterface + * and creates new CAppMngr2Runtime objects. Creating new CAppMngr2Runtime object + * loads the Runtime plug-in's DLL and instantiates it. + * + * After all Runtime plug-ins are loaded, Application Manager calls LoadIconsL() + * to load plug-in specific icons, GetSupportedDataTypesL() to identify installation + * files that this plug-in support, and GetAdditionalDirsToScanL() to get plug-in + * specific directories that may contain installation files. Then Application Manager + * scans directories and recognizes files in them, and proceeds to get installed + * applications and installation packages. Installed applications are prompted from + * each plug-in via GetInstalledAppsL() method. Each plug-in creates CAppMngr2AppInfo + * derived objects to represent currently installed applications. Installation packages + * are based on recognized files in scanned directories. Application Manager provides + * list of files that match the supported data types via GetInstallationFilesL() + * method, and the plug-in creates CAppMngr2PackageInfo objects representing + * installation packages. + * + * Application Manager monitors changes in scanned directories and known application + * registeries. When a change is notified, Application Manager gets the latest data + * using GetInstalledAppsL() and GetInstallationFilesL() methods again. If Application + * Manager does not listen some specific registry, plug-in can notify change using + * MAppMngr2RuntimeObserver interface. + * + * @lib appmngr2pluginapi.lib + * @since S60 v5.1 + */ +class CAppMngr2Runtime : public CBase + { +public: // constructor and destructor + + /** + * ECom object instantiation. + * + * Loads the ECom plug-in DLL and instantiates new Runtime plug-in object. + * + * @param aUid Specifices the concrete implementation + * @param aObserver Observer implementing MAppMngr2RuntimeObserver functions + * @return CAppMngr2Runtime New Runtime plug-in object + */ + IMPORT_C static CAppMngr2Runtime* NewL( TUid aImplementationUid, + MAppMngr2RuntimeObserver &aObserver ); + + /** + * Destructs the ECom object and unloads the plug-in DLL. + */ + IMPORT_C ~CAppMngr2Runtime(); + + +public: // new functions + + /** + * Runtime plug-in UID. + * + * Returns UID that identifies the runtime plug-in + * + * $return TUid Runtime plug-in UID + */ + IMPORT_C const TUid RuntimeUid() const; + + /** + * Utility function to open resource file. + * + * Adds nearest localized resource file to the list maintained by CCoeEnv. + * Uses DriveInfo::EDefaultRom drive and KDC_RESOURCE_FILES_DIR directory + * by default, if not defined in aFileName. Nearest extension language code + * is obtained from BaflUtils::NearestLanguageFile(). Added resource files + * must be deleted using CCoeEnv::DeleteResourceFile() function. + * + * @param aFileName Resource file name + * @return TInt Offset value for this resource file + */ + IMPORT_C TInt AddNearestResourceFileL( const TDesC& aFileName ); + + /** + * Utility function to construct full bitmap file name. + * + * Constructs the file name using DriveInfo::EDefaultRom drive, + * KDC_APP_BITMAP_DIR directory, and given MBM/MIF file name. + * + * The caller of this method is responsible to delete the retuned string. + * + * @param aBitmapFile MBM or MIF file name + * @return HBufC* Full file name for aBitmapFile + */ + IMPORT_C HBufC* FullBitmapFileNameLC( const TDesC& aBitmapFile ); + + /** + * Utility function to return cached CEikonEnv reference. + * + * @return CEikonEnv& Reference to cached CEikonEnv::Static() instance + */ + IMPORT_C CEikonEnv& EikonEnv(); + + /** + * Runtime observer. + * + * Returns reference to object implementing MAppMngr2RuntimeObserver + * interface. See appmngr2runtimeobserver.h for more info. + * + * @return MAppMngr2RuntimeObserver& Reference to observer + */ + IMPORT_C MAppMngr2RuntimeObserver& Observer(); + +public: // new pure virtual functions + + /** + * Load icons for this plug-in. + * + * Plug-in specific icons are used when CAppMngr2InfoBase::IconIndex() + * or CAppMngr2InfoBase::IndicatorIconIndex() return indexes to the + * returned aIconArray. + * + * There are no default icons, so each plug-in must provide implementation + * for LoadIconsL() method. + * + * @param aIconArray Array where to append the loaded icons + */ + virtual void LoadIconsL( CAknIconArray& aIconArray ) = 0; + + /** + * Supported data types for this plug-in. + * + * Return MIME types that this Runtime plug-in supports for creating + * installation packages (CAppMngr2PackageInfo objects). Application + * Manager scans installation files and recognizes file types. Files + * that match to the supported MIME types are provided to the plug-in + * via GetInstallationFilesL() method. + * + * Scanning and recognizing is implemented in Application Manager for + * performance reasons. Plug-ins should not scan or recognize files as + * Application Manager has done it already once and it provides list + * of files and their MIME types to the plug-ins. + * + * @param aDataTypeArray Array where to append supported data types + */ + virtual void GetSupportedDataTypesL( CDataTypeArray& aDataTypeArray ) = 0; + + /** + * Define additional directories for installation file scanning. + * + * By default all PathInfo::EInstallsPath directories in all non-remote + * drives are scanned. Also KSWInstallerPackageFolder directory defined + * in CenRep is scanned. Use this function to add more directories for + * scanning. All directory names are checked with RFs::IsValidName() and + * invalid names are ignored. Wild-cards (like '*') are not allowed in + * directory names. + * + * @param aFsSession File server session + * @param aDirs Array where to append additional directories to scan + */ + IMPORT_C virtual void GetAdditionalDirsToScanL( RFs& aFsSession, + RPointerArray& aDirs ); + + /** + * Create package info objects. + * + * Package info objects represent installation files in "Installation + * Files" view. Each package info object is displayed as a separate item. + * Package info objects should be based on recognized installation files, + * provided in aFileList array. + * + * GetInstallationFilesL() may be called several times. It is called once + * for each scanned directory that contains recognized files for this Runtime + * plugin. + * + * This asynchronous request must be completed properly using the method + * User::RequestComplete() even if the GetInstallationFilesL() itself has + * been implemented in synchronous manner. Outstanding request may be + * cancelled by calling CancelGetInstallationFiles(). + * + * @param aPackageInfos Array where to append package info objects + * @param aFileList List of file names and corresponding MIME types + * @param aFsSession File server session + * @param aStatus Request status for the asynchronous request + */ + virtual void GetInstallationFilesL( + RPointerArray& aPackageInfos, + const RPointerArray& aFileList, + RFs& aFsSession, + TRequestStatus& aStatus ) = 0; + + /** + * Cancel pending asynchronous GetInstallationFilesL() request. + */ + virtual void CancelGetInstallationFiles() = 0; + + /** + * Create application info objects. + * + * Application info objects represent installed applications in "Installed" + * view. Each application info object is displayed as a separate item. + * + * This asynchronous request must be completed properly using the method + * User::RequestComplete() even if the GetInstalledAppsL() itself has + * been implemented in synchronous manner. Outstanding request may be + * cancelled by calling CancelGetInstalledApps(). + * + * @param aApps Array where to add application info objects + * @param aFsSession File server session + * @param aStatus Request status for the asynchronous request + */ + virtual void GetInstalledAppsL( + RPointerArray& aApps, + RFs& aFsSession, + TRequestStatus& aStatus ) = 0; + + /** + * Cancel pending asynchronous GetInstalledAppsL() request. + */ + virtual void CancelGetInstalledApps() = 0; + +protected: // new functions + /** + * Protected constructor exported for derived classes. + */ + IMPORT_C CAppMngr2Runtime( MAppMngr2RuntimeObserver &aObserver ); + +private: // new functions + void ConstructL( TUid aImplementationUid ); + +private: // data + /** + * ECom instance identifier key. + */ + TUid iDtorIDKey; + + /** + * Implementation UID that identifies the plugin. + */ + TUid iRuntimeUid; + + /** + * Application implementing observer interface. + */ + MAppMngr2RuntimeObserver& iObserver; + + /** + * CEikonEnv pointer, cached from CEikonEnv::Static(). + */ + CEikonEnv* iCachedEikonEnv; // not owned + }; + +#endif // C_APPMNGR2RUNTIME_H +