/**

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

* Declaration of Types and Constants for Secure Backup and Restore

* 

*

*/

/**

 @file

*/

#ifndef __SBTYPES_H__

#define __SBTYPES_H__

#include <connect/sbdefs.h>

#include <e32cmn.h>

#include <f32file.h>

#include <connect/sbexternalisablearray.h>

class RApaLsSession;

namespace conn

	{

	/** Maximum length of package name

	@released

	@publishedPartner

	*/

	const TInt KMaxPackageNameLength = 128; // Arbitrary name length

	/** Length of the 128 bit Java hash in bytes

	@released

	@publishedPartner

	*/

	const TInt KJavaIdLength = 16;

	/** Used for unpacking unicode descriptors 

	@released

	@publishedPartner

	*/

	#ifdef UNICODE

	const TInt KCharWidthInBytes = 2;

	#else

	const TInt KCharWidthInBytes = 1;

	#endif // UNICODE

	/**

	@released

	@publishedPartner

	*/

	typedef TBufC<KMaxPackageNameLength> TPackageName;

	enum TCommonBUROptions

		/** 

		The passive backup options

		@released

		@publishedPartner

		*/

		{

		ENoOptions 				= 0x00000000, /*!< 0x00000000: no common options selected */

		EActiveBUR				= 0x00000001, /*!< 0x00000001: Does the data owner do active backup / restore? */

		EPassiveBUR				= 0x00000002, /*!< 0x00000002: Does the data owner do passive backup / restore? */

		EHasSystemFiles 		= 0x00000004, /*!< 0x00000004: Does the data owner want system files backed up? */

		ESupportsSelective		= 0x00000008, /*!< 0x00000008: Can the data owner do BUR selectively? */

		ERequiresReboot			= 0x00000010  /*!< 0x00000010: Does the data owner require reboot after restore? */

		};

	enum TPassiveBUROptions

		/** 

		The passive backup options

		@released

		@publishedPartner

		*/

		{

		ENoPassiveOptions 		= 0x00000000, /*!< 0x00000000: no passive options selected */

		EHasPublicFiles			= 0x00000001, /*!< 0x00000001: data owner has public files to BUR ? */

		EDeleteBeforeRestore	= 0x00000002, /*!< 0x00000002: data owner requires a delete before restore ? */

		EPassiveSupportsInc 	= 0x00000004  /*!< 0x00000004: data owner supports incremental BUR ? */

		};

	enum TActiveBUROptions

		/** 

		The active backup options

		@released

		@publishedPartner

		*/

		{

		ENoActiveOptions 		= 0x00000000, /*!< 0x00000000: no active backup options selected */

		EDelayToPrepareData 	= 0x00000001, /*!< 0x00000001: data owner slow to prepare active data */

		EActiveSupportsInc		= 0x00000002  /*!< 0x00000002: data owner supports incremental BUR ? */

		};

	/**	Common BUR Settings

	This structure will store the common backup and restore options for a SID 

	@released

	@publishedPartner	

	*/

	typedef TUint32 TCommonBURSettings;

	/**	Passive BUR Settings

	This structure will store the passive backup and restore options for a SID 

	@released

	@publishedPartner	

	*/	

	typedef TUint32 TPassiveBURSettings;

	/**	Active BUR Settings

	This structure will store the active backup and restore options for a SID 

	@released

	@publishedPartner	

	*/

	typedef TUint32 TActiveBURSettings;

	class TRestoreFileFilter

		/**

		TRestoreFileFilter packages up a file or directory name and an include or exclude flag.

		This type is used when telling a client during a restore operation which public files are

		to be restored for a specific data owner.

		@released

		@publishedPartner

		*/

		{

	public:

		/**

		Constructor

		@param aInclude ETrue if the file or directory is to be

						included, EFalse for exclusion

		@param aName The name of the file or directory (directory

					 names end with a slash)

		*/

		TRestoreFileFilter(TBool aInclude, const TFileName& aName)

			: iInclude(aInclude), iName(aName) {}

	public:

		TBool iInclude ; /*!< ETrue if the file or directory is to be included, EFalse for exclusion */

		TFileName iName; /*!< The name of the file or directory (directory names end with a slash) */

		};

	/** Array of TEntry objects

	@released

	@publishedPartner

	*/

	typedef RExternalisableArray<TEntry> RFileArray;

	/** Array of TRestoreFileFilter objects 

	@released

	@publishedPartner

	*/

	typedef RExternalisableArray<TRestoreFileFilter> RRestoreFileFilterArray;

	/** Array of TSecureId objects

	@released

	@publishedPartner

	*/

	typedef RExternalisableArray<TSecureId> RSIDArray;

	enum TDataOwnerStatus

		/**

		TDataOwnerStatus encapsulates the status of a data owner.

		@released

		@publishedPartner

		*/

		{

		EUnset = 0, /*!< 0x00000000: Unset - allows creation of object without incorrect status */

		EDataOwnerNotFound = 1, /*!< 0x00000001: Data owner not found in registration files */

		EDataOwnerReady = 2, /*!< 0x00000002: Data owner ready for backup / restore */

		EDataOwnerNotReady = 3, /*!< 0x00000003: Data owner not yet ready for backup / restore */

		EDataOwnerFailed = 4, /*!< 0x00000004: Data owner failed to become ready */

		EDataOwnerNotConnected = 5, /*!< 0x00000005: Data owner alive, but not fully ready */

		EDataOwnerReadyNoImpl = 6 /*!< 0x00000006: Data owner ready for backup / restore but does not provide callback implementation */

		};

	class TDataOwnerAndStatus

		/**

		TDataOwnerAndStatus encapsulates the identity and status of a data owner.

		Access to members is direct.

		@released

		@publishedPartner

		*/

		{

	public:

		/**

		Constructor

		@param aSID Data owner secure id - identifies the data owner

		@param aStatus Status of the data owner

		@param aDataOwnerError Error code if data owner failed to be ready

							   or KErrNone

		*/

		TDataOwnerAndStatus(TSecureId aSID, TDataOwnerStatus aStatus, TInt aDataOwnerError)

			: iSID(aSID), iStatus(aStatus), iDataOwnerError(aDataOwnerError) {}

	public:

		TSecureId iSID; /*!< Data owner secure id - identifies the data owner */

		TDataOwnerStatus iStatus; /*!< Status of the data owner */

		TInt iDataOwnerError; /*!< Error code if data owner failed to be ready or KErrNone */

		};

	/** Array of data owners with their status

	@released

	@publishedPartner

	*/

	typedef RExternalisableArray<TDataOwnerAndStatus> RSIDStatusArray;

	enum TBackupDataType

		/**

		TBackupDataType indicates whether a specific data stream or operation relates to active or

		passive backup or restore.  A specific data owner can use both active and passive and so we

		need to differentiate between operations.

		@released

		@publishedPartner

		*/

		{

		EActive = 0, /*!< 0x00000000: The backup or restore operation is active rather than passive */

		EPassive = 1 /*!< 0x00000001: The backup or restore operation is passive rather than active */

		};

	enum TTransferDataType

		/**

		TTransferDataType indicates the type of data being transferred from the Secure Backup

		Engine to the Secure Backup Server or vice versa.

		@released

		@publishedPartner

		*/

		{

		ERegistrationData = 0, /*!< 0x00000000: deprecated */

		EPassiveSnapshotData = 1, /*!< 0x00000001: The data is a snapshot for passive backup that includes file details*/

		EPassiveBaseData = 2, /*!< 0x00000002: The data is passively backup up private data with no previous history */

		EPassiveIncrementalData = 3, /*!< 0x00000003: The data is passively backed up private data as an increment on a previous base backup */

		EActiveSnapshotData = 4, /*!< 0x00000004: The data is a snapshot for active backup that includes file details*/

		EActiveBaseData = 5, /*!< 0x00000005: The data is actively backup up private data with no previous history */

		EActiveIncrementalData = 6, /*!< 0x00000006: The data is actively backed up private data as an increment on a previous base backup */

		ECentralRepositoryData = 7, /*!< 0x00000007: deprecated */

		EPublicFileListing = 8, /*!< 0x00000008: An externalised list of public file entries belonging to a single data owner */

		};

	enum TSBDerivedType

		/**

		Used to identify the derived type that the base generic type represents

		@deprecated

		@publishedPartner

		*/

		{

		ESIDDerivedType = 0, /*!< 0x00000000: SID derived type  */

		EPackageDerivedType = 1, /*!< 0x00000001: Package derived type */

		ESIDTransferDerivedType = 2, /*!< 0x00000002: SID data transfer derived type  */

		EPackageTransferDerivedType = 3, /*!< 0x00000003: Package data transfer derived type */

		EJavaDerivedType = 4, /*!< 0x00000004: Java ID derived type */

		EJavaTransferDerivedType = 5, /*!< 0x00000005: Java ID derived type */

		};

		/**

		Maximum number of derived types specified in TSBDerivedType

		@released

		@publishedPartner

		*/

	const TUint KMaxDerivedTypes = 6;	

	enum TPackageDataType

		/**

		TPackageDataType indicates the type of package data being

		transferred from the Secure Backup Engine to the Secure Backup

		Server or vice versa.

		@deprecated

		@publishedPartner

		*/

		{

		ESystemData = 0, /*!< 0x00000000: The data is system files (typically executables or resource files) */

		ESystemSnapshotData = 1, /*!< 0x00000001: The data is a snapshot for system files */

		};

	enum TJavaTransferType

		/**

		This enum defines the type of Java data that is being transferred and can indicate either a MIDlet 

		suite archive (Jad/Jar etc.) or data for an installed MIDlet suite

		@released

		@publishedPartner

		*/

		{

		EJavaMIDlet = 0,

		EJavaMIDletData = 1,

		};

	enum TTransferDirection

		/**

		TTransferDirection indicates whether a (just completed) data transfer is from the

		Secure Backup Server to a data owner or vice versa.

		@released

		@publishedPartner

		*/

		{

		EServerToDataOwner = 0, /*!< 0x00000000: The transfer is from the Secure Backup Server to a data owner */

		EDataOwnerToServer = 1/*!< 0x00000001: The transfer is from a data owner to the Secure Backup Server */

		};

	/** Generic Data Type is a class for representing any type of data owner so that it 

	may be passed through a common interface

	<H2>Introduction</H2>

	The CSBEClient Secure backup interface class is designed to perform backup operations 

	on many different types of data owners. This presents a problem in that the interfaces 

	sometimes require arguments that are specific to the data type in question. In addition, 

	we can't predict the new data types that may appear in future, therefore a "generic" data 

	type was proposed that could be passed through interfaces as a base class and contained 

	enough information to enable Runtime Type Identification (RTTI) to be performed.

	This approach means that only one interface needs to be maintained for each backup 

	operation whilst still allowing the Secure Backup Engine to determine which type was 

	originally sent by a PC client.

	As well as acting as an identifier for different Data Owner's (DO's), it was decided 

	to extend the usage of the class to identify Data Owner's Data as each DO may require 

	specific information to identify data being transferred (such as finished flags etc.)

	The identifier is transparent to the user of CSBEClient, meaning that it can be 

	extracted directly from the message sent by the PC into a generic type and passed through 

	to the SBEngine without being instantiated as a derived class.

	<H2>Usage</H2>

	The general usage of the generic data type is to extract it from a PC sent message as a 

	CSBGenericDataType object using CSBGenericDataType::NewL(const TDesC8& aDes).

	There are a few conventions that have been followed within the Secure Backup component 

	that a developer must bear in mind:

	@li Ownership of the CSBGenericDataType, CSBGenericTransferType or derived 

		object is generally passed between interfaces and as such it is the resposibility 

		of the receiving function to delete it. Unless otherwise stated in the documentation

		for an interface, this is assumed to be the case;

	@li When a CSBGenericDataType or CSBGenericTransferType is to be converted into 

		a derived type, it must be passed in as a parameter to the constructor of the derived 

		type. It must not be downcasted as it may never have been a derived type, and the 

		derived types contain extra member data;

	In order to convert a base type to a derived type, a method CSBGenericDataType::DerivedTypeL() 

	that returns a conn::TSBDerivedType can be called to query the base object for it's derived type.

	A typical mechanism would be to use a switch statement, switching on the return value of 

	DerivedTypeL() and taking appropriate action with regards to creating a derived object.

	<H2>Internal Operation</H2>

	<H3>Initialisation</H3>

	CSBGenericDataType is underneath basically a descriptor buffer. All accessor functions 

	simply extract and pack values from this descriptor. This means that the type can be 

	safely transferred via IPC between processes and safely transferred between a device 

	and a PC independently of communications bearer or transport.

	The base class CSBGenericDataType has ownership of the data buffer, iDataBuffer, used 

	to store the member data in and in order to keep the derived classes atomic, a running 

	total size variable is updated by the C++ constructors of each class in the inheritence 

	chain. Because of Symbian's static NewL idiom, all C++ constructors are executed before 

	CSBGenericDataType::ConstructL() is called to instantiate the buffer, hence the size 

	can be guaranteed to be big enough to hold all of the derived type's data.

	In order to ensure that the derived types know whereabouts in the descriptor to extract 

	and pack values, an initialisation routine, InitialiseL(TInt& aOffset), is implemented 

	by each class. Each class is responsible for calling it's parents InitialiseL(), before 

	initialising itself and passing in an offset. The job of the initialisation method is 

	to walk the descriptor, storing the offset's of it's member data. The offset is a 

	reference and is hence updated so that the child class begins unpacking after the parents 

	data ends. In this way, each class is atomic apart from having to explicitly scope it's 

	parent's InitialiseL() method.

	<H3>Accessing Data</H3>

	Data is accessed by the use of packing and unpacking bytes directly from the descriptor 

	using the UnpackType, PackType and associated function templates. These will be unpacked 

	in the endianness of the system and therefore the PC will have to ensure that this 

	is taken into account when packing the type into the message.

	Although this method suffers in terms of performance, for the reasons of platform 

	independence, this is the most reliable method of packing/unpacking.

	<H2>Byte Structure</H2>

	All child classes have their data following on from the parent classes so that the parent 

	classes may remain atomic with respect to the structure of their data. The binary structure 

	of this data type inside the descriptor buffer is as follows. Note that the endianness of 

	the data types specified below is determined by the platform and the PC must pack accordingly:

	<table border="1">

		<tr>

			<td>TSBDerivedType [4-bytes]</td>

		</tr>

	</table>

	@deprecated

	@publishedPartner

	*/

	class CSBGenericDataType : public CBase

		{

	public:

		IMPORT_C static CSBGenericDataType* NewL(const TDesC8& aDes);

		IMPORT_C ~CSBGenericDataType();

		IMPORT_C const TDesC8& Externalise() const;

		IMPORT_C TSBDerivedType DerivedTypeL() const;

	protected:

		CSBGenericDataType();

		void ConstructL(const TDesC8& aDes);

		void BaseConstructL();

		virtual void InitialiseL(TInt& aOffset);

		void UnpackDescriptorTypeAdvance(TDesC16& aDes, TInt& aOffset);

		void UnpackDescriptorTypeAdvance(TDesC8& aDes, TInt& aOffset);

		void UnpackTPtrAdvance(TPtrC16& aDes, TInt& aOffset);

		void UnpackTPtrAdvance(TPtrC8& aDes, TInt& aOffset);

		void PackDescriptorTypeAdvance(const TDesC16& aDes, TInt& aOffset);

		void PackDescriptorTypeAdvance(const TDesC8& aDes, TInt& aOffset);

	protected:

		/** the data buffer */

		HBufC8* iDataBuffer;

		/** Cumulative size of the derived type. All ctors in the inheritence tree increment 

		with their size */

		TInt iSize;

		/** the derived type */

		TInt iDerivedTypeOffset;

		};

	template<class T> inline void UnpackType(T& aType, TDesC8& aDes, TInt aOffset)

		/**

		Templated function to copy a simple type from a specified position in aDes

		defined by aOffset. aOffset is not updated on return.

		@param aType This pointer is set with the pointer to the type in aDes

		@param aDes The buffer that contains the type T pointed to by aPtr

		@param aOffset The running index of where the following type begins. Updated by ExtractPointer

		*/

		{

		// Set the position at which to finish copying

		TInt endOffset = aOffset + sizeof(T);

		TUint8* pRawType = reinterpret_cast<TUint8*>(&aType);

		TUint8* pRawSource = const_cast<TUint8*>(aDes.Ptr()) + aOffset;

		for (TInt offset = aOffset; offset < endOffset; offset++)

			{

			*pRawType++ = *pRawSource++;

			}

		}

	template<class T> inline void UnpackTypeAdvance(T& aType, TDesC8& aDes, TInt& aOffset)

		/**

		Templated function to copy a simple type from a specified position in aDes

		defined by aOffset. aOffset is advanced so that on return, the new 

		offset is stored enabling the next call to UnpackType() to point at the position 

		following this type.

		@param aType This pointer is set with the pointer to the type in aDes

		@param aDes The buffer that contains the type T pointed to by aPtr

		@param aOffset The running index of where the following type begins. Updated by ExtractPointer

		*/

		{

		// Set the position at which to finish copying

		TInt endOffset = aOffset + sizeof(T);

		TUint8* pRawType = reinterpret_cast<TUint8*>(&aType);

		TUint8* pRawSource = const_cast<TUint8*>(aDes.Ptr()) + aOffset;

		for (; aOffset < endOffset; aOffset++)

			{

			*pRawType++ = *pRawSource++;

			}

		}

	template<> inline void UnpackTypeAdvance(TDriveList& aType, TDesC8& aDes, TInt& aOffset)

		/**

		Templated function to copy a simple type from a specified position in aDes

		defined by aOffset. aOffset is advanced so that on return, the new 

		offset is stored enabling the next call to UnpackType() to point at the position 

		following this type.

		@param aType This pointer is set with the pointer to the type in aDes

		@param aDes The buffer that contains the type T pointed to by aPtr

		@param aOffset The running index of where the following type begins. Updated by ExtractPointer

		*/

		{

		TUint8* pRawSource = const_cast<TUint8*>(aDes.Ptr()) + aOffset;

		aType.SetMax();

		for (TInt index = 0; index < KMaxDrives; index++)

			{

			aType[index] = *pRawSource++;

			}

		aOffset += KMaxDrives;

		}

	template<class T> inline void PackType(T& aType, TDesC8& aDes, TInt aOffset)

		/**

		Templated function to copy a simple type into a specified position in aDes

		defined by aOffset. aOffset is not advanced as a result of this operation

		@param aType This object is overwritten with the flattened type in aDes

		@param aDes The buffer that contains the type T pointed to by aPtr