1 // Copyright (c) 2009 - 2010 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 * @file barsread2.cpp

    18 *

    19 * @internalComponent

    20 * @released

    21 */

    22 #include <iostream>

    23 #include <cassert>

    24 #include "barsc2.h"

    25 #include "barsread2.h"

    26 #include "barsreadimpl.h"

    27 

    28 /** It creates the implementation in place - iImpl array,

    29 and sets the default.

    30 */

    31 RResourceReader::RResourceReader() :

    32 	iRscBuffer(NULL)

    33 	{

    34 	new (iImpl) TResourceReaderImpl;

    35 	}

    36 

    37 /** The method calls RResourceReader::Close() method to release 

    38 allocated by the instance resources.

    39 */

    40 RResourceReader::~RResourceReader()

    41 	{

    42 	Close();

    43 	}

    44 

    45 /** 

    46 Sets the buffer containing the resource data.

    47 

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

    49 that subsequent calls to the interpreting functions, for example ReadInt8L(), 

    50 start at the beginning of this buffer.

    51 @param aRscFile A pointer to the CResourceFile object, used as a resource data supplier.

    52 @param aResourceId Numeric id of the resource to be read.

    53 */

    54 void RResourceReader::OpenL(CResourceFile* aRscFile, TInt aResourceId)

    55 {

    56 	if (aRscFile)

    57 	{

    58 		Close();

    59 		iRscBuffer = aRscFile->AllocReadL(aResourceId);

    60 		Impl()->SetBuffer(iRscBuffer);

    61 	}

    62 	else

    63 	{

    64 		std::string errMsg="Failed : Invalid Argument : CResourceFile* ";

    65 		throw CResourceFileException(errMsg);

    66 	}

    67 }

    68 

    69 /** 

    70 Destroys the buffer containing the resource data.

    71 

    72 Open() method should be called if you want to set

    73 the buffer and current position again.

    74 

    75 If a one or more copies of the same RResourceReader object exist - they share the same 

    76 resource data buffer. So destroying the RResourceReader object you will destroy the

    77 shared resource data buffer.

    78 

    79 @post Buffer pointer is set to NULL.

    80 @post Buffer current position pointer is set to NULL. 

    81 */

    82 void RResourceReader::Close()

    83 	{

    84 	delete iRscBuffer;

    85 	iRscBuffer = NULL;

    86 	Impl()->ResetBuffer();

    87 	}

    88 

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

    90 and constructs an 8 bit non modifiable pointer to represent this data.

    91 

    92 The data is interpreted as:

    93 

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

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

    96 

    97 followed by:

    98 

    99 the 8 bit text characters or binary data.

   100 

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

   102 PtrC8 returns zero.

   103 

   104 The current position within the resource buffer is updated.

   105 

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

   107 the resource contains text, then use the build independent variant ReadTPtrCL().

   108 

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

   110 

   111 a LTEXT type in a resource STRUCT declaration.

   112 

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

   114 BYTE keywords.

   115 

   116 @pre Open() is called to initialize RResourceReader data members.

   117 @return 8bit non modifiable pointer representing

   118 the data following the leading byte count at the

   119 current position within the resource buffer.

   120 @post Current buffer position is updated.

   121 @leave KErrEof The new buffer position is beyond the buffer end. */

   122 PtrC8* RResourceReader::ReadTPtrC8L()

   123 	{

   124 	return Impl()->ReadTPtrC8L();

   125 	}

   126 

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

   128 and constructs a 16 bit non modifiable pointer to represent this data.

   129 

   130 The data is interpreted as:

   131 

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

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

   134 

   135 followed by:

   136 

   137 the 16 bit text characters.

   138 

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

   140 PtrC16 returns zero.

   141 

   142 The current position within the resource buffer is updated.

   143 

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

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

   146 use the build independent variant ReadTPtrCL().

   147 

   148 @pre Open() is called to initialize RResourceReader data members.

   149 @return 16 bit non modifiable pointer representing

   150 the data following the leading byte count at the

   151 current position within the resource buffer.

   152 @post Current buffer position is updated.

   153 @leave KErrCorrupt The new buffer position is beyond the buffer end. */

   154 

   155 PtrC16* RResourceReader::ReadTPtrC16L()

   156 	{

   157 	return Impl()->ReadTPtrC16L();

   158 	}

   159 

   160 

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

   162 the value as a TInt.

   163 

   164 The current position within the resource buffer is updated.

   165 

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

   167 

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

   169 

   170 @pre Open() is called to initialize RResourceReader data members.

   171 @return The TInt8 value taken from the resource buffer.

   172 @post Current buffer position is updated.

   173 @leave KErrEof The new buffer position is beyond the buffer end. */

   174 TInt RResourceReader::ReadInt8L()

   175     {

   176 	return Impl()->ReadInt8L();

   177     }

   178 

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

   180 the value as a TUint.

   181 

   182 The current position within the resource buffer is updated.

   183 

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

   185 

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

   187 

   188 @pre Open() is called to initialize RResourceReader data members.

   189 @return The TUint8 value taken from the resource buffer.

   190 @post Current buffer position is updated.

   191 @leave KErrEof The new buffer position is beyond the buffer end. */

   192 TUint32 RResourceReader::ReadUint8L()

   193     {

   194 	return Impl()->ReadUint8L();

   195     }

   196 

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

   198 the value as a TInt.

   199 

   200 The current position within the resource buffer is updated.

   201 

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

   203 

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

   205 

   206 @pre Open() is called to initialize RResourceReader data members.

   207 @return The TInt16 value taken from the resource buffer.

   208 @post Current buffer position is updated.

   209 @leave KErrEof The new buffer position is beyond the buffer end. */

   210 TInt RResourceReader::ReadInt16L()

   211     {

   212 	return Impl()->ReadInt16L();

   213     }

   214 

   215 

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

   217 the value as a TInt.

   218 

   219 The current position within the resource buffer is updated.

   220 

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

   222 

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

   224 

   225 @pre Open() is called to initialize RResourceReader data members.

   226 @return The TInt32 value taken from the resource buffer.

   227 @post Current buffer position is updated.

   228 @leave KErrEof The new buffer position is beyond the buffer end. */

   229 TInt RResourceReader::ReadInt32L()

   230     {

   231 	return Impl()->ReadInt32L();

   232     }

   233 

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

   235 the value as a TUint.

   236 

   237 The current position within the resource buffer is updated.

   238 

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

   240 

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

   242 

   243 @pre Open() is called to initialize RResourceReader data members.

   244 @return The TUint32 value taken from the resource buffer.

   245 @post Current buffer position is updated.

   246 @leave KErrEof The new buffer position is beyond the buffer end. */

   247 TUint32 RResourceReader::ReadUint32L()

   248     {

   249 	return Impl()->ReadUint32L();

   250     }

   251 

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

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

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

   255 

   256 The current position within the resource buffer is updated.

   257 

   258 @pre Open() is called to initialize RResourceReader data members.

   259 @param aPtr Pointer to the target location for data copied from the resource buffer.

   260 @param aLength The length of data to be copied from the resource buffer.

   261 @post Current buffer position is updated.

   262 @leave KErrEof The new buffer position is beyond the buffer end. */

   263 void RResourceReader::ReadL(TAny* aPtr,TInt aLength)

   264     {

   265 	Impl()->ReadL(aPtr,aLength);

   266     }

   267 

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

   269 and constructs a build independent heap buffer containing a copy of this data.

   270 

   271 The data is interpreted as:

   272 

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

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

   275 

   276 followed by:

   277 

   278 the text characters or binary data. This resource data is interpreted as either 

   279 8 bit or 16 bit, depending on the build.

   280 

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

   282 follows the leading byte and returns a NULL pointer.

   283 

   284 The current position within the resource buffer is updated.

   285 

   286 Use this build independent variant when the resource contains text. If the 

   287 resource contains binary data, use the explicit 8 bit variant ReadHBufC8L().

   288 

   289 @pre Open() is called to initialize RResourceReader data members.

   290 @return Pointer to the heap buffer containing a copy of

   291 the data following the leading byte count at the

   292 current position within the resource buffer. The

   293 pointer can be NULL.

   294 @post Current buffer position is updated.

   295 @leave KErrCorrupt The resulting position lies beyond the end of the resource buffer. */

   296 Ptr16* RResourceReader::ReadHBufCL()

   297     {

   298 	return Impl()->ReadHBufCL();

   299 	}

   300 

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

   302 and constructs a non modifiable pointer to represent this data.

   303 

   304 The data is interpreted as:

   305 

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

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

   308 

   309 followed by:

   310 

   311 the text characters or binary data. This resource data is interpreted as either 

   312 8 bit or 16 bit, depending on the build.

   313 

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

   315 TPtrC returns zero.

   316 

   317 The current position within the resource buffer is updated.

   318 

   319 Use this build independent variant when the resource contains text. If the 

   320 resource contains binary data, use the explicit 8 bit variant ReadTPtrC8L().

   321 

   322 @pre Open() is called to initialize RResourceReader data members.

   323 @return Non modifiable pointer representing the

   324 data following the leading byte count of the element

   325 at the specified position within the array.

   326 @post Current buffer position is updated.

   327 @leave KErrCorrupt The resulting position lies beyond the end of the resource buffer. */

   328 PtrC16* RResourceReader::ReadTPtrCL()

   329     {

   330 	return ReadTPtrC16L();

   331 	}

   332 

   333 /** @internalComponent

   334 @return Non-const pointer to the implementation object. */

   335 TResourceReaderImpl* RResourceReader::Impl()

   336 	{

   337 	return reinterpret_cast <TResourceReaderImpl*> (iImpl);

   338 	}

   339 

   340 /** @internalComponent

   341 @return Const pointer to the implementation object. */

   342 const TResourceReaderImpl* RResourceReader::Impl() const

   343 	{

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

   345 	}

   346