--- /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 <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
+