/*
* 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 <e32base.h> // CBase
#include <apmrec.h> // 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<HBufC>& 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<CAppMngr2PackageInfo>& aPackageInfos,
const RPointerArray<CAppMngr2RecognizedFile>& 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<CAppMngr2AppInfo>& 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