/*
* Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "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:       Defines Runtime security manager's core class. Defines
 * 				  APIs for runtime bindings and clients to access security
 * 				  management functionalities
 *
*/






#ifndef _CRTSECMANAGER_H
#define _CRTSECMANAGER_H

#include <e32base.h>

#include <rtsecmgrcommondef.h>
#include <rtsecmgrtrustinfo.h>

class CRTSecMgrScriptSession;
class MSecMgrPromptHandler;
class CRTSecMgrClientProxy;
class CTrustInfo;
class CPermission;

/**
 * Core class of the runtime recurity manager component.
 * 
 * Runtime security manager broadly offers 
 *
 *  - Policy management functions
 *	- Script management functions
 *  - Access permission check
 *
 * CRTSecManager offers methods to perform policy management functionalities
 * such as 
 * 	- Registering runtime security access policy
 * 	- Updating the registered security access policy
 * 	- Un-registering the registered security access policy 
 * 
 * Similarly, CRTSecManager offers methods for script management such as
 * 	- Registering a runtime script with security manager
 * 	- Un-registering the registered script
 * 	- Obtaining scipt session associated with the registered script
 * 
 * The main functionality of CRTSecManager is to perform access permission
 * check using script session functions
 * 
 * @lib rtsecmgrclient.lib
 */
