// Copyright (c) 1997-2009 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:

// Definition of the CDiscoverer class

// 

//

/**

 @file

 @internalComponent

*/

#ifndef __DISCOVERER_H__

#define __DISCOVERER_H__

#include <e32base.h>

#include <f32file.h>

#include <e32property.h> // for RProperty

#include <domaindefs.h> // for TDmDomainState

#include "DiscovererObserver.h"	// The MDiscovererObserver class

#include "EComEntry.h"

#include "EComEntryBase.h"

#include "callback.h"

// Platsec path to binaries

_LIT(KSysBin,"\\sys\\bin\\");

// Platsec path to resources

_LIT(KResourcePlugins,"\\resource\\plugins\\");

_LIT(KDllExtension,".dll");

_LIT(KRscExtension,".rsc");

// Length of extension of file name.

//The language extension length including the "." is assumed to be 4 

const TInt KExtensionLength=4;

//Max lenth for plugin resource path

const TInt32 KEComPlugRSCPathMaxLen	=	50;

//class forward declare

class CEnvironmentChangeNotifier;

/**

	@internalComponent

	@since 7.0

	Responsible for Interface Implementation Collections,

	installed in the Interface Implementation Collection directories.

 */

class CDiscoverer : public CBase 

{

public:

/** Transition flag for Notification*/

	enum TNotificationFlag

	{

	/** A new plugin added or removed*/

	EPluginsModified,

	/**should do a rediscovery */

	EPluginsRediscover

	};

/** State declaration for CDiscoverer */	

	enum TDiscovererState

	{

	/** Undefined state */

	EDisc_Undefined,

	/** Initialize state */

	EDisc_NoPluginsDisc,

	/** Discover plugins on Ro Internal drive units */

	EDisc_CriticalPluginsDisc,

	/** All plugins are discovered.*/

	EDisc_AllPluginsDisc,

	/** Plugins added or removed, going to rediscover all plugins */

	EDisc_PluginsDirty

	};

/**

	@fn				NewL(MDiscovererObserver& aDiscovererObserver, RFs& aFs)

	Intended Usage	: Standardised safe construction which leaves nothing

					  on the cleanup stack.

	Error Condition	: Not enough memory available.	

	@leave  		KErrNoMemory

	@since			7.0

	@param			aDiscovererObserver A reference to the owning client 

					of the CDiscoverer

	@param			aFs A reference to a connected file server instance.

	@return			CDiscoverer* a pointer to the new class

	@pre 			None

	@post			CDiscoverer is fully constructed, and initialised.

 */

	static CDiscoverer* NewL(MDiscovererObserver& aDiscovererObserver, RFs& aFs);

/**

	@fn				~CDiscoverer()

	Intended Usage	: Standard default d'tor	

	Error Condition	: None	

	@since			7.0

	@pre 			CDiscoverer is fully constructed.

	@post			CDiscoverer is totally destroyed.

 */

	~CDiscoverer();

/**

	@fn				Resume()

	Intended Usage	: Re-enable the Discoverer to continue checking for new 

					  interface implementations. 

	Error Condition	: Where resume of the discoverer fails. KErrResumeFailed.

	@since			7.0

	@return			TInt The status of the operation. KErrNone or KErrResumeFailed.

	@pre 			CDiscoverer is fully constructed.

	@post			The operation of the discoverer has been resumed. Or where

					resumption failed, no change.

 */

	TInt Resume();

/**

	@fn				Suspend()

	Intended Usage	: Temporarily stop looking for new interface implementations.

	Error Condition	: Where suspension of the discoverer fails. KErrSuspendFailed.

	@since			7.0

	@return			TInt The status of the operation. KErrNone or KErrSuspendFailed.

	@pre 			CDiscoverer is fully constructed.

	@post			The operation of the discoverer has been suspended. Or where

					suspend failed, no change.

 */

	TInt Suspend();

/**

	@fn 			ProcessSSAEventL()

	Intended Usage	: It discovers the plugins on different Drive Units according to 

					the passing state. It will be used by CRegistrar to notify the 

					object of the system start-up state changes.

	@param 			aKnownState the start-up state passing in to CDiscoverer

	@pre			CDiscoverer is fully constructed

	@post			CDiscoverer is notified of the start-up state change

*/

