1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Resource reader

    15 // 

    16 //

    17 

    18 #include <barsread.h>

    19 #include "BaRsReadImpl.h"

    20 

    21 #define UNUSED_VAR(a) a = a

    22 

    23 /** Sets the buffer containing the resource data.

    24 

    25 The current position within the buffer is set to the start of the buffer so 

    26 that subsequent calls to the interpreting functions, for example ReadInt8(), 

    27 start at the beginning of this buffer.

    28 

    29 @param aBuffer A pointer to an 8-bit non-modifiable descriptor containing 

    30 or representing resource data. */

    31 EXPORT_C void TResourceReader::SetBuffer(const TDesC8* aBuffer)

    32 	{

    33 	CreateImpl();

    34 	Impl()->SetBuffer(aBuffer);

    35 	}

    36 

    37 /** Returns the current position within the resource buffer. 

    38 

    39 The function makes no assumption about the type of data in the buffer at the 

    40 current position.

    41 

    42 @return A pointer to the current position within the resource buffer. */

    43 EXPORT_C const TAny* TResourceReader::Ptr()

    44     {

    45 	return Impl()->Ptr();

    46     }

    47 

    48 /** Interprets the data at the current buffer position as leading byte count data 

    49 and constructs an 8 bit heap descriptor containing a copy of this data.

    50 

    51 The data is interpreted as:

    52 

    53 a byte value defining the number of 8 bit text characters or the length of 

    54 binary data (the resource string/binary data length is limited to 255 characters max)

    55 

    56 followed by:

    57 

    58 the 8 bit text characters or binary data.

    59 

    60 If the value of the leading byte is zero, the function assumes that no data 

    61 follows the leading byte and returns a NULL pointer.

    62 

    63 The current position within the resource buffer is updated. If the resulting 

    64 position lies beyond the end of the resource buffer, then the function raises 

    65 a BAFL 4 panic.

    66 

    67 Use this explicit 8-bit variant when the resource contains binary data. If 

    68 the resource contains text, then use the build independent variant ReadHBufCL().

    69 

    70 In general, this type of resource data corresponds to one of the following:

    71 

    72 a LTEXT type in a resource STRUCT declaration.

    73 

    74 a variable length array within a STRUCT declaration which includes the LEN 

    75 BYTE keywords.

    76 

    77 @return A pointer to the 8-bit heap descriptor containing a copy of the data 

    78 following the leading byte count at the current position within the resource 

    79 buffer. The pointer can be NULL. */

    80 EXPORT_C HBufC8* TResourceReader::ReadHBufC8L()

    81 	{

    82 	return Impl()->ReadHBufC8L();

    83 	}

    84 

    85 /** Interprets the data at the current buffer position as leading byte count data 

    86 and constructs a 16 bit heap descriptor containing a copy of this data.

    87 

    88 The data is interpreted as:

    89 

    90 a byte value defining the number of 16 bit text characters

    91 (the resource string/binary data length is limited to 255 characters max)

    92 

    93 followed by:

    94 

    95 the 16 bit text characters.

    96 

    97 If the value of the leading byte is zero, the function assumes that no data 

    98 follows the leading byte and returns a NULL pointer.

    99 

   100 The current position within the resource buffer is updated. If the resulting 

   101 position lies beyond the end of the resource buffer, then the function raises 

   102 a BAFL 4 panic.

   103 

   104 Do not use this explicit 16-bit variant when the resource contains binary 

   105 data; use the explicit 8-bit variant instead. If the resource contains text, 

   106 use the build independent variant ReadHBufCL().

   107 

   108 @return A pointer to the 16-bit heap descriptor containing a copy of the 

   109 data following the leading byte count at the current position within the resource 

   110 buffer. The pointer can be NULL. */

   111 EXPORT_C HBufC16* TResourceReader::ReadHBufC16L()

   112 	{

   113 	return Impl()->ReadHBufC16L();

   114 	}

   115 

   116 /** Interprets the data at the current buffer position as leading byte count data 

   117 and constructs an 8 bit non modifiable pointer descriptor to represent this 

   118 data.

   119 

   120 The data is interpreted as:

   121 

   122 a byte value defining the number of text characters or the length of binary 

   123 data (the resource string/binary data length is limited to 255 characters max)

   124 

   125 followed by:

   126 

   127 the 8 bit text characters or binary data.

   128 

   129 If the value of the leading byte is zero, calling Length() on the returned 

   130 TPtrC8 returns zero.

   131 

   132 The current position within the resource buffer is updated. If the resulting 

   133 position lies beyond the end of the resource buffer, then the function raises 

   134 a BAFL 4 panic.

   135 

   136 Use this explicit 8-bit variant when the resource contains binary data. If 

   137 the resource contains text, then use the build independent variant ReadTPtrC().

   138 

   139 In general, this type of resource data corresponds to one of the following:

   140 

   141 a LTEXT type in a resource STRUCT declaration.

   142 

   143 a variable length array within a STRUCT declaration which includes the LEN 

   144 BYTE keywords.

   145 

   146 @return An 8-bit non modifiable pointer descriptor representing the data 

   147 following the leading byte count at the current position within the resource 

   148 buffer. */

   149 EXPORT_C TPtrC8 TResourceReader::ReadTPtrC8()

   150 	{

   151 	TPtrC8 retPtr;

   152 	// TRAP and ignore the Error code as its non leaving method

   153 	TRAPD(errCode, retPtr.Set(ReadTPtrC8L ()));

   154     UNUSED_VAR(errCode);

   155 	return retPtr;

   156 	}

   157 

   158 TPtrC8 TResourceReader::ReadTPtrC8L()

   159 	{

   160 	return Impl()->ReadTPtrC8L();

   161 	}

   162 

   163 

   164 /** Interprets the data at the current buffer position as leading byte count data 

   165 and constructs a 16 bit non modifiable pointer descriptor to represent this 

   166 data.

   167 

   168 The data is interpreted as:

   169 

   170 a byte value defining the number of 16 bit text characters

   171 (the resource string/binary data length is limited to 255 characters max)

   172 

   173 followed by:

   174 

   175 the 16 bit text characters.

   176 

   177 If the value of the leading byte is zero, calling Length() on the returned 

   178 TPtrC16 returns zero.

   179 

   180 The current position within the resource buffer is updated. If the resulting 

   181 position lies beyond the end of the resource buffer, then the function raises 

   182 a BAFL 4 panic.

   183 

   184 Do not use this explicit 16-bit variant when the resource contains binary 

   185 data; use the explicit 8-bit variant instead. If the resource contains text, 

   186 use the build independent variant ReadTPtrC().

   187 

   188 @return A 16-bit non modifiable pointer descriptor representing the data 

   189 following the leading byte count at the current position within the resource 

   190 buffer. */

   191 EXPORT_C TPtrC16 TResourceReader::ReadTPtrC16()

   192 	{

   193 	TPtrC16 retPtr;

   194 	// TRAP and ignore the Error code as its non leaving method

   195 	TRAPD(errCode, retPtr.Set(ReadTPtrC16L ()));

   196     UNUSED_VAR(errCode);

   197 	return retPtr;

   198 	}

   199 

   200 TPtrC16 TResourceReader::ReadTPtrC16L()

   201 	{

   202 	return Impl()->ReadTPtrC16L();

   203 	}

   204 

   205 /** Interprets the data within the specified resource buffer as an array of leading 

   206 byte count data and constructs an 8 bit non modifiable pointer descriptor 

   207 to represent an element within this array.

   208 

   209 The function sets the buffer containing the resource data and sets the current 

   210 position to the start of this buffer. Any buffer set by a previous call to 

   211 SetBuffer() etc, is lost.

   212 

   213 The buffer is expected to contain an array of data elements preceded by a 

   214 TInt16 value defining the number of elements within that array.

   215 

   216 Each element of the array is interpreted as:

   217 

   218 a byte value defining the number of 8 bit text characters or the length of 

   219 binary data (the resource string/binary data length is limited to 255 characters max)

   220 

   221 followed by:

   222 

   223 the 8 bit text characters or binary data.

   224 

   225 If the value of the leading byte is zero, calling Length() on the returned 

   226 TPtrC8 returns zero.

   227 

   228 The current position within the resource buffer is updated. If the resulting 

   229 position lies beyond the end of the resource buffer, then the function raises 

   230 a BAFL 4 panic.

   231 

   232 Use this explicit 8 bit variant when the resource contains binary data, If 

   233 the resource contains text, then use the build independent variant ReadTPtrC(TInt,const TDesC8*).

   234 

   235 @param aIndex The position of the element within the array. This value is 

   236 relative to zero.

   237 @param aBuffer The buffer containing the resource data.

   238 @return An 8-bit non modifiable pointer descriptor representing the data following 

   239 the leading byte count of the element at the specified position within the 

   240 array. */

   241 EXPORT_C TPtrC8 TResourceReader::ReadTPtrC8(TInt aIndex,const TDesC8* aBuffer)

   242     {

   243 	TPtrC8 retPtr;

   244 	// TRAP and ignore the Error code as its non leaving method

   245 	TRAPD(errCode, retPtr.Set(ReadTPtrC8L(aIndex, aBuffer)));

   246     UNUSED_VAR(errCode);

   247 	return retPtr;

   248     }

   249 

   250 TPtrC8 TResourceReader::ReadTPtrC8L(TInt aIndex,const TDesC8* aBuffer)

   251     {

   252 	CreateImpl();

   253 	return Impl()->ReadTPtrC8L(aIndex,aBuffer);

   254     }

   255 

   256 /** Interprets the data within the specified resource buffer as an array of leading 

   257 byte count data and constructs a 16 bit non modifiable pointer descriptor 

   258 to represent an element within this array.

   259 

   260 The function sets the buffer containing the resource data and sets the current 

   261 position to the start of this buffer. Any buffer set by a previous call to 

   262 SetBuffer() etc., is lost.

   263 

   264 The buffer is expected to contain an array of data elements preceded by a 

   265 TInt16 value defining the number of elements within that array.

   266 

   267 Each element of the array is interpreted as:

   268 

   269 a byte value defining the number of 8 bit text characters or the length of 

   270 binary data (the resource string/binary data length is limited to 255 characters max)

   271 

   272 followed by:

   273 

   274 the 16 bit text characters.

   275 

   276 If the value of the leading byte is zero, calling Length() on the returned 

   277 TPtrC16 returns zero.

   278 

   279 The current position within the resource buffer is updated. If the resulting 

   280 position lies beyond the end of the resource buffer, then the function raises 

   281 a BAFL 4 panic.

   282 

   283 Do not use this explicit 16-bit variant when the resource contains binary 

   284 data; use the explicit 8-bit variant instead. If the resource contains text, 

   285 use the build independent variant ReadTPtrC(TInt,const TDesC8*).

   286 

   287 @param aIndex The position of the element within the array. This value is 

   288 relative to zero.

   289 @param aBuffer The buffer containing the resource data.

   290 @return A 16-bit non modifiable pointer descriptor representing the data following 

   291 the leading byte count of the element at position within the array */

   292 EXPORT_C TPtrC16 TResourceReader::ReadTPtrC16(TInt aIndex,const TDesC8* aBuffer)

   293     {

   294 	TPtrC16 retPtr;

   295 	// TRAP and ignore the Error code as its non leaving method

   296 	TRAPD(errCode, retPtr.Set(ReadTPtrC16L(aIndex, aBuffer)));

   297     UNUSED_VAR(errCode);

   298 	return retPtr;

   299     }

   300 

   301 TPtrC16 TResourceReader::ReadTPtrC16L(TInt aIndex,const TDesC8* aBuffer)

   302     {

   303 	CreateImpl();

   304 	return Impl()->ReadTPtrC16L(aIndex,aBuffer);

   305     }

   306 

   307 /** Interprets the data at the current buffer position as an array of leading byte 

   308 count data and constructs a flat array of 8 bit descriptors.

   309 

   310 Each descriptor in the descriptor array corresponds to an element of the resource 

   311 array.

   312 

   313 At the current buffer position, the buffer is expected to contain an array 

   314 of data elements preceded by a TInt16 value defining the number of elements 

   315 within that array.

   316 

   317 Each element of the array is interpreted as:

   318 

   319 a byte value defining the number of 8 bit text characters or the length of 

   320 binary data (the resource string/binary data length is limited to 255 characters max)

   321 

   322 followed by:

   323 

   324 the text characters or binary data.

   325 

   326 The current position within the resource buffer is updated. If the resulting 

   327 position lies beyond the end of the resource buffer, then the function raises 

   328 a BAFL 4 panic.

   329 

   330 Use this explicit 8-bit variant when the resource contains binary data. If 

   331 the elements of the resource array contain text, use the build independent 

   332 variant of ReadDesCArrayL().

   333 

   334 @return A pointer to an 8-bit variant flat descriptor array. */

   335 EXPORT_C CDesC8ArrayFlat* TResourceReader::ReadDesC8ArrayL()

   336     {

   337 	return Impl()->ReadDesC8ArrayL();

   338     }

   339 

   340 /** Interprets the data at the current buffer position as an array of leading byte 

   341 count data and constructs a flat array of 16 bit descriptors.

   342 

   343 Each descriptor in the descriptor array corresponds to an element of the resource 

   344 array.

   345 

   346 At the current buffer position, the buffer is expected to contain an array 

   347 of data elements preceded by a TInt16 value defining the number of elements 

   348 within that array.

   349 

   350 Each element of the array is interpreted as:

   351 

   352 a byte value defining the number of 8 bit text characters or the length of 

   353 binary data (the resource string/binary data length is limited to 255 characters max)

   354 

   355 followed by:

   356 

   357 the 16 bit text characters.

   358 

   359 The current position within the resource buffer is updated. If the resulting 

   360 position lies beyond the end of the resource buffer, then the function raises 

   361 a BAFL 4 panic.

   362 

   363 Do not use this explicit 16-bit variant when the resource contains binary 

   364 data; use the explicit 8-bit variant instead. If the resource contains text, 

   365 use the build independent variant ReadDesCArrayL().

   366 

   367 @return A pointer to a 16-bit variant flat descriptor array. */

   368 EXPORT_C CDesC16ArrayFlat* TResourceReader::ReadDesC16ArrayL()

   369     {

   370 	return Impl()->ReadDesC16ArrayL();

   371     }

   372 

   373 /** Interprets the data at the current buffer position as a TInt8 type and returns 

   374 the value as a TInt.

   375 

   376 The current position within the resource buffer is updated. If the resulting 

   377 position lies beyond the end of the resource buffer, then the function raises 

   378 a BAFL 4 panic.

   379 

   380 In general, a TInt8 corresponds to a BYTE type in a resource STRUCT declaration.

   381 

   382 Note that in Symbian OS, a TInt is at least as big as a TInt8.

   383 

   384 @return The TInt8 value taken from the resource buffer. */

   385 EXPORT_C TInt TResourceReader::ReadInt8()

   386     {

   387 	TInt retInt=0;

   388 	// TRAP and ignore the Error code as its non leaving method

   389 	TRAPD(errCode, retInt=ReadInt8L());

   390     UNUSED_VAR(errCode);

   391 	return retInt;

   392     }

   393 

   394 TInt TResourceReader::ReadInt8L()

   395     {

   396 	return Impl()->ReadInt8L();

   397     }

   398 

   399 /** Interprets the data at the current buffer position as a TUint8 type and returns 

   400 the value as a TUint.

   401 

   402 The current position within the resource buffer is updated. If the resulting 

   403 position lies beyond the end of the resource buffer, then the function raises 

   404 a BAFL 4 panic.

   405 

   406 In general, a TUint8 corresponds to a BYTE type in a resource STRUCT declaration.

   407 

   408 Note that in Symbian OS, a TUint is at least as big as a TUint8.

   409 

   410 @return The TUint8 value taken from the resource buffer. */

   411 EXPORT_C TUint TResourceReader::ReadUint8()

   412     {

   413 	TUint retInt=0;

   414 	// TRAP and ignore the Error code as its non leaving method

   415 	TRAPD(errCode, retInt=ReadUint8L());

   416     UNUSED_VAR(errCode);

   417 	return retInt;

   418     }

   419 

   420 TUint TResourceReader::ReadUint8L()

   421     {

   422 	return Impl()->ReadUint8L();

   423     }

   424 

   425 /** Interprets the data at the current buffer position as a TInt16 type and returns 

   426 the value as a TInt.

   427 

   428 The current position within the resource buffer is updated. If the resulting 

   429 position lies beyond the end of the resource buffer, then the function raises 

   430 a BAFL 4 panic.

   431 

   432 In general, a TInt16 corresponds to a WORD type in a resource STRUCT declaration.

   433 

   434 Note that in Symbian OS, a TInt is at least as big as a TInt16.

   435 

   436 @return The TInt16 value taken from the resource buffer. */

   437 EXPORT_C TInt TResourceReader::ReadInt16()

   438     {

   439 	TInt retInt=0;

   440 	// TRAP and ignore the Error code as its non leaving method

   441 	TRAPD(errCode, retInt=ReadInt16L());

   442     UNUSED_VAR(errCode);

   443 	return retInt;

   444     }

   445 

   446 TInt TResourceReader::ReadInt16L()

   447     {

   448 	return Impl()->ReadInt16L();

   449     }

   450 

   451 /** Interprets the data at the current buffer position as a TUint16 type and returns 

   452 the value as a TUint.

   453 

   454 The current position within the resource buffer is updated. If the resulting 

   455 position lies beyond the end of the resource buffer, then the function raises 

   456 a BAFL 4 panic.

   457 

   458 In general, a TUint16 corresponds to a WORD type in a resource STRUCT declaration.

   459 

   460 Note that in Symbian OS, a TUint is at least as big as a TUint16.

   461 

   462 @return The TUint16 value taken from the resource buffer. */

   463 EXPORT_C TUint TResourceReader::ReadUint16()

   464     {

   465 	TUint retInt=0;

   466 	// TRAP and ignore the Error code as its non leaving method

   467 	TRAPD(errCode, retInt=ReadUint16L());

   468     UNUSED_VAR(errCode);

   469 	return retInt;

   470     }

   471 

   472 TUint TResourceReader::ReadUint16L()

   473     {

   474 	return Impl()->ReadUint16L();

   475     }

   476 

   477 /** Interprets the data at the current buffer position as a TInt32 type and returns 

   478 the value as a TInt.

   479 

   480 The current position within the resource buffer is updated. If the resulting 

   481 position lies beyond the end of the resource buffer, then the function raises 

   482 a BAFL 4 panic.

   483 

   484 In general, a TInt32 corresponds to a LONG type in a resource STRUCT declaration.

   485 

   486 Note that in Symbian OS, TInt and TInt32 are the same size.

   487 

   488 @return The TInt32 value taken from the resource buffer. */

   489 EXPORT_C TInt TResourceReader::ReadInt32()

   490     {

   491 	TInt retInt=0;

   492 	// TRAP and ignore the Error code as its non leaving method

   493 	TRAPD(errCode, retInt=ReadInt32L());

   494     UNUSED_VAR(errCode);

   495 	return retInt;

   496     }

   497 

   498 TInt TResourceReader::ReadInt32L()

   499     {

   500 	return Impl()->ReadInt32L();

   501     }

   502 

   503 /** Interprets the data at the current buffer position as a TUint32 type and returns 

   504 the value as a TUint.

   505 

   506 The current position within the resource buffer is updated. If the resulting 

   507 position lies beyond the end of the resource buffer, then the function raises 

   508 a BAFL 4 panic.

   509 

   510 In general, a TUint32 corresponds to a LONG type in a resource STRUCT declaration.

   511 

   512 Note that in Symbian OS a TUint is the same size as a TUint32.

   513 

   514 @return The TUint32 value taken from the resource buffer. */

   515 EXPORT_C TUint TResourceReader::ReadUint32()

   516     {

   517 	TUint retInt=0;

   518 	// TRAP and ignore the Error code as its non leaving method

   519 	TRAPD(errCode, retInt=ReadUint32L());

   520     UNUSED_VAR(errCode);

   521 	return retInt;

   522     }

   523 

   524 TUint TResourceReader::ReadUint32L()

   525     {

   526 	return Impl()->ReadUint32L();

   527     }

   528 

   529 /** Interprets the data at the current buffer position as a TReal64 type and returns 

   530 the value as a TReal64.

   531 

   532 The current position within the resource buffer is updated. If the resulting 

   533 position lies beyond the end of the resource buffer, then the function raises 

   534 a BAFL 4 panic.

   535 

   536 In general, a TReal64 corresponds to a DOUBLE type in a resource STRUCT declaration.

   537 

   538 @return The TReal64 value taken from the resource buffer. */

   539 EXPORT_C TReal64 TResourceReader::ReadReal64() __SOFTFP

   540     {

   541 	TReal64 retReal=0;

   542 	// TRAP and ignore the Error code as its non leaving method

   543 	TRAPD(errCode, retReal=ReadReal64L());

   544     UNUSED_VAR(errCode);

   545 	return retReal;

   546     }

   547 

   548 TReal64 TResourceReader::ReadReal64L() __SOFTFP

   549     {

   550 	return Impl()->ReadReal64L();

   551     }

   552 

   553 /** Copies a specified length of data from the resource buffer, starting at the 

   554 current position within the buffer, into the location pointed to by a specified 

   555 pointer. No assumption is made about the type of data at being read.

   556 

   557 The current position within the resource buffer is updated. If the resulting 

   558 position lies beyond the end of the resource buffer, then the function raises 

   559 a BAFL 4 panic.

   560 

   561 @param aPtr A pointer to the target location for data copied from the resource 

   562 buffer.

   563 @param aLength The length of data to be copied from the resource buffer. */

   564 EXPORT_C void TResourceReader::Read(TAny* aPtr,TInt aLength)

   565     {

   566 	// TRAP and ignore the Error code as its non leaving method

   567 	TRAPD(errCode, Impl()->ReadL(aPtr,aLength));

   568     UNUSED_VAR(errCode);

   569     }

   570 

   571 /** Moves the current buffer position backwards by the specified amount.

   572 

   573 If the resulting position lies before the start of the resource buffer, then 

   574 the function raises a BAFL 5 panic.

   575 

   576 @param aLength The length by which the current position is to be moved backward. */

   577 EXPORT_C void TResourceReader::Rewind(TInt aLength)

   578     {

   579 	// TRAP and ignore the Error code as its non leaving method

   580 	TRAPD(errCode, Impl()->RewindL(aLength));

   581     UNUSED_VAR(errCode);

   582     }

   583 

   584 /** Moves the current buffer position forwards by the specified amount.

   585 

   586 If the resulting position lies beyond the end of the resource buffer, then 

   587 the function raises a BAFL 4 panic.

   588 

   589 @param aLength The length by which the current position is to be advanced. */

   590 EXPORT_C void TResourceReader::Advance(TInt aLength)

   591 	{

   592 	// TRAP and ignore the Error code as its non leaving method

   593 	TRAPD(errCode, Impl()->AdvanceL(aLength));

   594     UNUSED_VAR(errCode);

   595 	}

   596 

   597 /** Placement new operator is used TResourceReaderImpl instance to be created.

   598 TResourceReaderImpl instance default behaviour - it will panic when there is a problem.

   599 

   600 @internalComponent */

   601 void TResourceReader::CreateImpl()

   602 	{

   603 	new (iImpl) TResourceReaderImpl;

   604 	}

   605 

   606 /** Placement new operator is used TResourceReaderImpl instance to be created.

   607 TResourceReaderImpl instance default behaviour - it will panic when there is a problem.

   608 

   609 @internalComponent */

   610 TResourceReaderImpl* TResourceReader::Impl()

   611 	{

   612 	return reinterpret_cast <TResourceReaderImpl*> (iImpl);

   613 	}

   614 

   615 /** The method returns a const pointer to TResourceReader implementation.

   616 

   617 @internalComponent */

   618 const TResourceReaderImpl* TResourceReader::Impl() const

   619 	{

   620 	return reinterpret_cast <const TResourceReaderImpl*> (iImpl);

   621 	}

   622