NONSHARABLE_CLASS(CRTSecManager) : public CBase
	{
public:

	/**
	 * Two-phased constructor
	 * 
	 * Constructs a CRTSecManager instance
	 *
	 * Initializes client side security manager session. Starts the security
	 * manager server, if it is not already running.
	 * 
	 * @return pointer to an instance of CRTSecManager
	 */
	IMPORT_C static CRTSecManager* NewL();

	/**
	 * Two-phased constructor
	 * 
	 * Constructs a CRTSecManager instance and leaves the created instance
	 * onto the cleanupstack.
	 *
	 * Initializes client side security manager session. Starts the security
	 * manager server, if it is not already running.
	 * 
	 * @return pointer to an instance of CRTSecManager
	 */
	IMPORT_C static CRTSecManager* NewLC();

	/**
	 * Destructor
	 * 
	 * Closes client side security manager session
	 */
	IMPORT_C ~CRTSecManager();

	/**
	 * Registers a runtime security policy. Runtimes should call this function
	 * to register their security access and trust policies.
	 *
	 * @param aSecPolicy RFile Handle to security policy file
	 *
	 * @return TPolicyID generated policy identifier if successul; Otherwise one of
	 *					 system wide error codes
	 *
	 * \note
	 * Clients should call ShareProtected on the file session object as shown below.
	 * 
	 * @code	 * 
	 * 	RFs fileSession;
	 * 	fileSession.Connect();
	 * 	fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy
	 * 
	 * 	RFile secPolicyFile;
	 * 	secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );
	 * 	TPolicyID policyID = secMgr->SetPolicy(secPolicyFile);
	 *
	 *  if(policyID <= KErrNone)
	 *  {
	 *		//error..
	 *	}
	 * 
	 * @endcode
	 * 
	 */
	IMPORT_C TPolicyID SetPolicy(const RFile& aSecPolicy);
	
	/**
	 * Registers a runtime security policy. Runtimes should call this function
	 * to register their security access and trust policies.
	 *
	 * @param aPolicyBuffer const TDesC& security policy file buffer
	 *
	 * @return TPolicyID generated policy identifier if successul; Otherwise one of
	 *					 system wide error codes
	 *
	 * \note
	 * Clients should call ShareProtected on the file session object as shown below.
	 * 
	 * @code	 * 
	 * 	RFs fileSession;
	 * 	fileSession.Connect();
	 * 	fileSession.ShareProtected(); //Mandatorily call before invoking SetPolicy
	 * 
	 * 	RFile secPolicyFile;
	 * 	secPolicyFile.Open(fileSession, _L("AccessPolicy.xml"), EFileShareAny );	 
	 *  HBufC8* fileBuffer = HBufC8::NewL(KFileBufferMaxLen);
	 *  secPolicyFile.Read(*fileBuffer);
	 *   
	 * 	TPolicyID policyID = secMgr->SetPolicy(*fileBuffer);
	 *
	 *  if(policyID <= KErrNone)
	 *  {
	 *		//error..
	 *	}
	 * 
	 * @endcode
	 * 
	 */
	IMPORT_C TPolicyID SetPolicy(const TDesC8& aPolicyBuffer);

	/**
	 * UnRegisters a registered security policy. Runtimes should call this function
	 * to de-register the already registered security policy.
	 *
	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
	 *
	 * @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone
	 *    
	 */
	IMPORT_C TInt UnSetPolicy(TPolicyID aPolicyID);

	/**
	 * Updates an already registered security policy. Runtimes should call this function
	 * to update their policy.
	 *
	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
	 * @param aSecPolicy RFile Handle to security policy file
	 *
	 * @see SetPolicy for file session pre-conditions
	 *
	 * @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID
	 *
	 */
	IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const RFile& aSecPolicy);

	/**
	 * Updates an already registered security policy. Runtimes should call this function
	 * to update their policy.
	 *
	 * @param aPolicyID TPolicyID Policy identifier previously generated with SetPolicy
	 * @param aPolicyBuffer const TDesC& security policy file buffer
	 *
	 * @see SetPolicy for file session pre-conditions
	 *
	 * @return TPolicyID One of sytem wide error codes in case of failure; Otherwise the passed policyID
	 *
	 */
	IMPORT_C TPolicyID UpdatePolicy(TPolicyID aPolicyID,const TDesC8& aPolicyBuffer);
	
	/**
	 * Registers a script/executable. Runtimes should specify the trust information
	 * of the script to be registered. 
	 *
	 * @param aPolicyID TPolicyID   Runtime's registered policy identifier
	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
	 *
	 * @return TExecutableID generated executable identifier if successul; Otherwise one of
	 *					 	 system wide error codes
	 *
	 */
	IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo);

	/**
	 * Registers a script/executable. Runtimes should specify the trust information
	 * of the script to be registered. 
	 *
	 * @param aPolicyID TPolicyID   Runtime's registered policy identifier
	 * @param aHashMarker const TDesC& Hash value to identify script when starting script session
	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
	 *
	 * @return TExecutableID generated executable identifier if successul; Otherwise one of
	 *					 	 system wide error codes
	 *
	 */
	IMPORT_C TExecutableID RegisterScript(TPolicyID aPolicyID, const TDesC& aHashMarker, const CTrustInfo& aTrustInfo);

	/**
	 * De-Registers a script/executable. Runtimes should pass the previously registered
	 * script identifier corresponding to the script to be de-registered.
	 *
	 * @param aExeID TExecutableID   A valid script identifier
	 *
	 * @return TInt One of sytem wide error codes in case of failure; Otherwise KErrNone
	 *     
	 */
	IMPORT_C TInt UnRegisterScript(TExecutableID aExeID, TPolicyID aPolicyID);

	/**
	 * Creates a script session instance. CRTSecMgrScriptSession performs access permission
	 * check for native platform service invocation. A CRTSecMgrScriptSession instance needs to
	 * be created for every instance of scripts which could potentially invoke platform service.
	 *
	 * @param aPolicyID TPolicyID    Valid registered policy identifier
	 * @param aExeID TExecutableID   Script identifier, KAnonymousScript in case of anonymous script session
	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
	 *							     will supply a default prompt handler
	 *
	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;
	 * Otherwise NULL
	 */
	IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, TExecutableID aExecID, MSecMgrPromptHandler* aPromptHdlr=NULL , const TDesC& aHashValue = KNullDesC);

	/**
	 * Creates a script session instance for an unregisterd trusted script. CRTSecMgrScriptSession performs access permission
	 * check for native platform service invocation. 
	 *
	 * @param aPolicyID TPolicyID    Valid registered policy identifier
	 * @param aTrustInfo CTrustInfo a valid instance of CTrustInfo object
	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
	 *							     will supply a default prompt handler
	 *
	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession;
	 * 								  NULL in case of invalid policy identifier
	 *           
	 *     
	 */
	IMPORT_C CRTSecMgrScriptSession* GetScriptSessionL(TPolicyID aPolicyID, const CTrustInfo& aTrustInfo, MSecMgrPromptHandler* aPromptHdlr=NULL);

	/**
	 * Creates a script session instance. CRTSecMgrScriptSession performs access permission
	 * check for native platform service invocation. A CRTSecMgrScriptSession instance needs to
	 * be created for every instance of scripts which could potentially invoke platform service.
	 *
	 * @param aPolicyID TPolicyID    Valid registered policy identifier
	 * @param aExeID TExecutableID   Script identifier, KAnonymousScript in case of anonymous script session
	 * @param aHashValue TDesC		 hash value passed while registering the script
	 * @param aPromptHdlr MSecMgrPromptHandler An optional prompt handler. If not provided, Security manager
	 *							     will supply a default prompt handler
	 *
	 * @return CRTSecMgrScriptSession* A pointer to the created instance of CRTSecMgrScriptSession if the executableID is valid;
	 * Otherwise NULL
	 
	IMPORT_C CRTSecMgrScriptSession* GetScriptSession(TPolicyID aPolicyID, TExecutableID aExecID, const TDesC& aHashValue, MSecMgrPromptHandler* aPromptHdlr=NULL);*/
private:
	//Private default constructor
	CRTSecManager();

	//Part of second-phase constructor
	void ConstructL();

private:
	//Proxy to client side session object
	CRTSecMgrClientProxy* iClientProxy;
	};
#endif //_CRTSECMANAGER_H