	void ProcessSSAEventL(TStartupStateIdentifier aKnownState);

/** 

	@fn 			ProcessDNEventL()

	Intended Usage	:It will be used by one iRscDirNotifier in iRscDirNotifierList 

					to indicate that plugins have been removed or added(state is 

					EDisc_PluginsDirty) and to start a 

					re-discovery(when done, state is EDisc_AllPluginsDisc).

	@leave			KErrNoMemory

	@param			:aFlag the notification transition flag.

	@param			:aDriveUnit a drive which on the plugins has been changed and need to re-discovery

	@pre 			:CDiscoverer is fully constructed.

	@post			: state will be changed, and a re-discovery will happen 

					if the current state is EDisc_PluginsDirty. 

*/

	void ProcessDNEventL(TNotificationFlag aFlag, const TDriveUnit& aDriveUnit);

/**

	@fn 			State()

	Intended Usage	:Retrieve the object's current state.

	@return 		TDiscovererState the CDiscoverer's current state.

	@pre			CDiscoverer is fully constructed.

	@post 			the CDiscoverer's current state has been returned.

*/

	TDiscovererState State() const;

/** Set the iSwiChangeCallBack member

@param aCallBack new value for iSwiChangeCallBack

*/

	void SetSwiChangeCallBack(const TCallBackWithArg& aCallBack);

/** Set the iBurChangeCallBack member

@param aCallBack new value for iBurChangeCallBack

*/

	void SetBurChangeCallBack(const TCallBackWithArg& aCallBack);

private:

/**

	@internalComponent

	@fn				CDiscoverer(MDiscovererObserver& aDiscovererObserver, RFs& aFs)

	Intended Usage	: Standardised default c'tor	

	Error Condition	: None	

	@since			7.0

	@param			aDiscovererObserver A reference to the owning client 

					of the CDiscoverer

	@param			aFs A reference to an connected file server instance.

	@pre 			None

	@post			CDiscoverer is fully constructed

 */

	CDiscoverer(MDiscovererObserver& aDiscovererObserver, RFs& aFs);

/**

	@fn				ConstructL()

	Intended Usage	: Standardised 2nd, (Initialisation) phase of two phase construction.

	Error Condition	: Leaves with error code : usually KErrNoMemory.

	@leave  		KErrNoMemory.

	@since			7.0

	@return			void 

	@pre 			CDiscoverer is fully constructed.

	@post			CDiscoverer is fully initialised.

 */

	void ConstructL();

/**

	@fn				NotificationL(TInt aStatus)

	Intended Usage	: Called by the one object of iRscDirNotifierList when the 

					contents of the Interface Implementation directories

					has changed on a specified drive.

	Error Condition	: None	

	@leave			KErrNoMemory

	@since			7.0

	@param			aDriveUnit a drive which has changes.

	@return			ETrue to indicate the notifier should re-activate.

	@pre 			CDiscoverer is fully constructed.

	@post			CDiscoverer has been notified that a re-scan of the 

					plugin directories is required.

 */

	TBool NotificationL(TInt aStatus, const TDriveUnit& aDriveUnit);

/**

	@fn				SwiChangeNotificationL(TInt aSwiOperation)

	Intended Usage	: Called by iSwiChangeNotifier when it is notified of a

					SWI changed.

	Error Condition	: None	

	@since			9.2

	@param			aSwiOperation the SWI operation that is currently taking place

	@pre 			CDiscoverer is fully constructed.

	@post			CDiscoverer has been notified that a re-scan of the

					removable plugin directories is required and has stored current

					SWI operation.

 */

	void SwiChangeNotificationL(TInt aSwiOperation);

/**

	@fn				LanguageChangeNotificationL()

	Intended Usage	: Called by iLanguageChangeNotifier when it is notified of language

					downgrade path changed.

	Error Condition	: None	

	@since			9.3

	@pre 			CDiscoverer is fully constructed.

	@post			CDiscoverer has been notified that a rescan may be required

 */

	void LanguageChangeNotificationL();

	// Methods used by the Incremental Directory Scanning mechanism

/**

	@fn				void RediscoveryScanDirectoryL()

	Intended Usage	: Perform a scan on the Interface Implementation 

					Collection directories on a specified drive.

	Error Condition	: Not enough memory available	

	@leave  		KErrNoMemory

	@since			7.0

	@param			:A drive on which the directory is scanned.

	@return			void

	@pre 			CDiscoverer is fully constructed.

	@post			The scan of the Interface Implementation Collection 

					directories has processed on a specified drive.

 */

