/*

* 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: 

* This file defines the SIF API.

*

*/

/**

 @file

 @publishedAll

 @released

*/

#ifndef SIF_H

#define SIF_H

#include <usif/sif/siftransportclient.h>

namespace Usif

	{

	/**

		The RSoftwareInstall class provides an asynchronous interface to the Software

		Install Framework. This class wraps all the details of client-server communication

		with the SIF server residing in a separate process. This API is asynchronous and

		therefore clients may issue concurrect requests. However, the SIF constrains

		concurrent operations by default. A client issuing an Install or Uninstall request

		may set the aExclusiveOperation flag to EFalse in order to allow for concurrent

		execution of his request. However, even if this flag is set to EFalse, a request

		may fail with KErrServerBusy if a corresponding underlying installer doesn't

		support concurrent operations.

		This class is intended to be used by SIF client applications, for example, application

		or device managers.

		Software @see TComponentId needed for the Uninstall/Activate/Deactivate APIs is a unique

		identifier of an installed component regardless of its type across the system.  When installing

		a package containing other embedded packages each embedded component gets its own @see

		TComponentId in the descending order. For example, we have a package P1 that contains an

		embedded package P2 that contains yet another embedded package P3.

		After installation the components may be identified by the following Ids:

		- Id of Component 1 (Package 1): 6 (example value)

		- Id of Component 2 (Package 2): 7

		- Id of Component 3 (Package 3): 8

		Component 3 with Id = 8 is the last installed/most embedded component and therefore its id

		is the highest.

		All the SIF operations may require special capabilities in order to complete successfully.

		This check may be implemented in a SIF plug-in. For example, a silent installation may require

		the TrustedUI capability. However, this is expected behavour that standard operations

		don't require any capabilities. Please see @see Usif::CSifPlugin description for further details

		if there are any deviations from this rule.

	 */

	class RSoftwareInstall

		{

	public:

		IMPORT_C RSoftwareInstall();

		/**

		   Connects a client to the SIF server.

		@return	Symbian OS error code where KErrNone indicates

				success and any other value indicates failure.

		*/

		IMPORT_C TInt Connect();

		/**

		   Disconnects a client from the SIF server.

		*/

		IMPORT_C void Close();

		/**

		Returns the details of a component to be installed by file name

		@param aFileName The file name of a component to be queried

		@param aComponentInfo On return, contains the details of a component

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		*/

		IMPORT_C void GetComponentInfo(const TDesC& aFileName, CComponentInfo& aComponentInfo,

										TRequestStatus& aStatus);

		/**

		 * Returns the details of a component to be installed by file handle

		@param aFileHandle The file handle of a component to be queried

		@param aComponentInfo On return, contains the details of a component

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		*/

		IMPORT_C void GetComponentInfo(RFile& aFileHandle, CComponentInfo& aComponentInfo,

										TRequestStatus& aStatus);

		/**

		Installs a component by file name

		@param aFileName The file name of a component to be installed

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Install

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Install(const TDesC& aFileName, TRequestStatus& aStatus,

							TBool aExclusiveOperation = ETrue);

		/**

		Installs a component by file name using opaque arguments/results

		@param aFileName The file name of a component to be installed

		@param aArguments The array of opaque params for a SIF plug-in. An empty

		array may be passed.  The following param is defined for the "SCOMO Install

		Inactive" operation:

		Name: InstallInactive, Type: Int, Value: ETrue

		@param aResults The array of opaque params returned from a SIF plug-in.

		The following return param is defined for the id of an installed component:

		Name: ComponentId, Type: Int

		For packages containing embedded components, the returned param contains

		the id of the last/most embedded component.

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Install

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Install(const TDesC& aFileName, const COpaqueNamedParams& aArguments,

								COpaqueNamedParams& aResults, TRequestStatus& aStatus,

								TBool aExclusiveOperation = ETrue);

		/**

		Installs a component by file handle

		@param aFileHandle The file handle of a component to be installed

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Install

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Install(RFile& aFileHandle, TRequestStatus& aStatus,

								TBool aExclusiveOperation = ETrue);

		/**

		Installs a component by file handle using opaque arguments/results

		@param aFileHandle The file handle of a component to be installed

		@param aArguments The array of opaque params for a SIF plug-in. An empty

		array may be passed.  The following param is defined for the "SCOMO Install

		Inactive" operation:

		Name: InstallInactive, Type: Int, Value: ETrue

		@param aResults The array of opaque params returned from a SIF plug-in.

		The following return param is defined for the id of an installed component:

		Name: ComponentId, Type: Int

		For packages containing embedded components, the returned param contains

		the id of the last/most embedded component.

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Install

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Install(RFile& aFileHandle, const COpaqueNamedParams& aArguments,

								COpaqueNamedParams& aResults, TRequestStatus& aStatus,

								TBool aExclusiveOperation = ETrue);

		/**

		Uninstalls a component

		@param aComponentId The id of a component to be uninstalled

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Uninstall

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Uninstall(TComponentId aComponentId, TRequestStatus& aStatus,

								TBool aExclusiveOperation = ETrue);

		/**

		Uninstalls a component

		@param aComponentId The id of a component to be uninstalled

		@param aArguments The array of opaque params for a SIF plug-in. An empty

		array may be passed.

		@param aResults The array of opaque results returned from a SIF plug-in.

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		@param aExclusiveOperation If this flag is set to ETrue, the Uninstall

		operation is executed in the Exclusive mode. In this mode the SIF

		Server executes only one operation at a time. If there is another

		operation in progress the SIF Server returns KErrServerBusy.

		If this flag is set to EFalse, the SIF Server executes the operation

		even if there is a concurrent operation in progress. The default value

		is ETrue.

		*/

		IMPORT_C void Uninstall(TComponentId aComponentId, const COpaqueNamedParams& aArguments,

								COpaqueNamedParams& aResults, TRequestStatus& aStatus,

								TBool aExclusiveOperation = ETrue);

		/**

		Activates a component.

  		The SCOMO state of a component can be changed at any time through the SIF API. However, capability

		checking may apply depending on the particular installer. For example, a Python installer may require the 

		ECapabilityWriteUserData capability to activate or deactivate a Python component.

		@param aComponentId The id of a component to be activated

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		*/

		IMPORT_C void Activate(TComponentId aComponentId, TRequestStatus& aStatus);

		/**

		Deactivates a component.

  		The SCOMO state of a component can be changed at any time through the SIF API. However, capability

		checking may apply depending on the particular installer. For example, a Python installer may require the 

		ECapabilityWriteUserData capability to activate or deactivate a Python component.

		@param aComponentId The id of a component to be deactivated

		@param aStatus The request status. KErrNone, if successful, otherwise

		one of the other system-wide or SIF error codes defined in usiferror.h.

		*/

		IMPORT_C void Deactivate(TComponentId aComponentId, TRequestStatus& aStatus);

		/**

		Cancels an ongoing asynchronous request

		This is a synchronous call. When it returns the original asynchronous call is completed.

		*/

		IMPORT_C void CancelOperation();

#ifdef _DEBUG

		friend class CSifOperationStep;

#endif //_DEBUG

	private:

		RSifTransportClient iTransport;

		};

	} // namespace Usif

#endif // SIF_H