<?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>