/*

* Copyright (c) 2008-2009 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: 

* RSoftwareComponentRegistry provides interfaces allowing install, uninstall, and update 

* of software components .

* Software Components Registry interface is designed to be used by installers, application managers, device managers and the software install framework (SIF).

*

*/

/**

 @file

 @publishedAll

 @released

*/

#ifndef SOFTWARECOMPONENTREGISTRY_H

#define SOFTWARECOMPONENTREGISTRY_H

#include <e32base.h>

#include <usif/usifcommon.h>

#include <usif/scr/screntries.h>

#include <scs/scsclient.h>

namespace Usif

	{	 

#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

	class CScrLogEntry;

	class CLocalizedSoftwareTypeName;

#endif SYMBIAN_ENABLE_SPLIT_HEADERS

	NONSHARABLE_CLASS(RSoftwareComponentRegistry) : public RScsClientBase

	/*

		The clients of Software Component Registry (SCR) use this class to communicate 

		with the SCR server. 

		This class provides several sets of functionality:

		(i) Components' management, such as adding and removing components, registering files and other operations

		(ii) Transaction management, which allows rolling back or committing a set of mutating operations together.

		(iii) Read-only queries, such as getting component properties, or component information. 

		Operations which update or create new components in the SCR are restricted to the registered installers or layered execution

		environments (LEE). For example, only a Java installer or the Java Virtual Machine (JVM) can create new Java components. Additionally,

		only the same entities can change properties of or delete already existing Java components.

		Please note that mutating functions of this class can be used if any of the following conditions applies:

		- There is no active transaction or reading operation with component or file views.

		- A transaction exists and has been started by this connection.

		Additionally, please note that SCR limits the size of strings it receives in input to 512 characters, e.g. supplying component names, property names longer than that

		will result in KErrArgument.

	 */

		{

	public:

		/**

			Default constructor of SCR session.

		 */

		IMPORT_C RSoftwareComponentRegistry();

		/**

			Opens a connection to the SCR server.

			@return KErrNone, if the connection is successful. Otherwise, a system-wide error code.  

		 */

		IMPORT_C TInt Connect();

		/**

			Closes the connection with the SCR server.

		 */

		IMPORT_C void Close();

		/**

			The SCR allows its clients to perform all mutable operations related to a software component management operation

			(e.g. install, uninstall, upgrade, and replace) within a single transaction. If a software component management operation 

			fails or is aborted then the SCR will revert to a consistent state.  If mutating operations are not done under a transaction, 

			it will be impossible to roll them back automatically in conjunction with other operations.

			A transaction is started and persists throughout the connection until the next commit/rollback function call.

			The transaction automatically rolls back if the server connection is closed without commit/rollback functions 

			being invoked.  If the device unexpectedly shuts down while a transaction is in progress, the SCR server will 

			revert to consistent state on next usage. 

			Please note that nested/concurrent transactions are NOT supported. 

			N.B. It is impossible to start a transaction if at least one component or file view (e.g. RSoftwareComponentRegistryView and

			RSoftwareComponentRegistryFilesList) owned by another SCR session is in progress. 

			N.B. Transaction operations are permitted only to registered installers or execution environments.

			@leave KErrScrWriteOperationInProgress If a transaction is already in progress on the SCR server.

			@leave KErrScrReadOperationInProgress If one or more component views or file lists owned by other SCR sessions are open.

			@leave KErrPermissionDenied An unauthorised process attempted a transaction operation. 

			@leave Or system-wide error codes.

		 */

		IMPORT_C void CreateTransactionL();

		/**

			Rolls back the transaction started by this session by reverting all the changes made during the transaction. 

			N.B. Transaction operations are permitted only to registered installers or execution environments.			

			@leave KErrScrNoActiveTransaction There is no active transaction on the SCR Server started by this connection.

			@leave KErrPermissionDenied An unauthorised process attempted a transaction operation.

			@leave Or system-wide error codes.

		 */ 

		IMPORT_C void RollbackTransactionL();

		/**

			Commits the transaction started by this session.

			N.B. Transaction operations are permitted only to registered installers or execution environments.			

			@leave KErrScrNoActiveTransaction There is no active transaction on the SCR Server started by this connection.

			@leave KErrPermissionDenied An unauthorised process attempted a transaction operation.

			@leave Or system-wide error codes.

		 */

		IMPORT_C void CommitTransactionL();

		/**

			Adds a new software component entry to the SCR database.

			If the component and vendor names of the software component being installed are NOT localizable, 

			then this API should be used to add a new component.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aName The non-localizable name of the component being added.

			@param aVendor The non-localizable vendor name of the component being added.

			@param aUniqueSwTypeName The non-localized, unique software type name, such as @see Usif::KSoftwareTypeNative and @see Usif::KSoftwareTypeJava.

			@param aGlobalId A named, nullable, case-sensitive string used to specify a deterministic identifier for the component 

						that is unique within the context of that software type. The global component id might be 

						the package UID for native applications or the MIDlet name/vendor pair for Java MIDLets, etc. 

						Note that if KNullDesC is provided, the global identifier will be empty.

			@param aCompOpType The type of the component operation. Typical operations are install or upgrade. @see Usif::TScrComponentOperationType

			@return  The component ID of the newly added entry.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C TComponentId AddComponentL(const TDesC& aName, const TDesC& aVendor, const TDesC& aUniqueSwTypeName, const TDesC* aGlobalId=NULL, TScrComponentOperationType aCompOpType=EScrCompInstall);

		/**

			Adds a new software component entry to the SCR database.

			If the component and vendor names of the software component being installed are localizable,

			then this API should be used to add a new component.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentInfo The list of localizable component information (such as vendor and name) with one entry per each supported locale.

			@param aUniqueSwTypeName The non-localized, unique software type name, e.g. "Native".

			@param aGlobalId A named, nullable, case-sensitive string used to specify a deterministic identifier for the component 

							that is unique within the context of that software type. The global component id would be 

							the package UID for native applications or the midlet-names for Java, etc. 

							Note that if KNullDesC is provided, the global identifier will be empty.

			@param aCompOpType The type of the component operation. Typical operations are install or upgrade. @see Usif::TScrComponentOperationType

			@return  The component ID of the newly added entry. 

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C TComponentId AddComponentL(const RPointerArray<CLocalizableComponentInfo>& aComponentInfo, const TDesC& aUniqueSwTypeName, const TDesC* aGlobalId=NULL, TScrComponentOperationType aCompOpType=EScrCompInstall);

		/** 

			Adds a new dependency between two software components (supplier and dependant) of any type.

			For example, if VNC Viewer is ported to the Symbian OS using the POSIX library, VNC Viewer

			depends on the POSIX library. Here, VNC Viewer is dependant, whereas the POSIX library is supplier. 

			A dependency exists on global component ids, since a dependency is a global relation between 

			two components, regardless to their status on a particular system. While local component ids 

			(@see TComponentId) are private to a particular device and can change for the same global id 

			in the case of upgrades or reinstalls, global component ids are unique and equal for the same 

			component on any device.

			Since a dependency is defined using global ids, it can be added even if the participant

			components don't exist in the system. 

			N.B. A duplicate dependency is not allowed. 

			@param aSupplierVerCompId The versioned software component identifier of the supplier component. 

			@param aDependantGlobalCompId The global software component identifier of the dependant component.

			@leave KErrAlreadyExists If the dependency is already defined in the SCR.

			@leave Or other system-wide error codes.

		 */

		IMPORT_C void AddComponentDependencyL(const CVersionedComponentId& aSupplierVerCompId, const CGlobalComponentId& aDependantGlobalCompId);

		/**

			Adds a new named 8-bit descriptor property to the registry for a given software component and locale. 

			If the property already exits, then its value is updated.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aName The name of the software component property.

			@param aValue The value of the software component property.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes. 

		 */

		IMPORT_C void SetComponentPropertyL(TComponentId aComponentId, const TDesC& aName, const TDesC8& aValue);		

		/**

			Adds a new named localizable 16-bit string property to the registry for a given software component and locale. 

			If the property already exists, then its value is updated.

			N.B. If the property exists with the same value but for a different locale, it is NOT replaced, but instead added for the new locale.

			N.B. This API should not be used for raw binary data. For binary data, the TDesC8 variant of SetComponentProperty should be used instead.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aName The name of the software component property.

			@param aValue The value of the software component property.

			@param aLocale The language code of the property. The default value is non-localized property.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes. 

		 */

		IMPORT_C void SetComponentPropertyL(TComponentId aComponentId, const TDesC& aName, const TDesC& aValue, TLanguage aLocale=KNonLocalized);

		/**

			Adds a new named numeric property to the registry for a given software component. If the property already

			exits, then its value is updated. Signed values from -2^63+1 to +2^63-1 are supported. 

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aName The name of the software component property.

			@param aValue The value of the software component property. Can be TInt; if the value cannot exceed 32-bit range, as TInt64 provides automatic casting from TInt.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

	     */

		IMPORT_C void SetComponentPropertyL(TComponentId aComponentId, const TDesC& aName, TInt64 aValue);

		/**

			Registers a file to a given software component.

			Before registration, tests whether the provided filename is syntactically correct. 

			For more information about the syntax, check @see RFs::IsValidName.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aFileName The fully qualified name of the file being registered.

			@param aConsiderForInstalledDrives This parameter specifies whether the list of installed drives ( @see CComponentEntry::InstalledDrives) should be maintained as a result of this operation. 

			In most cases, this should be left at the default setting, unless a file is registered for uninstall purposes only and is not actually present on the system, for example a possible temporary file which might be created later by the component's application(s)

			Please note that if UnregisterComponentFileL is later used on the component, this parameter will not apply, and the file registration may still affect the list of installed drives.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave KErrArgument If the file name is invalid or is not fully qualified

			@leave Or system-wide error codes.

		 */	

		IMPORT_C void RegisterComponentFileL(TComponentId aComponentId, const TDesC& aFileName, TBool aConsiderForInstalledDrives = ETrue); 

		/**

			Adds a new named 8-bit descriptor property to the registry for a given file and software component. If the property already

			exits, then its value is updated.

			A file property allows adding custom information about a component’s file ownership, for example, a native installer 

			may associate custom operations to be done on uninstall for a particular file.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aFileName  The fully qualified name of the file.

			@param aPropName  The name of the file property being added.

			@param aPropValue The value of the file property being set.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		*/

		IMPORT_C void SetFilePropertyL(TComponentId aComponentId, const TDesC& aFileName, const TDesC& aPropName, const TDesC8& aPropValue);

		/**

			Adds a new named numeric property to the registry for a given file and software component. 

			If the property already exists, it is just updated.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.	 	

			@param aFileName  The fully qualified name of the file.

			@param aPropName  The name of the file property being added.

			@param aPropValue The value of the file property being added.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C void SetFilePropertyL(TComponentId aComponentId, const TDesC& aFileName, const TDesC& aPropName, TInt aPropValue);

		/**

			Adds a new localized component name for a given software component. 

			If the localized name already exists for the specified locale, or one of the locales in its downgrade path (@see BaflUtils::GetDowngradePathL),

			then it is updated. 

			If no locale is specified, then the default component name is updated (or added if no default name exists).

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aName The new value of the component name for a given locale.

			@param aLocale The language code of the requested locale. The default value is non-localized.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		*/

		IMPORT_C void SetComponentNameL(TComponentId aComponentId, const TDesC& aName, TLanguage aLocale=KNonLocalized);

		/**

			Adds a new localized component vendor for a given software component. 

			If the localized vendor name already exists for the specified locale, or one of the locales in its downgrade path (@see BaflUtils::GetDowngradePathL),

			then it is updated. 

			If no locale is specified, then the default vendor name is updated (or added if no default vendor name exists).

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aVendor The new value of the vendor name for a given locale.

			@param aLocale The language code of the requested locale. The default value is non-localized.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

	    */

		IMPORT_C void SetVendorNameL(TComponentId aComponentId, const TDesC& aVendor, TLanguage aLocale=KNonLocalized);

		/**

			Updates the version of a given software component.

			N.B. The default value of component version is NULL.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aVersion The new value of the version attribute.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C void SetComponentVersionL(TComponentId aComponentId, const TDesC& aVersion);

		/**

			Sets whether the component is removable.

			When a component is added, this is set to True by default (i.e. all non-ROM components are removable unless stated otherwise).

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aValue ETrue to set component as removable. EFalse to set component as unremovable.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

			@capability AllFiles Creating non-removable components requires AllFiles.

		 */

		IMPORT_C void SetIsComponentRemovableL(TComponentId aComponentId, TBool aValue);

		/**

			Sets whether the component is DRM protected.

			When a component is added, this is set to False by default (i.e. all components are non-DRM protected unless stated otherwise).

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aValue ETrue to set component as DRM protected. EFalse to set component as non-DRM protected.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

			@capability WriteDeviceData Creating DRM protected components requires WriteDeviceData.

		 */

		IMPORT_C void SetIsComponentDrmProtectedL(TComponentId aComponentId, TBool aValue);

		/**

			Sets the hidden attribute of a component indicating that the component shouldn't be displayed in the list of installed components.

			When a component is added, this is set to False by default (i.e. all components are visible unless stated otherwise).

			N.B. SCR does not enforce usage of this flag, and application managers may ignore it, e.g. in an admin view.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aValue ETrue to set component as hidden. EFalse to set component as non-hidden.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

			@capability WriteDeviceData Creating hidden components requires WriteDeviceData.

		 */

		IMPORT_C void SetIsComponentHiddenL(TComponentId aComponentId, TBool aValue);

		/**

			Sets the Known-Revoked attribute of a component. If this attribute is true, then it indicates 

			a revocation check was performed during or after the installation and the component

			was found to be revoked. When a component is added, this is set to False by default.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aValue ETrue to set component as known-revoked. EFalse to set component as known-unrevoked.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

			@capability WriteDeviceData Creating known-revoked components requires WriteDeviceData.

		 */

		IMPORT_C void SetIsComponentKnownRevokedL(TComponentId aComponentId, TBool aValue);

		/**

			Sets the Origin-Verified attribute of a component. If this attribute is true, then it indicates that 

			the installer has verified the originator of the software component by using appropriate checking mechanisms (e.g. certificates). 

			If the attribute is false, it means that such a verification has not been performed, or that the installer does not support origin verification. 

			When a component is added, this is set to False by default.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aValue ETrue to set component as origin-verified EFalse to set component as origin-non-verified.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

			@capability WriteDeviceData Creating origin verified components requires WriteDeviceData.

		 */

		IMPORT_C void SetIsComponentOriginVerifiedL(TComponentId aComponentId, TBool aValue);

		/**

			Sets the total size in bytes of the files owned by a given component. Note that SCR doesn't maintain this value.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aComponentSizeInBytes The size of the component's files in bytes.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C void SetComponentSizeL(TComponentId aComponentId, TInt64 aComponentSizeInBytes);

		/**

			Deletes a specific property entry of a given software component.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			N.B. If the component or property doesn't exist, the function completes successfully.

			N.B. If the property is specified for multiple locales, it is deleted for all of them.

			@param aComponentId The unique ID of the given software component.

			@param aPropName The name of the component property being deleted.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

	     */

		IMPORT_C void DeleteComponentPropertyL(TComponentId aComponentId, const TDesC& aPropName);

		/** 

			Deletes a specific file property entry for a given file and software component.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			@param aComponentId The unique ID of the given software component.

			@param aFileName The fully qualified name of the file.

			@param aPropName The name of the file property being deleted.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		 */

		IMPORT_C void DeleteFilePropertyL(TComponentId aComponentId, const TDesC& aFileName, const TDesC& aPropName);

		/**

			Unregisters a specific file entry from a given software component.

			Note that all associated file properties for the same component are removed as well.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			N.B. This operation also deletes all the corresponding file properties.

			@param aComponentId The unique ID of the given software component.

			@param aFileName The fully qualified name of the file being deregistered.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

	     */

		IMPORT_C void UnregisterComponentFileL(TComponentId aComponentId, const TDesC& aFileName);

		/**

			Deletes a sofware component entry and all its data from the registry, including properties and file registration records.

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.

			N.B. If the component doesn't exist, the function completes successfully.

			@param aComponentId The unique ID of the given software component.

			@leave KErrScrWriteOperationInProgress If a transaction started by another session is in progress.

			@leave KErrScrReadOperationInProgress If a read operation with component or file views is in progress.

			@leave Or system-wide error codes.

		*/

		IMPORT_C void DeleteComponentL(TComponentId aComponentId);

		/** 

			Deletes an existing dependency between two software components (supplier and dependant) of any type.

			(@see RSoftwareComponentRegistry::AddComponentDependencyL for more information about component dependency.)

			N.B. This is a mutating function. Please see @see Usif::RSoftwareComponentRegistry.