	void RediscoveryScanDirectoryL(const TDriveUnit& aDriveUnit);

/**

	@fn				void ScanDirectoryCancel()

	Intended Usage	: Cancel any scan of the Interface Implementation Collection 

					directories in progress.

	Error Condition	: None	

	@since			7.0

	@return			void 

	@pre 			CDiscoverer is fully constructed.

	@post			The re-scan of the Interface Implementation 

					Collection directories has beed aborted.

 */

	void ScanDirectoryCancel();

/**

	@fn				CompleteNotificationProcessing()

	Intended Usage	: Signal that the directory change notification has

					 been fully processed on all drives.

	Error Condition	: None	

	@since			7.0

	@pre 			CDiscoverer is fully constructed.

	@post			An asynchronous re-scan of the Interface Implementation 

					Collection directories is complete.

 */

	void CompleteNotificationProcessing();

/**

	@fn				ValidateEntryL(const TEntry& aEntry, const TDriveName& aDriveName, CPluginBase*& aEntryToFill,TBool aIsRO)

	Intended Usage	: Verify that a Interface Implementation Collection directories entry is valid

					discovery.

	Error Condition	: No memory

	@leave  		KErrNoMemory

	@since			9.1

	@param			aEntry	A directory entry for an Interface Implementation Collection.

	@param			aDriveName	The drive containing this entry

	@param			aEntryToFill A newly created directory entry with the 

					filename updated to include the full path.

	@param			aIsRO	Indicates whether current drive is Read Only

	@pre 			CDiscoverer is fully constructed, 

					aEntry, aPath and aEntryToFill are all valid references.

	@post			aEntryToFill is created and valid, with the full path and filename as its name entry.

 */

	void ValidateEntryL(const TEntry& aEntry, const TDriveName& aDriveName, CPluginBase*& aEntryToFill, TBool aIsRO);

/**

	@fn				ValidateEntryL(RResourceArchive& aRscArchive,CPluginBase*& aEntryToFill);

	Intended Usage	: Verify that a Interface Implementation Collection directories entry is valid

					discovery.

	Error Condition	: No memory

	@leave  		KErrNoMemory

	@since			9.1

	@param			aRscArchive A referernce to the resource archive

	@param			aEntryToFill A newly created directory entry with the 

					filename updated to include the full path.

	@pre 			CDiscoverer is fully constructed, 

	@post			aEntryToFill is created and valid, with the full path and filename as its name entry.

 */

	void ValidateEntryL(RResourceArchive& aRscArchive, CPluginBase*& aEntryToFill);

/**

	@fn				ProcessEntryL(const TDriveName& aDrive,CPluginBase*& aEntry, TBool aAnyDllDiscovered)

	Intended Usage	: Verify that a Interface Implementation Collection directories entry is valid

					discovery.

	Error Condition	: Depends on the observer implementation.	

	@leave  		Depends on the observer implementation. (@see CRegistrar).

	@since			9.1

	@param			aDrive the drive name containing this entry

	@param			aEntry	A directory entry for an Interface Implementation Collection.

	@param			aAnyDllDiscovered a flag to tell if any Dll is discovered in the drive.

	@pre 			CDiscoverer is fully constructed.

	@post			The directory entry has been processed by the observer.

 */

	void ProcessEntryL(const TDriveName& aDrive, CPluginBase*& aEntry, TBool aAnyDllDiscovered);

/**

	@fn				DriveMountedL(TDriveUnit aDrive)

	Intended Usage	: Signal a drive is available.

	Error Condition	: Depends on the observer implementation.	

	@leave  		Depends on the observer implementation. @see CRegistrar.

	@since			7.0

	@param			aDrive	The drive to be noted as available.

	@return			void. 

	@pre 			CDiscoverer is fully constructed.

	@post			The drive mount has been signalled to the observer.

 */

	void DriveMountedL(TDriveUnit aDrive);

/**

	@fn				DriveUnmountedL(TDriveUnit aDrive)

	Intended Usage	: Signal a drive is unavailable.

	Error Condition	: Leaves with an error code

	@leave			KErrNoMemory

	@since			7.0

	@param			aDrive	The drive to be noted as unavailable.

	@pre 			CDiscoverer is fully constructed.

	@post			The drive dismount has been signalled to the observer.

 */

