<?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-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832" xml:lang="en"><title>rbufexample: Using resizable buffer descriptors</title><shortdesc>This example application demonstrates how to use the <codeph>RBuf</codeph> class. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> is a resizable buffer descriptor. It is

part of the user library. It is used to contain strings and binary

data when the maximum size of the data is not known until run time. </p>

<p>This overview contains the following sections: </p>

<ul>

<li id="GUID-6A429EA8-8396-5A67-BF08-5CC81426D99A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-7605348A-0F8B-56A4-A48C-C83CB1CD546D">Download</xref> </p> </li>

<li id="GUID-9BBBEFB0-D463-5A81-9AF8-8FE0FB781D5A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-BC0B8F0D-94A8-51D1-9BC2-85E4F76C482A">Description</xref>  </p> </li>

<li id="GUID-4946F730-6E6A-5EC2-8A73-F0E29EBB09D9"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-69043124-f5fc-499b-8550-0c5b6ed66fe5">Class summary</xref>  </p> </li>

<li id="GUID-4D0A67AF-FAC5-51F5-8C4F-5E9FBF1C2981"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-111B7B66-A3C4-5A15-8CF2-C6A227483651">Build</xref>  </p> </li>

<li id="GUID-F01C5F43-391A-562A-A6E2-B7C34A2FB01A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-E30CC1D4-B854-5080-8F37-950CA4D86DD0">See also</xref>  </p> </li>

</ul>

<section id="GUID-7605348A-0F8B-56A4-A48C-C83CB1CD546D"><title>Download</title> <p>Click on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-7520d937-647a-495a-9196-edca52b98e89.zip" scope="external">rbufexample.zip</xref>.</p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-7520d937-647a-495a-9196-edca52b98e89.html" scope="peer">browse</xref> to view the example code.</p> </section>

<section id="GUID-BC0B8F0D-94A8-51D1-9BC2-85E4F76C482A"><title>Description</title> <ul>

<li id="GUID-87468748-0221-5005-9A98-EE03F5280421"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-B2AF4A97-A93B-5437-A31D-85C98AFC7DBB"> Creating an RBuf</xref>  </p> </li>

<li id="GUID-6A66563D-F504-5D7E-8274-78126F2877F8"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-88B88124-BB7D-58DC-9F8A-61C32BDD58C4">Swapping two RBufs</xref>  </p> </li>

<li id="GUID-6F41B457-6A2B-5895-8404-DCE5F971B59B"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-893B2BF3-AD9F-587D-95D5-165014C932B4">Copying data to an RBuf using the assignment operator</xref>  </p> </li>

<li id="GUID-0B584C6E-A740-5CD6-A8F7-E2DA4327D2B9"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-2B6B8519-6306-5F0C-8A79-4094A3037901">Reallocating an RBuf</xref>  </p> </li>

<li id="GUID-D96AC20C-5F22-52F7-B299-F178B90AE214"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-DE5A5DC0-07C6-50B9-AFDA-E69A92A02980"> Replacing and modifying the data in an RBuf</xref>  </p> </li>

</ul> <p id="GUID-B2AF4A97-A93B-5437-A31D-85C98AFC7DBB"><b>Creating

an RBuf</b> </p> <p>The example demonstrates creating an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> in the following ways: </p> <ol id="GUID-B4E38F9F-B275-5364-B59C-71087CDDAF1C">

<li id="GUID-0482EE2B-165C-5B55-B819-741026C38F02"><p> <b>Using RBuf::Create()

or RBuf::CreateL():</b> These functions create either an empty descriptor,

or one with data copied from another descriptor. </p> </li>

<li id="GUID-00E1680C-CB9C-5CC8-BC4A-C7337E0B9B9D"><p> <b>Using RBuf::CreateMax()

or RBuf::CreateMaxL():</b> These functions set the buffer's current

length to be the same as its maximum length. </p> </li>

<li id="GUID-A0E4C908-5542-53D3-8452-BDA3BFB8887D"><p> <b>By assigning

from an HBufC:</b> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-24070146-5588-3525-AC3E-62DA78BEA297"><apiname>RBuf::Assign(HBufC8*)</apiname></xref> transfers

ownership of the heap descriptor. It is not possible to access the

original heap descriptor once ownership has been transferred. </p> </li>

