<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E9C763D4-AFFF-5D98-B82A-AF390A1B56A2" xml:lang="en"><title>Reading

from Large Files </title><shortdesc>How to read from large files. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F8EC9EE9-D699-509C-B4C4-054FC9F33AC6"><title>Introduction</title><p>Files

can be read from their current position or from a specified position. The

procedure is the same in both cases: </p><ol id="GUID-63D74D6D-1FA8-5D4F-918F-446492096096">

<li id="GUID-050331FD-7046-524F-AE3A-9A5B6B2A0A65"><p>Replace <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> with <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita"><apiname>RFile64</apiname></xref>. </p> <codeblock id="GUID-EC99FBD6-5830-574E-847B-559DA7319E32" xml:space="preserve">//RFile file;

RFile64 file;</codeblock> </li>

<li id="GUID-81709B5D-F194-5955-AFDF-B05BD3EB1D58"><p>Use a <codeph>TInt64</codeph> to

specify the position to start reading from. </p><p>The <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> variable

in the example below has been replaced with a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> to

read from locations beyond 2GB–1 in large files. </p> <codeblock id="GUID-7C026B6E-146E-500F-92BE-9AD391E80FD5" xml:space="preserve">// TInt readPosition = 0;

TInt64 readPosition = 0</codeblock> </li>

</ol></section>

<section id="GUID-559A2122-D5EF-53D3-9FA7-44F11B25D739"><title>Read() from

relative/current position</title><p>There are four <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-69D2F421-3391-3D39-88E8-49D106047065"><apiname>RFile64::Read()</apiname></xref> overloaded

functions that can read from a position in a file that is beyond 2GB–1:<ul>

<li id="GUID-1EA965AD-B142-5697-9D20-22B8AE4FFFF9"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-0E15871A-1FA2-323E-8A36-18BC5A2BCD4A"><apiname>RFile64::Read(TDes8&amp;

aDes)</apiname></xref>  </p> </li>

<li id="GUID-77B102B1-BD23-58AC-8D4A-79DFBA0CB79B"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-C0EB3323-0AD1-3C39-934A-E87422D7A3F2"><apiname>RFile64::Read(TDes8&amp;

aDes, TRequestStatus&amp; aStatus)</apiname></xref>  </p> </li>

<li id="GUID-D50D5170-8F6A-58C1-A3B0-2A0A538D01BE"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-881C2A3A-24B9-32B4-BFAE-2F407A4DE128"><apiname>RFile64::Read(TDes8&amp;

aDes, TInt aLength)</apiname></xref>  </p> </li>

<li id="GUID-8FF87AAD-69F9-5792-B8C8-645F7081A687"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-C391FFDF-5073-3299-8492-8E58FE4398D3"><apiname>RFile64::Read(TDes8&amp;

aDes, TInt aLength, TRequestStatus&amp; aStatus)</apiname></xref>. </p> </li>

</ul></p> <p><b>Example</b> </p><p>Modify

applications to handle reads beyond 2GB–1. For example, a counter variable

accumulating the number of bytes should be of type <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref>.

The counter variable <codeph>bytesRead</codeph> in the example below is now

a <codeph>TInt64</codeph>. </p><codeblock id="GUID-61122959-7EFE-5099-910F-460268440D3B" xml:space="preserve">    // RFile file;

    RFile64 file;

    TInt err = file.Open(TheFs, _L(“BIGFILE.BIG”), EFileRead);

    if(err != KErrNone)

     {

        // handle unrelated error

        return err;

     }

    // Large file access is now supported!

    // Replace TInt variable with TInt64 variable

    // Tint bytesRead = 0;

    TInt64 bytesRead = 0;

    TBuf8<4096> readBuf;

    ...

    // Read loop

    FOREVER

        {

        // Read a block

        r = file.Read(readBuf);

        if(KErrNone != r)

            {

            // Error handling

            break;

            }

        bytesRead += readBuf.Length(); // bytesRead can exceed 2G as large files are now supported</codeblock> </section>

<section id="GUID-52200A55-E323-5C7D-99A2-86F61E4D7F32"><title>Read() from

absolute position</title><p>There are four <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-69D2F421-3391-3D39-88E8-49D106047065"><apiname>RFile64::Read()</apiname></xref> overloaded

functions that may specify a position greater than 2GB-1. These functions

use a value of <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> to specify the position to start

reading from. <ul>

<li id="GUID-E21F04BE-B0D3-5098-9113-45A7CB651AAC"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-CEBEB5E7-FB20-36AC-B3FE-C2DAE9BD393E"><apiname>RFile64::Read(TInt64

aPos, TDes8&amp; aDes)</apiname></xref>  </p> </li>

<li id="GUID-DFD66B85-01A7-5163-8E7C-21343428CE5B"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-00247BB3-FF0B-369C-92FA-D9CE419BC2CA"><apiname>RFile64::Read(TInt64

aPos, TDes8&amp; aDes, TRequestStatus&amp; aStatus)</apiname></xref>  </p> </li>

<li id="GUID-6826723F-4A0A-5B9A-9211-1395CC4101CC"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-BBD91754-9CE4-3677-9158-B67A696CF64E"><apiname>RFile64::Read(TInt64

aPos, TDes8&amp; aDes, TInt aLength)</apiname></xref>  </p></li>

<li id="GUID-66F9D583-FA4F-5178-A9A2-798C4CD60CF8"><p> <xref href="GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7.dita#GUID-83A415A0-F417-3CA5-BA10-5AEF119AB1F7/GUID-0E5E4CF9-FE04-31A1-B6FF-E0AB77A03350"><apiname>RFile64::Read(TInt64

aPos, TDes8&amp; aDes, TInt aLength, TRequestStatus&amp; aStatus)</apiname></xref>. </p></li>

</ul></p><p><b>Example</b> </p><p>To

read locations beyond 2GB–1 in large files the file must be opened for 64-Bit

access and the <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> variable should be replaced with a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref> variable

or specify the position value directly. </p><codeblock id="GUID-FF1C9570-9078-5B93-844F-E97E6B3E763C" xml:space="preserve">//    RFile file;

    RFile64 file;

    TInt err = file.Open(TheFs, _L(“BIGFILE.BIG”), EFileRead);

    if(err != KErrNone)

     {

        // handle unrelated error

        return err;

     }

    // Large file access is now supported!

    // TInt readPosition = 0;

    TInt64 readPosition = 0;    // Use a TInt64 to prevent wrap-around

    TBuf8<4096> readBuf;

    ...

    // Read loop

    FOREVER

        {

        // Read a block

        r = file.Read(readPosition, readBuf);

        if(KErrNone != r)

            {

            // Error handling

            break;

            }

        readPosition += readBuf.Length();        // Must use TInt64 read position

        }</codeblock> </section>