<?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 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>
</conbody></concept>