<li id="GUID-B8812B95-CE27-5850-B866-F6DBC18ADF8C"><p> <b>By assigning

some previously allocated memory:</b> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-8B622E83-88C5-3561-98FC-E2157022BCBC"><apiname>RBuf::Assign(const

RBuf8&amp; )</apiname></xref> transfers ownership of allocated memory. It

is then not possible to access the original memory. </p> </li>

<li id="GUID-9FCBF30F-815B-5CA9-B0B6-1698DA0C4F0E"><p> <b>Using RReadStream:</b> The example writes some text to a file stream (<codeph>RFileWriteStream</codeph>). Then it creates the buffer by passing the open stream object to <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-C029FB52-971D-3C53-A6BC-C6FEC0E9BCDB"><apiname>RBuf::CreateL(TInt)</apiname></xref>. </p> </li>

</ol><p><b>Related APIs</b></p><ul>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> - Defines a build-independent resizable

buffer descriptor.</p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9B5FF0B6-9C38-3E74-A5BC-A5CB02E029B7"><apiname>RBuf::Assign(const RBuf8&amp;)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E69BAB5A-EFC1-3700-8B56-9A5876BF428D"><apiname>RBuf::Create(const TDesC8&amp;)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D1478239-6AFC-30F3-B836-D76F53725844"><apiname>RBuf::CreateL(const TDesC8&amp;)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-2BB11BE2-CCD9-3197-B4A5-4001474AEEAF"><apiname>RBuf::CreateMax(TInt)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-EF93482B-CD75-3744-B5B1-3AED1E4F0637"><apiname>RBuf::CreateMaxL(TInt)</apiname></xref></p></li>

</ul> <p id="GUID-88B88124-BB7D-58DC-9F8A-61C32BDD58C4"><b>Swapping

two RBufs</b> </p> <p>The example creates two resizable buffers using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E69BAB5A-EFC1-3700-8B56-9A5876BF428D"><apiname>RBuf::Create(const TDesC8&amp;)</apiname></xref>. Then it swaps the contents

of them using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E396F6CA-1353-31E3-8AFF-BAFE2DF6E0E7"><apiname>RBuf::Swap(RBuf8&amp;)</apiname></xref>. </p> <p> <b>Note:</b> When you swap data between two <codeph>RBuf</codeph> s

ensure that the maximum length of the target <codeph>RBuf</codeph> is sufficient to hold the data, otherwise a panic (<codeph>User

11</codeph>) occurs. </p><p><b>Related APIs</b></p><ul>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E69BAB5A-EFC1-3700-8B56-9A5876BF428D"><apiname>RBuf::Create(const TDesC8&amp;)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E396F6CA-1353-31E3-8AFF-BAFE2DF6E0E7"><apiname>RBuf::Swap(RBuf8&amp;)</apiname></xref></p></li>

</ul> <p id="GUID-893B2BF3-AD9F-587D-95D5-165014C932B4"><b>Copying

data to an RBuf using the assignment operator</b> </p> <p>The example

creates two resizable buffers and allocates memory using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-E69BAB5A-EFC1-3700-8B56-9A5876BF428D"><apiname>RBuf::Create(const TDesC8&amp;)</apiname></xref>. It then copies

data to these buffers. It also copies data from the first buffer to

the second buffer using the assignment operator. </p> <p> <b> Notes:</b>  </p> <ul>

<li id="GUID-9B2835F9-BD3E-56DD-9CFD-F71677FFC71C"><p>When you use <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9B5FF0B6-9C38-3E74-A5BC-A5CB02E029B7"><apiname>RBuf::Assign(const RBuf8&amp;)</apiname></xref>, ownership of the buffer

is transferred. <codeph>Assign(const RBuf8&amp;)</codeph> neither

checks nor frees any pre-existing owned allocated memory. If this

descriptor already owns some allocated memory, <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-32EB41B6-A1C8-326C-9D52-095B05D4D20B"><apiname>RBuf16::Close()</apiname></xref> should be invoked on it before calling <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9B5FF0B6-9C38-3E74-A5BC-A5CB02E029B7"><apiname>RBuf::Assign(const

RBuf8&amp;)</apiname></xref>, otherwise a memory leak will occur. </p> </li>

<li id="GUID-41218102-1810-5E83-BAEE-5683D378F75F"><p>When you use

