<?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 <apiname>RBuf</apiname> 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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</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-7CACD30A-D6FC-38CB-A754-CB4B5C3728FF"><apiname>RBuf::CreateL()</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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-7CACD30A-D6FC-38CB-A754-CB4B5C3728FF"><apiname>RBuf::CreateL()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-7F4E287B-F06C-33CF-9F17-E0E69244860A"><apiname>RBuf::CreateMax()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-792C0C3B-203E-37FF-9BCF-8C9AEDB1CECE"><apiname>RBuf::CreateMaxL()</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-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</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-D3EA0EA9-EC2C-3555-8D39-7AF1EF6C7E8B"><apiname>RBuf::Swap()</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-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D3EA0EA9-EC2C-3555-8D39-7AF1EF6C7E8B"><apiname>RBuf::Swap()</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-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref>,
ownership of the buffer is transferred. <codeph>Assign()</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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</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-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</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()</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-D07FA48B-6FD0-3683-AEC9-ABC672AB2D80"><apiname>RBuf::ReAlloc()</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-D07FA48B-6FD0-3683-AEC9-ABC672AB2D80"><apiname>RBuf::ReAlloc()</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-0958525F-DB10-3D9A-AE99-B8113CA15810"><apiname>RBuf::Replace()</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-019690E0-EFD2-3A9D-9332-11FB5A16D407"><apiname>RBuf::Delete()</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-019690E0-EFD2-3A9D-9332-11FB5A16D407"><apiname>RBuf::Delete()</apiname></xref></p></li>
<li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-0958525F-DB10-3D9A-AE99-B8113CA15810"><apiname>RBuf::Replace()</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 OS 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>
</conbody></concept>