1 /*

     2 * Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 * Note: This file may contain code to generate corrupt files for test purposes.

    16 * Such code is excluded from production builds by use of compiler defines;

    17 * it is recommended that such code should be removed if this code is ever published publicly.

    18 * base class for all types found in sis files. Defines all virtual functions.

    19 * fieldroot <- field <- container <- [array, sequence, structure] <- most SIS types

    20 * fieldroot <- field <- [string, compressed, blob]

    21 * fieldroot <- numeric

    22 * fieldroot <- header

    23 *

    24 */

    25 

    26 

    27 /**

    28  @file 

    29  @internalComponent

    30  @released

    31 */

    32 

    33 

    34 #ifndef __FIELDROOT_H__

    35 #define __FIELDROOT_H__

    36 

    37 #include <assert.h>

    38 #include "basefile.h"

    39 

    40 

    41 #ifdef GENERATE_ERRORS

    42 #ifndef _DEBUG

    43 #error GENERATE_ERRORS requires _DEBUG

    44 			// or change the code to rewrite TLV sizes in array and structure

    45 #endif

    46 #endif

    47 

    48 class CSISFieldRoot

    49 

    50 	{

    51 public:

    52 	typedef TUint64 TFieldSize;		// in BYTES

    53 

    54 	typedef enum

    55 		{

    56 		ESISUndefined,

    57 		ESISString,

    58 		ESISArray,

    59 		ESISCompressed,

    60 		ESISVersion,

    61 		ESISVersionRange, 

    62 		ESISDate,

    63 		ESISTime,

    64 		ESISDateTime,

    65 		ESISUid,

    66 		ESISUnused1,

    67 		ESISLanguage,

    68 		ESISContents,

    69 		ESISController,

    70 		ESISInfo,

    71 		ESISSupportedLanguages,

    72 		ESISSupportedOptions,

    73 		ESISPrerequisites,

    74 		ESISDependency,

    75 		ESISProperties,

    76 		ESISProperty,

    77 		ESISSignatures,

    78 		ESISCertificateChain,

    79 		ESISLogo,

    80 		ESISFileDescription,

    81 		ESISHash,

    82 		ESISIf,

    83 		ESISElseIf,

    84 		ESISInstallBlock,

    85 		ESISExpression,

    86 		ESISData,

    87 		ESISDataUnit,

    88 		ESISFileData,

    89 		ESISSupportedOption,

    90 		ESISControllerChecksum,

    91 		ESISDataChecksum,

    92 		ESISSignature,

    93 		ESISBlob,

    94 		ESISSignatureAlgorithm,

    95 		ESISSignatureCertificateChain,

    96 		ESISDataIndex,

    97 		ESISCapabilities,

    98 			// insert new fields here

    99 		ESISUnknown

   100 		} TFieldType;

   101 

   102 	typedef enum

   103 		{

   104 		EDbgDefault				= 0,

   105 		EDbgDataChecksum		= 0x01,

   106 		EDbgControllerChecksum	= 0x02,

   107 		EDbgCompress			= 0x04,

   108 		EDbgNoCompress			= 0x08,

   109 		} TDbgFlag;

   110 

   111 #ifdef GENERATE_ERRORS

   112 	typedef enum

   113 		{

   114 		EBugDefault			= 0,

   115 		EBugCRCError		= 0x0001,

   116 		EBugInvalidLength	= 0x0002,

   117 		EBugMissingField  	= 0x0004,

   118 		EBugUnexpectedField	= 0x0008,

   119 		EBugBigEndian	  	= 0x0010,

   120 		EBugDuffFieldType 	= 0x0020,

   121 		EBugInvalidValues  	= 0x0040,

   122 		EBugHashError	 	= 0x0080,

   123 		EBugNegativeLength	= 0x0100,

   124 		EBugInsaneString	= 0x0200,

   125 		EBugInsaneBlob		= 0x0400,

   126 		EBugArrayCount		= 0x0800,

   127 		EBug32As64			= 0x1000,

   128 		EBugUnknownField	= 0x2000,

   129 		EBugEmptyCaps       = 0x4000,

   130 		EBugUnknownData		= 0x8000,

   131 		} TBug;

   132 #endif // GENERATE_ERRORS

   133 

   134 	typedef enum

   135 		{

   136 		EOptDefault				= 0,

   137 		EOptIsUnicode			= 1<<0,

   138 		EOptIsDistributable		= 1<<1,

   139 		EOptIsCompareToMajor	= 1<<2,

   140 		EOptNoCompress			= 1<<3,

   141 		EOptShutdownApps		= 1<<4,

   142 		EOptNonRemovable		= 1<<5,

   143 		EOptROMUpgrade			= 1<<6,

   144 		} THeadOpt;

   145 

   146 

   147 public:

   148 	CSISFieldRoot ();

   149 	virtual ~CSISFieldRoot ();

   150 

   151 public:

   152 	/**

   153 	 * Internalize the class

   154 	 * @param aFile File stream from where data needs to be read.

   155 	 * @param aContainerSize size of the content to be read.

   156 	 * @param aArrayType Type of the array 

   157 	 */

   158 	virtual void Read (TSISStream& aFile, const TFieldSize& aContainerSize, const TFieldType aArrayType = ESISUndefined) = 0;

   159 	/**

   160 	 * Skip the file reading for this field. Read pointer will be moved to the

   161 	 * next field to be read.

   162 	 * @param aFile stream for which the data read should be skipped.

   163 	 * @param aContainerSize size of the data to be skipped. 

   164 	 */

   165 	virtual void Skip (TSISStream& aFile, const TFieldSize& aContainerSize) const = 0;

   166 	/**

   167 	 * Externalize the class

   168 	 * @param aFile File stream to which the data needs to be written.

   169 	 * @param aIsArrayElement whether the structure is part of an array or not. 

   170 	 */

   171 	virtual void Write (TSISStream& aFile, const bool aIsArrayElement) const = 0;

   172 	  

   173 	/**

   174 	 * This function verifies the structure. If verification of object fails, throw an exception

   175 	 * aLanguages >= 1

   176 	 * @param aLanguages - language

   177 	 */ 

   178 	virtual void Verify (const TUint32 aLanguages) const;

   179 	/**

   180 	 * if object not acceptable, modify it. Assumes, once modified, will not need modifying again

   181 	 */

   182 	virtual void MakeNeat ();

   183 	/**

   184 	 * @return 	if true, don't bother writing this record to disc

   185 	 * 			if false, when reading, it'd better be there

   186 	 */

   187 	virtual bool WasteOfSpace () const;

   188 	/**

   189 	 * Retrieves the size of the structure excluding the header.

   190 	 * @param aInsideArray - whether the structure is part of an array or not. 

   191 	 * @return byte count.

   192 	 */

   193 	virtual TFieldSize ByteCount (const bool aInsideArray) const = 0;

   194 	/**

   195 	 * Retrieves the in-stream size of data in BYTES of the structure with the header.

   196 	 * @param aInsideArray - whether the structure is part of an array or not. 

   197 	 * @return byte count.

   198 	 */

   199 	virtual TFieldSize ByteCountWithHeader (const bool aInsideArray) const;	

   200 	/**

   201 	 * Sets the size of the structure. 

   202 	 * either 	a) set variable size field, or

   203 	 *			b) ensure fixed size field is expected size

   204 	 * @param size - size of the structure. 

   205 	 */

   206 	virtual void SetByteCount (const TFieldSize aSize);

   207 	/**

   208 	 * Dump the entire content in hex format into the stream

   209 	 */

   210 	virtual void Dump (std::ostream& aStream, const int aLevel) const = 0;

   211 	/**

   212 	 * Adds the write the package details into the stream.

   213 	 * @param aStream - Stream in which the package entries need to be written.

   214 	 * @param aVerbose - If this option is set then detail description of pkg

   215 	 * 			will be written into the stream.

   216 	 */

   217 	virtual void AddPackageEntry(std::wostream& aStream, bool aVerbose) const;

   218 	/**

   219 	 * Class name

   220 	 */

   221 	virtual std::string Name () const;

   222 	/**

   223 	 * Calculates CRC of the content

   224 	 * @param aCRC CRC value of the content

   225 	 * @param aIsArrayElement whether the structure is part of an array or not. 

   226 	 */ 

   227 	virtual void CalculateCrc (TCRC& aCRC, const bool aIsArrayElement) const = 0 ;

   228 #ifdef GENERATE_ERRORS

   229 	virtual void CreateDefects ();

   230 #endif // GENERATE_ERRORS

   231 	virtual void SkipOldWriteNew (TSISStream& aFile) const;

   232 	/**

   233 	 * stream offset before the header

   234 	 */

   235 	virtual TSISStream::pos_type PreHeaderPos () const;

   236 	/**

   237 	 * stream offset after the header

   238 	 */

   239 	virtual TSISStream::pos_type PostHeaderPos () const;

   240 	/**

   241 	 * Calculates CRC of the content

   242 	 * @param aIsArrayElement whether the structure is part of an array or not. 

   243 	 * @return CRC value of the content

   244 	 */ 

   245 	TCRC Crc (const bool aIsArrayElement = false) const;

   246 	std::string NoteIfOptional () const;

   247 

   248 	/**

   249 	 * Set Debug options

   250 	 */

   251 	static void SetDebugOption (const TDbgFlag aDbgFlag);

   252 	/**

   253 	 * Check if a particular debug option is set or not.

   254 	 */

   255 	static bool IsDebugOptionSet (const TDbgFlag aDbgFlag);

   256 	/**

   257 	 * Set file header option

   258 	 */

   259 	static void SetHeaderOption (const THeadOpt aHeaderOption);

   260 	/**

   261 	 * Check if a particular file header option is set or not.

   262 	 */

   263 	static bool IsHeaderOptionSet (const THeadOpt aHeaderOption);

   264 

   265 #ifdef GENERATE_ERRORS

   266 	static void SetBug (const TBug aBug);

   267 	static bool IsBugSet (const TBug aBug);

   268 	static bool IsAnyBugSet ();

   269 	static void SetBugStart (const unsigned aStart);

   270 	static void SetBugRepeat (const unsigned aRepeat);

   271 	static bool IsBugToBeCreated (const TBug aBug);

   272 	static void AddRawDataValue (TSISStream& aFile,const unsigned aLength);

   273 #endif // GENERATE_ERRORS

   274 

   275 	/**

   276 	 * Initialize the instance.

   277 	 */

   278 	static void InitInstance ();

   279 

   280 protected:

   281 	// calculates the CRC of the given data

   282 	static void DoTheCrc (TCRC& aCRC, const TUint8* aData, const unsigned aLen);

   283 	

   284 	// calculates CRC on the given data and the padding bytes that will be required

   285 	static void DoPaddedCrc(TCRC& aCRC, const TUint8* aData, const unsigned aLen);

   286 	

   287 	// calculate the CRC of just the padding for the given data length

   288 	static void PaddingCrc(TCRC& aCRC, const unsigned aLength);

   289 

   290 	static unsigned SizeOfFieldType ();

   291 

   292 protected:

   293 	static TDbgFlag	iDbgFlag;

   294 	static THeadOpt	iOptions;

   295 

   296 #ifdef GENERATE_ERRORS

   297 	static TBug		iBug;

   298 	static unsigned iBugStart;

   299 	static unsigned iBugRepeat;

   300 	static unsigned iBugRepeatCountdown;

   301 #endif // GENERATE_ERRORS

   302 	};

   303 

   304 

   305 inline void CSISFieldRoot::AddPackageEntry(std::wostream& aStream, bool aVerbose) const

   306 	{

   307 	(void)aStream;

   308 	(void)aVerbose;

   309 	}

   310 

   311 inline void CSISFieldRoot::InitInstance ()

   312 	{

   313 	srand (1);

   314 		// Please consult the VC6 documentation to understand the supplied parameter value.

   315 	}

   316 

   317 

   318 inline void CSISFieldRoot::SetDebugOption (const TDbgFlag aDbgFlag)

   319 	{

   320 	iDbgFlag = static_cast <TDbgFlag> (static_cast <unsigned int> (iDbgFlag) + static_cast <unsigned int> (aDbgFlag));

   321 	}

   322 

   323 inline bool CSISFieldRoot::IsDebugOptionSet (const TDbgFlag aDbgFlag)

   324 	{

   325 	return (static_cast <unsigned int> (iDbgFlag) & static_cast <unsigned int> (aDbgFlag)) != 0;

   326 	}

   327 

   328 inline void CSISFieldRoot::SetHeaderOption (const THeadOpt aOptions)

   329 	{

   330 	iOptions = static_cast <THeadOpt> (static_cast <unsigned int> (iOptions) + static_cast <unsigned int> (aOptions));

   331 	}

   332 

   333 inline bool CSISFieldRoot::IsHeaderOptionSet (const THeadOpt aOptions)

   334 	{

   335 	return (static_cast <unsigned int> (iOptions) & static_cast <unsigned int> (aOptions)) != 0;

   336 	}

   337 

   338 #ifdef GENERATE_ERRORS

   339 inline void CSISFieldRoot::SetBug (const TBug aBug)

   340 	{

   341 	iBug = static_cast <TBug> (static_cast <unsigned int> (iBug) + static_cast <unsigned int> (aBug));

   342 	}

   343 

   344 inline bool CSISFieldRoot::IsBugSet (const TBug aBug)

   345 	{

   346 	return (static_cast <unsigned int> (iBug) & static_cast <unsigned int> (aBug)) != 0;

   347 	}

   348 

   349 inline bool CSISFieldRoot::IsAnyBugSet ()

   350 	{

   351 	return iBug != EBugDefault;

   352 	}

   353 

   354 inline void CSISFieldRoot::SetBugStart (const unsigned aStart)

   355 	{

   356 	iBugStart = aStart;

   357 	}

   358 

   359 inline void CSISFieldRoot::SetBugRepeat (const unsigned aRepeat)

   360 	{

   361 	iBugRepeat = aRepeat;

   362 	iBugRepeatCountdown = aRepeat;

   363 	}

   364 

   365 inline void CSISFieldRoot::CreateDefects ()

   366 	{

   367 	}

   368 #endif // GENERATE_ERRORS

   369 

   370 inline std::string CSISFieldRoot::NoteIfOptional () const

   371 	{

   372 	return WasteOfSpace () ? " (Dropped)" : std::string ();

   373 	}

   374 

   375 

   376 inline void CSISFieldRoot::Verify (const TUint32 aLanguages) const

   377 	{ 

   378 	}

   379 

   380 

   381 inline bool CSISFieldRoot::WasteOfSpace () const

   382 	{ 

   383 	return false; 

   384 	}

   385 

   386 

   387 inline CSISFieldRoot::TFieldSize CSISFieldRoot::ByteCountWithHeader (const bool aInsideArray) const

   388 	{ 

   389 	return ByteCount (aInsideArray); 

   390 	}

   391 	

   392 		

   393 inline void CSISFieldRoot::SetByteCount (const TFieldSize aSize)

   394 	{

   395 	assert (aSize == ByteCount (false));

   396 	}

   397 

   398 

   399 inline void CSISFieldRoot::MakeNeat ()

   400 	{ 

   401 	}

   402 

   403 

   404 inline std::string CSISFieldRoot::Name () const

   405 	{

   406 	return std::string ();

   407 	}

   408 

   409 

   410 inline unsigned CSISFieldRoot::SizeOfFieldType ()

   411 	{

   412 	return sizeof (TUint32);

   413 	}

   414 

   415 inline void CSISFieldRoot::SkipOldWriteNew (TSISStream& aFile) const

   416 	{

   417 	}

   418 

   419 inline TSISStream::pos_type CSISFieldRoot::PreHeaderPos () const

   420 	{

   421 	return 0;

   422 	}

   423 

   424 inline TSISStream::pos_type CSISFieldRoot::PostHeaderPos () const

   425 	{

   426 	return 0;

   427 	}

   428 

   429 TSISStream& operator >> (TSISStream& aFile, CSISFieldRoot::TFieldType& aType);

   430 TSISStream& operator << (TSISStream& aFile, const CSISFieldRoot::TFieldType aType);

   431 

   432 #endif // __FIELDROOT_H__

   433