	void DriveUnmountedL(TDriveUnit aDrive);

/**

	@fn 			StartNotifiers()

	Intended Usage	: start the iRscDirNotifierList and iSwiChangeNotifier when EDisc_AllPlugins

					state is reached.

	@pre 			: CDiscoverer is fully constructed. and iRscDirNotifierList and iSwiChangeNotifier

					are fully constructed.

	@post			: iRscDirNotifierList Activate and iSwiChangeNotifier Subscribe methods are called.

*/

	void StartNotifiers();

/** 

	@fn 			InitialiseEvent()

	Intended Usage	: called during the CDiscoverer's construction 

					to change the state.

	@pre			: non

	@post			: State is changed from EDisc_Undefined to EDisc_NoPluginsDisc.

*/		

	void InitialiseEvent();

/**

	@fn				IsAnyDllRegisteredWithDriveL(const TDriveUnit aDrive)

	Intended Usage	: Find if any Dll is registered in the drive.

	@param 			: aDrive the identifier of the drive to find if any Dll is registered.

	@return			: ETrue if any Dll is registered in the drive unit, otherwise EFalse.

	@pre 			: CDiscoverer is fully constructed.

	@post 			: If any Dll registered info will be returned.

*/	

	TBool IsAnyDllRegisteredWithDriveL(const TDriveUnit aDrive)const ;	

/**

	@fn				SwiOperationInProgress()

	Intended Usage	: Determine if any SWI operation is currently in progress

	@return			: ETrue if any SWI operation is in progress otherwise EFalse.

	@pre 			: CDiscoverer is fully constructed.

	@post 			: None

*/	

	TBool SwiOperationInProgress() ;

/**

	@fn				LocaleChangedL(TAny*)

	Intended Usage	: Callback function to be attached to an instance of CEnvironmentChangeNotifier to 

					  rebuild registry data. Note that this has to be a static member function.

	@param 			: A parameter to be passed usually with a "this" pointer so that while the function

					  remaining a static function it can access all the member data anyway.

	@return			: ETrue if language downgrade path is changed, otherwise EFalse.

	@pre 			: CDiscoverer is fully constructed.

	@post 			: Call LanguageChangeNotificationL method to rescan resource files.

*/		

	static TInt LocaleChangedL(TAny*) ;

// Attributes

private:

	// Define the helper classes which handle the 

	// notification processing.

	class CDirChangeNotifier;

	typedef RPointerArray<CDirChangeNotifier> RDirChangeNotifierPointerArray;

	// Handles notifications of changes to plugin resources directory on list of drives.

	RDirChangeNotifierPointerArray iRscDirNotifierList;

	class CSwiChangeNotifier;

	// Handles notifications of changes to SWI

	CSwiChangeNotifier* iSwiChangeNotifier;

	// Indicates whether a discovery due to SWI changes is pending

	TBool iSwiChangeDiscoveryPending;

	//Handle notifications of changes to environment (including language switch)

	CEnvironmentChangeNotifier* iLanguageChangeNotifier	;

	// Stores the current SWI operation

	TInt iSwiOperation;

	// Indicates whether a discovery due to language changes is pending

	TBool iLanguageChangeDiscoveryPending;

	// the current state of CDiscoverer

	TDiscovererState iState;

	class CIdleScanningTimer;

	// A single timer, processes all pending notifications.

	CIdleScanningTimer* iScanningTimer;

	class CDirScanner;

	/** 

		The internal Interface Implementation Collection 

		identifier and registration handler  

	 */

	CDirScanner* iDirScanner;

	/** A reference to the owning client of the CDiscoverer */

	MDiscovererObserver& iDiscovererObserver;

	/** A reference to the connected file server instance */

	RFs& iFs;

	/** The list of existing drives */

	RArray<TUint> iDrivesDiscovered;

	/** cached info of drives A to Z */

	CEComCachedDriveInfo* iCachedDriveInfo;

	TCallBackWithArg iSwiChangeCallBack;

	TCallBackWithArg iBurChangeCallBack;

	// List the internal classes as friends

	friend class CSwiChangeNotifier;

	friend class CDirChangeNotifier;

	friend class CIdleScanningTimer;

	friend class CDirScanner;

	// And the Test bed state accessor

	friend class TDiscoverer_StateAccessor;

};

// __________________________________________________________________________

//

/**

The notification object which uses P&S to monitor SWI KSAUidSoftwareInstallKey 

for changes. When SWI is present in the device/ROM this attribute publishes the

current state of a software install or uninstall.

When its RunL method is called and depending on the install/uninstall state it 

notifies its owning CDiscoverer class object to re-scan removable drives.

@internalComponent

*/