1 // Copyright (c) 2008-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 the License "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 // f32\inc\f32file64.inl

    15 // 

    16 //

    17 

    18 /**

    19  

    20  Reads from the file at the current position.

    21  

    22  This is a synchronous function.

    23  

    24  Note that when an attempt is made to read beyond the end of the file,

    25  no error is returned. 

    26  The descriptor's length is set to the number of bytes read into 

    27  it. Therefore, when reading through a file,the end of file has been reached 

    28  when the descriptor length, as returned by TDesC8::Length(), is zero.

    29  

    30  @param aDes Descriptor into which binary data is read. Any existing contents 

    31  are overwritten. On return, its length is set to the number of

    32  bytes read.

    33  @return KErrNone if successful, otherwise one of the other system-wide error 

    34  codes.

    35  

    36  @see TDesC8::Length

    37 */

    38 inline TInt RFile64::Read(TDes8& aDes) const

    39 	{return RFile::Read(aDes);}

    40 

    41 /**

    42 Reads from the file at the current position.

    43 

    44 This is an asynchronous function.

    45 

    46 Note that when an attempt is made to read beyond the end of the file,

    47 no error is returned. 

    48 The descriptor's length is set to the number of bytes read into 

    49 it. Therefore, when reading through a file,the end of file has been reached 

    50 when the descriptor length, as returned by TDesC8::Length(), is zero.

    51 

    52 @param aDes    Descriptor into which binary data is read. Any existing contents 

    53                are overwritten. On return, its length is set to the number of

    54                bytes read.

    55                NB: this function is asynchronous and the request that it

    56                represents may not complete until some time after the call

    57                to the function has returned. It is important, therefore, that

    58                this descriptor remain valid, or remain in scope, until you have

    59                been notified that the request is complete.

    60                

    61 @param aStatus Request status. On completion contains:

    62        KErrNone, if successful, otherwise one of the other system-wide error codes.

    63 

    64 @see TDesC8::Length       

    65 */

    66 inline void RFile64::Read(TDes8& aDes,TRequestStatus& aStatus) const

    67 	{RFile::Read(aDes, aStatus);}

    68 

    69 /**

    70 Reads the specified number of bytes of binary data from the file at the current position.

    71 

    72 This is a synchronous function.

    73 

    74 Note that when an attempt is made to read beyond the end of the file,

    75 no error is returned. 

    76 The descriptor's length is set to the number of bytes read into 

    77 it. Therefore, when reading through a file,the end of file has been reached 

    78 when the descriptor length, as returned by TDesC8::Length(), is zero.

    79 Assuming aLength is less than the maximum length of the descriptor, the only circumstance 

    80 in which Read() can return fewer bytes than requested, is when the end of 

    81 file is reached or if an error occurs.

    82 

    83 @param aDes    Descriptor into which binary data is read. Any existing

    84                contents are overwritten. On return, its length is set to

    85                the number of bytes read.

    86             

    87 @param aLength The number of bytes to be read from the file into the descriptor. 

    88                If an attempt is made to read more bytes than the descriptor's 

    89                maximum length, the function returns KErrOverflow.

    90                This value must not be negative, otherwise the function

    91                returns KErrArgument.

    92                

    93 @return KErrNone if successful, otherwise one of the other system-wide error

    94         codes.

    95 */

    96 inline TInt RFile64::Read(TDes8& aDes,TInt aLength) const

    97 	{return RFile::Read(aDes, aLength);}

    98 

    99 /**

   100 Reads a specified number of bytes of binary data from the file at the current position.

   101 

   102 This is an asynchronous function.

   103 

   104 Note that when an attempt is made to read beyond the end of the file,

   105 no error is returned. 

   106 The descriptor's length is set to the number of bytes read into it.

   107 Therefore, when reading through a file, the end of file has been reached 

   108 when the descriptor length, as returned by TDesC8::Length(), is zero.

   109 Assuming aLength is less than the maximum length of the descriptor, the only

   110 circumstances in which Read() can return fewer bytes than requested is when

   111 the end of file is reached or if an error has occurred.

   112 

   113 @param aDes    Descriptor into which binary data is read. Any existing

   114                contents are overwritten. On return, its length is set to the

   115                number of bytes read.

   116                NB: this function is asynchronous and the request that it

   117                represents may not complete until some time after the call

   118                to the function has returned. It is important, therefore, that

   119                this descriptor remain valid, or remain in scope, until you have

   120                been notified that the request is complete.

   121                

   122 @param aLength The number of bytes to be read from the file into the descriptor. 

   123                If an attempt is made to read more bytes than the descriptor's

   124                maximum length, then the function updates aStatus parameter with KErrOverflow.

   125                It must not be negative otherwise the function updates aStatus with KErrArgument.

   126                

   127 @param aStatus Request status. On completion contains KErrNone if successful, 

   128                otherwise one of the other system-wide error codes.

   129 */

   130 inline void RFile64::Read(TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const

   131 	{ RFile::Read( aDes, aLength, aStatus);}

   132 

   133 /**

   134 Writes to the file at the current offset within the file.

   135 

   136 This is a synchronous function.

   137 

   138 @param aDes The descriptor from which binary data is written.

   139             The function writes the entire contents of aDes to the file.

   140 

   141 @return KErrNone if successful, otherwise one of the other system-wide error 

   142         codes.

   143 */

   144 inline TInt RFile64::Write(const TDesC8& aDes)

   145 	{return RFile::Write(aDes);}

   146 

   147 

   148 /** 

   149 Writes to the file at the current offset within the file.

   150 

   151 This is an asynchronous function.

   152 

   153 @param aDes    The descriptor from which binary data is written.

   154                The function writes the entire contents of aDes to the file.

   155                NB: this function is asynchronous and the request that it

   156                represents may not complete until some time after the call

   157                to the function has returned. It is important, therefore, that

   158                this descriptor remain valid, or remain in scope, until you have

   159                been notified that the request is complete.

   160             

   161 @param aStatus Request status. On completion contains KErrNone if successful, 

   162                otherwise one of the other system-wide error codes.

   163 */

   164 inline void RFile64::Write(const TDesC8& aDes,TRequestStatus& aStatus)

   165 	{RFile::Write(aDes, aStatus);}

   166 

   167 

   168 /**

   169 Writes a portion of a descriptor to the file at the current offset within

   170 the file.

   171 

   172 This is a synchronous function.

   173 

   174 @param aDes    The descriptor from which binary data is written.

   175 @param aLength The number of bytes to be written from the descriptor.

   176                This must not be greater than the length of the descriptor.

   177                It must not be negative.

   178 

   179 @return KErrNone if successful; KErrArgument if aLength is negative;

   180 		otherwise one of the other system-wide error codes.

   181         

   182 @panic FSCLIENT 27 in debug mode, if aLength is greater than the length

   183        of the descriptor aDes.  

   184 */

   185 inline TInt RFile64::Write(const TDesC8& aDes,TInt aLength)

   186 	{return RFile::Write(aDes, aLength);}

   187 

   188 

   189 /**

   190 Writes a portion of a descriptor to the file at the current offset

   191 within the file.

   192 

   193 This is an asynchronous function.

   194 

   195 @param aDes    The descriptor from which binary data is written.

   196                NB: this function is asynchronous and the request that it

   197                represents may not complete until some time after the call

   198                to the function has returned. It is important, therefore, that

   199                this descriptor remain valid, or remain in scope, until you have

   200                been notified that the request is complete.

   201 

   202 @param aLength The number of bytes to be written from the descriptor.

   203                This must not be greater than the length of the descriptor.

   204                It must not be negative.

   205 

   206 @param aStatus Request status. On completion contains KErrNone if successful; 

   207 			   KErrArgument if aLength is negative; 

   208 			   otherwise one of the other system-wide error codes.

   209 */

   210 inline void RFile64::Write(const TDesC8& aDes,TInt aLength,TRequestStatus& aStatus)

   211 	{RFile::Write(aDes, aLength, aStatus);}

   212 

   213 /**

   214 Reads from the file at the specified offset within the file

   215 

   216 This is a synchronous function.

   217 

   218 Note that when an attempt is made to read beyond the end of the file,

   219 no error is returned. 

   220 The descriptor's length is set to the number of bytes read into it.

   221 Therefore, when reading through a file, the end of file has been reached 

   222 when the descriptor length, as returned by TDesC8::Length(), is zero.

   223 

   224 Note:

   225 1. This function over-rides the base class function RFile::Read 

   226    and inlines the base class RFile::Read.

   227 2. The difference is that this function can read beyond 2GB - 1 when

   228    aPos + length of aDes is beyond 2GB - 1.

   229 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   230    to help migration to 64 bit file addressing. When the macro is defined, 

   231    this function becomes a private overload and hence use of 

   232    TInt RFile64::Read(TInt64 aPos,TDes8& aDes) const is recommended.

   233 

   234 @see TInt RFile::Read(TInt aPos,TDes8& aDes) const

   235 @see TInt RFile64::Read(TInt64 aPos,TDes8& aDes) const

   236 

   237 @param aPos Position of first byte to be read.  This is an offset from

   238             the start of the file. If no position is specified, reading

   239             begins at the current file position. 

   240             If aPos is beyond the end of the file, the function returns

   241             a zero length descriptor.

   242             

   243 @param aDes The descriptor into which binary data is read. Any existing content

   244             is overwritten. On return, its length is set to the number of

   245             bytes read.

   246             

   247 @return KErrNone if successful, otherwise one of the other system-wide error 

   248         codes.

   249 

   250 @panic FSCLIENT 19 if aPos is negative.

   251 */

   252 

   253 inline TInt RFile64::Read(TInt aPos,TDes8& aDes) const

   254 	{return RFile::Read(aPos, aDes);}

   255 

   256 /**

   257 Reads from the file at the specified offset within the file.

   258 

   259 This is an asynchronous function.

   260 

   261 Note that when an attempt is made to read beyond the end of the file,

   262 no error is returned. 

   263 The descriptor's length is set to the number of bytes read into it.

   264 Therefore, when reading through a file, the end of file has been reached 

   265 when the descriptor length, as returned by TDesC8::Length(), is zero.

   266 

   267 Note:

   268 1. This function over-rides the base class function RFile::Read 

   269    and inlines the base class RFile::Read.

   270 2. The difference is that this function can read beyond 2GB - 1 when

   271    aPos + length of aDes is beyond 2GB - 1.

   272 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   273    to help migration to 64 bit file addressing. When the macro is defined, 

   274    this function becomes a private overload and hence use of 

   275    void RFile64::Read(TInt64 aPos,TDes8& aDes,TRequestStatus& aStatus) const is recommended.

   276 

   277 @see void RFile::Read(TInt aPos,TDes8& aDes,TRequestStatus& aStatus) const

   278 @see void RFile64::Read(TInt64 aPos,TDes8& aDes,TRequestStatus& aStatus) const

   279 

   280 @param aPos    Position of first byte to be read. This is an offset from

   281                the start of the file. If no position is specified, 

   282                reading begins at the current file position.

   283                If aPos is beyond the end of the file, the function returns

   284                a zero length descriptor.

   285                

   286 @param aDes    The descriptor into which binary data is read. Any existing

   287                content is overwritten. On return, its length is set to

   288                the number of bytes read.

   289                NB: this function is asynchronous and the request that it

   290                represents may not complete until some time after the call

   291                to the function has returned. It is important, therefore, that

   292                this descriptor remain valid, or remain in scope, until you have

   293                been notified that the request is complete.

   294                

   295 @param aStatus The request status. On completion, contains an error code of KErrNone 

   296                if successful, otherwise one of the other system-wide error codes.

   297 

   298 @panic FSCLIENT 19 if aPos is negative.        

   299 */

   300 inline void RFile64::Read(TInt aPos,TDes8& aDes,TRequestStatus& aStatus) const

   301 	{RFile::Read(aPos, aDes, aStatus);}

   302 

   303 /**

   304 Reads the specified number of bytes of binary data from the file at a specified 

   305 offset within the file.

   306 

   307 This is a synchronous function.

   308 

   309 Note that when an attempt is made to read beyond the end of the file,

   310 no error is returned. 

   311 The descriptor's length is set to the number of bytes read into it.

   312 Therefore, when reading through a file, the end of file has been reached 

   313 when the descriptor length, as returned by TDesC8::Length(), is zero.

   314 Assuming aLength is less than the maximum length of the descriptor, the only

   315 circumstances in which Read() can return fewer bytes than requested is when

   316 the end of file is reached or if an error has occurred.

   317 

   318 Note:

   319 1. This function over-rides the base class function RFile::Read 

   320    and inlines the base class RFile::Read.

   321 2. The difference is that this function can read beyond 2GB - 1 when

   322    aPos + aLength is beyond 2GB - 1.

   323 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   324    to help migration to 64 bit file addressing. When the macro is defined, 

   325    this function becomes a private overload and hence use of 

   326    TInt RFile64::Read(TInt64 aPos,TDes8& aDes,TInt aLength) const is recommended.

   327 

   328 @see TInt RFile::Read(TInt aPos,TDes8& aDes,TInt aLength) const

   329 @see TInt RFile64::Read(TInt64 aPos,TDes8& aDes,TInt aLength) const

   330 

   331 @param aPos    Position of first byte to be read. This is an offset from

   332                the start of the file. If no position is specified, 

   333                reading begins at the current file position.

   334                If aPos is beyond the end of the file, the function returns

   335                a zero length descriptor.

   336                

   337 @param aDes    The descriptor into which binary data is read. Any existing

   338                contents are overwritten. On return, its length is set to

   339                the number of bytes read.

   340 @param aLength The number of bytes to read from the file into the descriptor. 

   341                If an attempt is made to read more bytes than the descriptor's

   342                maximum length, then the function updates aStatus parameter with KErrOverflow.

   343                It must not be negative otherwise the function updates aStatus with KErrArgument.

   344                

   345 @return KErrNone if successful, otherwise one of the other system-wide

   346         error codes.

   347 

   348 @panic FSCLIENT 19 if aPos is negative.        

   349 */

   350 inline TInt RFile64::Read(TInt aPos,TDes8& aDes,TInt aLength) const

   351 	{return RFile::Read(aPos, aDes, aLength);}

   352 

   353 /**

   354 Reads the specified number of bytes of binary data from the file at a specified 

   355 offset within the file.

   356 

   357 This is an asynchronous function.

   358 

   359 

   360 Note that when an attempt is made to read beyond the end of the file,

   361 no error is returned. 

   362 The descriptor's length is set to the number of bytes read into it.

   363 Therefore, when reading through a file, the end of file has been reached 

   364 when the descriptor length, as returned by TDesC8::Length(), is zero.

   365 Assuming aLength is less than the maximum length of the descriptor, the only

   366 circumstances in which Read() can return fewer bytes than requested is when

   367 the end of file is reached or if an error has occurred.

   368 

   369 Note:

   370 1. This function over-rides the base class function RFile::Read 

   371    and inlines the base class RFile::Read.

   372 2. The difference is that this function can read beyond 2GB - 1 when

   373    aPos + aLength is beyond 2GB - 1.

   374 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   375    to help migration to 64 bit file addressing. When the macro is defined, 

   376    this function becomes a private overload and hence use of 

   377    void RFile64::Read(TInt64 aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const is recommended.

   378 

   379 @see void RFile::Read(TInt aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const

   380 @see void RFile64::Read(TInt64 aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const

   381 

   382 @param aPos    Position of first byte to be read. This is an offset from

   383                the start of the file. If no position is specified, 

   384                reading begins at the current file position.

   385                If aPos is beyond the end of the file, the function returns

   386                a zero length descriptor.

   387                

   388 @param aDes    The descriptor into which binary data is read. Any existing

   389                contents are overwritten. On return, its length is set to

   390                the number of bytes read.

   391                NB: this function is asynchronous and the request that it

   392                represents may not complete until some time after the call

   393                to the function has returned. It is important, therefore, that

   394                this descriptor remain valid, or remain in scope, until you have

   395                been notified that the request is complete.

   396 

   397 @param aLength The number of bytes to read from the file into the descriptor. 

   398                If an attempt is made to read more bytes than the descriptor's

   399                maximum length, then the function returns KErrOverflow.

   400                It must not be negative otherwise the function returns KErrArgument.

   401 

   402 @param aStatus Request status. On completion contains KErrNone if successful, 

   403                otherwise one of the other system-wide error codes.

   404                

   405 @panic FSCLIENT 19 if aPos is negative.                       

   406 */

   407 inline void RFile64::Read(TInt aPos,TDes8& aDes,TInt aLength,TRequestStatus& aStatus) const

   408 	{ RFile::Read(aPos, aDes, aLength, aStatus);}

   409 

   410 /**

   411 Writes to the file at the specified offset within the file

   412 

   413 This is a synchronous function.

   414 

   415 Note:

   416 1. This function over-rides the base class function RFile::Write 

   417    and inlines the base class RFile::Write.

   418 2. The difference is that this function can write beyond 2GB - 1 when

   419    aPos + length of aDes is beyond 2GB - 1.

   420 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   421    to help migration to 64 bit file addressing. When the macro is defined, 

   422    this function becomes a private overload and hence use of 

   423    TInt RFile64::Write(TInt64 aPos,const TDesC8& aDes) is recommended.

   424 

   425 @see TInt RFile::Write(TInt aPos,const TDesC8& aDes)

   426 @see TInt RFile64::Write(TInt64 aPos,const TDesC8& aDes) 

   427 

   428 @param aPos The offset from the start of the file at which the first

   429             byte is written. 

   430             If a position beyond the end of the file is specified, then

   431             the write operation begins at the end of the file.

   432             If the position has been locked, then the write fails.

   433             

   434 @param aDes The descriptor from which binary data is written. The function writes 

   435             the entire contents of aDes to the file.

   436             

   437 @return KErrNone if successful, otherwise one of the other system-wide error

   438         codes.

   439 

   440 @panic FSCLIENT 19 if aPos is negative.                       

   441 */

   442 inline TInt RFile64::Write(TInt aPos,const TDesC8& aDes)

   443 	{return RFile::Write( aPos, aDes);}

   444 

   445 /**

   446 Writes to the file at the specified offset within the file

   447 

   448 This is an asynchronous function.

   449 

   450 Note:

   451 1. This function over-rides the base class function RFile::Write 

   452    and inlines the base class RFile::Write.

   453 2. The difference is that this function can write beyond 2GB - 1 when

   454    aPos + length of aDes is beyond 2GB - 1.

   455 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   456    to help migration to 64 bit file addressing. When the macro is defined, 

   457    this function becomes a private overload and hence use of 

   458    void RFile64::Write(TInt64 aPos,const TDesC8& aDes,TRequestStatus& aStatus) is recommended.

   459 

   460 @see void RFile::Write(TInt aPos,const TDesC8& aDes,TRequestStatus& aStatus)

   461 @see void RFile64::Write(TInt64 aPos,const TDesC8& aDes,TRequestStatus& aStatus)

   462 

   463 @param aPos    The offset from the start of the file at which the first

   464                byte is written. 

   465                If a position beyond the end of the file is specified, then

   466                the write operation begins at the end of the file.

   467                If the position has been locked, then the write fails.

   468                

   469 @param aDes    The descriptor from which binary data is written. The function

   470                writes the entire contents of aDes to the file.

   471                NB: this function is asynchronous and the request that it

   472                represents may not complete until some time after the call

   473                to the function has returned. It is important, therefore, that

   474                this descriptor remain valid, or remain in scope, until you have

   475                been notified that the request is complete.

   476 

   477 @param aStatus Request status. On completion contains KErrNone if successful, 

   478                otherwise one of the other system-wide error codes.

   479 

   480 @panic FSCLIENT 19 if aPos is negative.                       

   481 */

   482 inline void RFile64::Write(TInt aPos,const TDesC8& aDes,TRequestStatus& aStatus)

   483 	{RFile::Write(aPos, aDes, aStatus);}

   484 

   485 /**

   486 Writes the specified number of bytes to the file at the specified offset within the file.

   487 

   488 This is a synchronous function.

   489 

   490 Note:

   491 1. This function over-rides the base class function RFile::Write 

   492    and inlines the base class RFile::Write.

   493 2. The difference is that this function can write beyond 2GB - 1 when

   494    aPos + aLength is beyond 2GB - 1.

   495 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   496    to help migration to 64 bit file addressing. When the macro is defined, 

   497    this function becomes a private overload and hence use of 

   498    TInt RFile64::Write(TInt64 aPos,const TDesC8& aDes,TInt aLength) is recommended.

   499 

   500 @see TInt RFile::Write(TInt aPos,const TDesC8& aDes,TInt aLength)

   501 @see TInt RFile64::Write(TInt64 aPos,const TDesC8& aDes,TInt aLength)

   502 

   503 @param aPos    The offset from the start of the file at which the first

   504                byte is written. 

   505                If a position beyond the end of the file is specified, then

   506                the write operation begins at the end of the file.

   507                If the position has been locked, then the write fails.

   508                              

   509 @param aDes    The descriptor from which binary data is written.

   510 @param aLength The number of bytes to be written from aDes .

   511 			   It must not be negative.

   512 

   513 @return KErrNone if successful; KErrArgument if aLength is negative;

   514 		otherwise one of the other system-wide error codes.

   515         

   516 @panic FSCLIENT 19 if aPos is negative.                       

   517 */

   518 inline TInt RFile64::Write(TInt aPos,const TDesC8& aDes,TInt aLength)

   519 	{return RFile::Write(aPos, aDes, aLength);}

   520 

   521 /**

   522 Writes the specified number of bytes to the file at the specified offset within the file.

   523 

   524 This is an asynchronous function.

   525 

   526 Note:

   527 1. This function over-rides the base class function RFile::Write 

   528    and inlines the base class RFile::Write.

   529 2. The difference is that this function can write beyond 2GB - 1 when

   530    aPos + aLength is beyond 2GB - 1.

   531 3. This function is protected using _F32_STRICT_64_BIT_MIGRATION macro 

   532    to help migration to 64 bit file addressing. When the macro is defined, 

   533    this function becomes a private overload and hence use of 

   534    void RFile64::Write(TInt64 aPos,const TDesC8& aDes,TRequestStatus& aStatus) is recommended.

   535 

   536 @see void RFile::Write(TInt aPos,const TDesC8& aDes,TRequestStatus& aStatus)

   537 @see void RFile64::Write(TInt64 aPos,const TDesC8& aDes,TRequestStatus& aStatus)

   538 

   539 @param aPos    The offset from the start of the file at which the first

   540                byte is written. 

   541                If a position beyond the end of the file is specified, then

   542                the write operation begins at the end of the file.

   543                If the position has been locked, then the write fails.

   544               

   545 @param aDes    The descriptor from which binary data is written.

   546                NB: this function is asynchronous and the request that it

   547                represents may not complete until some time after the call

   548                to the function has returned. It is important, therefore, that

   549                this descriptor remain valid, or remain in scope, until you have

   550                been notified that the request is complete.

   551 

   552 @param aLength The number of bytes to be written from aDes.

   553 			   It must not be negative.

   554 			   

   555 @param aStatus Request status. On completion contains KErrNone if successful; 

   556 			   KErrArgument if aLength is negative; 

   557 			   otherwise one of the other system-wide error codes.

   558 

   559 @panic FSCLIENT 19 if aPos is negative.                       

   560 */

   561 inline void RFile64::Write(TInt aPos,const TDesC8& aDes,TInt aLength,TRequestStatus& aStatus)

   562 	{RFile::Write(aPos, aDes, aLength, aStatus);}