the assignment operator, you must make sure the target descriptor's

maximum length is equal to or greater than the length of the source

descriptor, otherwise a <codeph>User 11</codeph> panic (descriptor

overflow) occurs. Any existing data in the target descriptor is replaced. </p> </li>

</ul> <p><b>Related APIs</b></p><ul>

<li><p><xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-32EB41B6-A1C8-326C-9D52-095B05D4D20B"><apiname>RBuf16::Close()</apiname></xref></p></li>

<li><p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9B5FF0B6-9C38-3E74-A5BC-A5CB02E029B7"><apiname>RBuf::Assign(const RBuf8&amp;)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-05537A6D-F8B8-3760-B9CA-591465BEFE4B"><apiname>RBuf::Create(TInt)</apiname></xref></p></li>

</ul><p id="GUID-2B6B8519-6306-5F0C-8A79-4094A3037901"><b>Reallocating

an RBuf</b> </p> <p>The example creates a resizable buffer descriptor,

then it resizes it using <codeph>RBuf::ReAlloc(TInt)</codeph>. The

old and new lengths are printed to the console to show how <codeph>ReAlloc()</codeph> does not change the length of the descriptor,

but only its maximum length. Calling <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9887F6B2-492E-3225-905C-7841A2C9CAE8"><apiname>RBuf::ReAlloc(TInt)</apiname></xref> with a value of zero frees the memory and sets the length and maximum

length to zero. </p><p><b>Related APIs</b></p><ul>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-9887F6B2-492E-3225-905C-7841A2C9CAE8"><apiname>RBuf::ReAlloc(TInt)</apiname></xref></p></li>

</ul> <p id="GUID-DE5A5DC0-07C6-50B9-AFDA-E69A92A02980"><b> Replacing

and modifying the data in an RBuf</b> </p> <p>The example creates

a resizable buffer descriptor and replaces a portion of the data in

it using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-FB7C2936-6CE6-38BF-80BE-F02364F21E6B"><apiname>RBuf::Replace(TInt ,TInt ,const TDesC16&amp;)</apiname></xref>. The start position and length of the data to be replaced, and the

replacement text are passed as parameters. <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-05E77813-EAA3-37DF-A857-0687916F2E30"><apiname>RBuf::Delete(TInt

, TInt)</apiname></xref> is then used to delete the replacement text, by

specifying the position and length of the data to be deleted. </p><p><b>Related APIs</b></p><ul>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-05E77813-EAA3-37DF-A857-0687916F2E30"><apiname>RBuf::Delete(TInt , TInt)</apiname></xref></p></li>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-FB7C2936-6CE6-38BF-80BE-F02364F21E6B"><apiname>RBuf::Replace(TInt ,TInt ,const TDesC16&amp;)</apiname></xref></p></li>

</ul> </section>

<section id="GUID-69043124-F5FC-499B-8550-0C5B6ED66FE5"><title>Class

summary</title><ul>

<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> - Defines a build-independent resizable

buffer descriptor.</p></li>

<li><p> <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> - Defines a build-independent heap

descriptor.</p></li>

<li><p><xref href="GUID-EFFA9A71-4CA4-3227-879D-17EFEB8B07D6.dita"><apiname>RFileWriteStream</apiname></xref> - Supports the writing

of a stream to a file.</p></li>

<li><p><xref href="GUID-90A3AE1D-DCB2-3E98-8BE9-C48C15964E7D.dita"><apiname>RFileReadStream</apiname></xref> - Supports the reading of

a stream from a file.</p></li>

<li><p><xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref></p></li>

</ul></section>

<section id="GUID-111B7B66-A3C4-5A15-8CF2-C6A227483651"><title>Build</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian

build process</xref> describes how to build this example application.

The example builds an executable file called <filepath>rbufexample.exe</filepath> in the standard location (<filepath>\epoc32\release\winscw\&lt;build_variant&gt;</filepath> for the emulator). After launching the executable, depending on

the emulator you are using, you may need to navigate away from the

application launcher/shell screen to view the console. </p> </section>

<section id="GUID-E30CC1D4-B854-5080-8F37-950CA4D86DD0"><title>See

also</title> <p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita">How to use the resizable buffer descriptor - RBuf</xref>  </p> </section>