<?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-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A" xml:lang="en"><title>How to

use the resizable buffer descriptor - RBuf</title><shortdesc>Use this descriptor to hold a string or binary data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A resizable buffer descriptor is an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> type. Use the

member functions of the base classes: <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> and <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> to

change the data in the descriptor. See <xref href="GUID-C85B4EA2-0184-52AF-B097-152E4A023CEF.dita">Abstract

base descriptor classes</xref>. </p>

<p>This buffer of the descriptor is put on the heap. The buffer is the place

where the data is put. This is useful if you do not know the maximum size

of the data until run time. </p>

<p>The resizable buffer descriptors are similar to what are called <xref href="GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita">Heap

descriptors</xref>, or <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> types, but the API provided

by <codeph>RBuf</codeph> is easier to use. The <codeph>RBuf</codeph> API also

makes it easier to change the maximum size of the buffer containing the data,

a task often referred to as reallocating the buffer. </p>

<p>The general guidelines are: use <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> descriptors to

contain data that rarely changes; use <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> descriptors

to contain data that changes frequently. However, in practice, <codeph>RBuf</codeph> types

are equally suitable for both cases, and you should <i>always consider</i> using

an <codeph>RBuf</codeph> in preference to an <codeph>HBufC</codeph>. </p>

<p>For cases where your code uses APIs that return an <codeph>HBufC</codeph> type,

you can convert this to an <codeph>RBuf</codeph>. In effect, <codeph>RBuf</codeph> can

act as a wrapper around the <codeph>HBufC</codeph>; access and manipulation

of the data is then done through the member functions of <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> and

its base classes <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> and <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref>  </p>

<p>Some key points about resizable buffer descriptors: </p>

<ul>

<li id="GUID-C9051973-DFA3-57E6-8AD2-E6E1B49B0A74"><p>For text data, it is

usual to construct an <codeph>RBuf</codeph> type and allow the appropriate

variant, either a <xref href="GUID-955061A8-A83E-39E5-8745-8FAC7DEA7BCC.dita"><apiname>RBuf8</apiname></xref> or a <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref> to

be selected at build time. </p> </li>

<li id="GUID-93CD2C60-ABB6-5063-8CCA-B63B09139A3F"><p>For binary data, an

explicit <xref href="GUID-955061A8-A83E-39E5-8745-8FAC7DEA7BCC.dita"><apiname>RBuf8</apiname></xref> is used. </p> </li>

<li id="GUID-82B1C228-51A3-5FED-9797-206805BD3DA5"><p>It is rare to use an

explicit <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref>. </p> </li>

<li id="GUID-2F339945-4741-59A1-AEAA-B405379E25DB"><p>Data can be changed

through <codeph>RBuf</codeph> as well as replaced using its assignment operators.

Like all descriptors, <codeph>RBuf</codeph> is derived from: </p> <ul>

<li id="GUID-7145D7BB-ABCC-5BF8-B367-6D8F9C308AF9"><p>the <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> class,

through which the data can be manipulated </p> </li>

<li id="GUID-18DF3A17-15E7-54C7-8E3D-1A968AD46D14"><p>the <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> class,

through which information about the data (such as its length) can be retrieved. </p> </li>

</ul> </li>

<li id="GUID-F2EE3065-3D20-5D2B-9887-2C2181FB0195"><p>You can pass an <codeph>RBuf</codeph> to

a function that takes a <codeph>TDesC&amp;</codeph> parameter, and a <codeph>TDes&amp;</codeph> parameter. </p> </li>

<li id="GUID-83C851DA-BC8C-543D-9987-656FA19832C2"><p>Memory that has already

been allocated by your code can be transferred to an <codeph>RBuf</codeph>.

This allows any data that may be in that location to be managed through the

descriptor. </p> </li>

<li id="GUID-6C6B51EE-486C-5ED1-A343-F6777DB5D130"><p>Ownership of an existing <codeph>HBufC</codeph> can

be transferred to an <codeph>RBuf</codeph>. This allows the data contained

within the <codeph>HBufC</codeph> to be managed through the <codeph>RBuf</codeph> API. </p> </li>

</ul>

<p>Although the following notes refer to the build independent types, they

are equally valid for the explicit 8-bit and 16-bit types. </p>

<ul>

<li id="GUID-9506E27E-3079-52A9-A993-4DD1DE1BB50B"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-A72C3172-7185-5D87-B4CB-6266AC6146A3">Creating an RBuf</xref>  </p> </li>

<li id="GUID-C7A121AA-401B-5524-A171-E84352170D71"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-2B23F296-D414-5ABD-82CA-DDCEE2F48459">Re-allocating the memory buffer</xref>  </p> </li>

<li id="GUID-AC98AE5C-AF3F-5105-BDFF-958D080C92E1"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-A6368F43-9A67-5583-B279-FE68B8CADEC4">Freeing the memory buffer</xref>  </p> </li>

<li id="GUID-883D98FB-E588-5BCB-A0C0-A64465BFDDA7"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-7ECF515D-D538-5F6C-B2A0-88C1B4E3505C">Cleanup rules</xref>  </p> </li>

<li id="GUID-94E02925-DDB7-5C8E-9B5B-E98DA78D65D4"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-6732B0A9-4E6E-50A8-9C4F-ADB2BB8FBAEF">Replacing and modifying data</xref>  </p> </li>

</ul>

<section id="GUID-A72C3172-7185-5D87-B4CB-6266AC6146A3"><title>Creating an

RBuf</title> <p>An <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> object behaves like a handle to

a resource. In this case, the resource is the buffer that contains the data.

While this might seem to be an implementation issue, you need to understand

that much of the interface provided by the <codeph>RBuf</codeph> class itself

is involved in allocating, freeing and resizing this buffer. </p> <p>An <codeph>RBuf</codeph> object

can: </p> <ul>

<li id="GUID-38116609-9E75-57B4-9F34-FEC8AD3AA285"><p>be placed on the program

stack. </p> </li>

<li id="GUID-FD4007BC-6EA8-5DC0-B61E-59B2BA17B5C2"><p>be a member of another

'C' type class. </p> </li>

</ul> <p>An <codeph>RBuf</codeph> object cannot be a member of a 'T' type

class. </p> <p>See also <xref href="GUID-2458916B-55B2-5E08-A825-4EBDB3503E67.dita">Class

types</xref>. </p> <p>The default constructor does not allocate a buffer,

and means that, by default, the object represents no data. In descriptor terminology,

its length is zero and its maximum length is zero. </p> <p>Before an <codeph>RBuf</codeph> can

hold any data, you need to create the buffer. </p> <ul>

<li id="GUID-8BD20341-B902-5BD2-B121-3596432F4CC9"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-A15FC714-C2D3-51F9-A336-4043F9F6DA1C">Simple construction</xref>  </p> </li>

<li id="GUID-7EFD2DA7-C50D-54E8-9343-FC26F07387CD"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-82460E76-D738-51BD-AC7F-29C2CA54C597">More advanced construction</xref>  </p> </li>

<li id="GUID-3A9847B8-8741-5543-B5B2-D7FEB1EB3C4A"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-19A5BFF9-0B7E-54C1-BC27-2F69B65FAC47">Creating an RBuf from an existing descriptor</xref>  </p> </li>

<li id="GUID-BDE8E0A0-0FF6-5BF2-B276-9B9750DDA383"><p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-2C934B0F-97D7-5118-A6C4-7CE375F6E0F7">Creating an RBuf by transferring ownership of a pre-existing buffer</xref>  </p> </li>

</ul> <p id="GUID-A15FC714-C2D3-51F9-A336-4043F9F6DA1C"><b>Simple construction</b> </p> <p>The

simplest way to create the buffer is to use the <codeph>Create()</codeph> or

the <codeph>CreateL()</codeph> member functions of <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> [See <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-E5E4895B-4BA2-3EB1-AB7E-D676374F12E2"><apiname>RBuf16::Create()</apiname></xref> and <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-AE30A4E2-0F85-32F3-A4A7-3A8FF8A5B856"><apiname>RBuf16::CreateL()</apiname></xref>]. </p> <p>For example, the following code fragment constructs a resizable

buffer descriptor that can hold up to 15 data items. In descriptor terminology,

this means that the maximum length is set to 15. The current length of the

descriptor is set to zero, i.e. it contains no data. </p> <codeblock id="GUID-CA817431-E554-5BBA-994F-BDE6FD30B802" xml:space="preserve">RBuf buf;

...

buf.CreateL(15);

...</codeblock> <p>Note that <codeph>CreateL()</codeph> is similar to <codeph>Create()</codeph>,

but leaves if memory cannot be allocated. </p> <p id="GUID-82460E76-D738-51BD-AC7F-29C2CA54C597"><b>More advanced construction</b> </p> <p>A

variation on the simple creation technique is to use the <codeph>CreateMax()</codeph> or

the <codeph>CreateMaxL()</codeph> member functions of <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> [See <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-E5E4895B-4BA2-3EB1-AB7E-D676374F12E2"><apiname>RBuf16::Create()</apiname></xref> and <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-AE30A4E2-0F85-32F3-A4A7-3A8FF8A5B856"><apiname>RBuf16::CreateL()</apiname></xref>]. </p> <p>These functions not only allocate the buffer, but set the current

length of the data to be the same as the maximum length. For example: </p> <codeblock id="GUID-C2FA200E-5D22-5A6D-B192-04B83509D9ED" xml:space="preserve">RBuf buf;

...

buf.CreateMaxL(15);

...</codeblock> <p>No data has been assigned to the descriptor, and in effect

it contains "arbitrary" data. However, this can be useful in cases where the

descriptor needs to have a current length before calling another function.

For example, you might want a buffer of 16 bytes initialised to binary zeroes: </p> <codeblock id="GUID-C0B7F0CA-A5D9-5E9E-8DEE-C8BB983B5D4F" xml:space="preserve">RBuf8 buf;

...

buf.CreateMaxL(15);

buf.Fillz();

...</codeblock> <p> <codeph>FillZ()</codeph> provided by the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> base

class, sets the data to binary zeroes for the length of the descriptor, 15

bytes in this example. Note that we have explicitly used the 8-bit variant

here. </p> <p>There are other ways of achieving this, but this is an economical

technique. </p> <p id="GUID-19A5BFF9-0B7E-54C1-BC27-2F69B65FAC47"><b>Creating an RBuf from an

existing descriptor</b> </p> <p>A common requirement is to create an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> and

to copy the data from an existing descriptor of any type. <codeph>RBuf</codeph> provides

variants of <codeph>Create()</codeph> and <codeph>CreateL()</codeph> to do

this. </p> <p>In the following code fragment, a <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref> descriptor

is passed to a function, which then passes it to this <codeph>CreateL()</codeph> variant.

The source descriptor has a maximum length of 15, which means that the <codeph>RBuf</codeph> buffer

is allocated so that the <codeph>RBuf</codeph> maximum length is also 15. </p> <p>The

content of the source descriptor is copied into the <codeph>RBuf</codeph>,

and the length of the <codeph>RBuf</codeph> (i.e. the length of data that

the descriptor represents) is set to be the same as that of the source descriptor

- in this case 11. </p> <codeblock id="GUID-4961B664-D22A-5086-97B4-C52E8EB96101" xml:space="preserve">_LIT(KSampleText,"Hello World");

...

TBuf<15> sampletext(KSampleText);

FuncL(sampletext);

...

void FuncL(TDesC& aSource)

    {

    RBuf buf;

    buf.CreateL(aSource);

    ...

    }

</codeblock> <p>The following code fragment constructs a resizable buffer

descriptor and copies data from a source descriptor. The length of data copied

is limited by the value of the second parameter. If this is less than the

length of the source descriptor, then only this length of data is copied.

The buffer allocated is large enough to contain data of length specified by

this second parameter. </p> <p>This is often used in cases where the length

of the source data is not easily predictable, and it is important to limit

the size of the <codeph>RBuf</codeph> buffer created. </p> <p>There are two

possibilities in this code fragment : </p> <ul>

<li id="GUID-90C4F9FE-BE4B-52B1-96F6-89803743D065"><p>if the length of <codeph>aSource</codeph> is

20, then the maximum length of <codeph>buf</codeph> is limited to 10, only

half the data in <codeph>aSource</codeph> is copied, and the length of <codeph>buf</codeph> is

set to 10. </p> </li>

<li id="GUID-1FF37B48-27C9-5B60-8443-46633F609548"><p>if the length of <codeph>aSource</codeph> is

8, then the maximum length of <codeph>buf</codeph> is still set to 10; all

8 items are copied, and the length of <codeph>buf</codeph> is set to 8. </p> </li>

</ul> <codeblock id="GUID-A7309735-947B-57AF-9EA3-F2721EBFDDBD" xml:space="preserve">void FuncL(TDesC&amp; aSource)

    {

    RBuf buf;

    ...

    buf.CreateL(aSource,10);

    ...

    }

</codeblock> <p id="GUID-2C934B0F-97D7-5118-A6C4-7CE375F6E0F7"><b>Creating an RBuf by transferring

ownership of a pre-existing buffer</b> </p> <p>An important technique is to

create an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> and transfer ownership of existing allocated

memory to it. This allows any data in that block of memory to be managed through

the <codeph>RBuf</codeph>. </p> <p>There are three main cases to consider: </p> <ul>

<li id="GUID-E5C30864-1E72-54EC-B321-3A5F27D5A590"><p>transferring ownership

of a preexisting heap descriptor, an <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> type. </p> </li>

<li id="GUID-9E7CC922-7B86-5044-A5D7-CFCB76617312"><p>transferring ownership

of allocated memory </p> </li>

<li id="GUID-45EDF081-0E89-50EE-96D7-4E2FF28993B3"><p>transferring ownership

of the buffer owned by a different <codeph>RBuf</codeph>. </p> </li>

</ul> <p id="GUID-11BEB9E8-CE72-5DF8-869E-2C2FF9E43A35"><b> Transferring ownership

of an HBufC</b> </p> <p>This is a mechanism you would use if an existing API

returned an <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>, and you wanted to deal with its data

through an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> instead. </p> <p>The following code fragment

shows how this could be done. Note that the <codeph>HBufC</codeph> pointer

is passed to the <codeph>RBuf</codeph> constructor. </p> <p>Following construction,

ownership of the heap descriptor has been passed to the <codeph>RBuf</codeph> object.

In descriptor terminology, the maximum length of the <codeph>RBuf</codeph> is

15, and its length is 11, reflecting the state of the original <codeph>HBufC</codeph> object. </p> <p>You

can now manipulate any data that may have been assigned to the original <codeph>HBufC</codeph>,

through the functions in the <codeph>RBuf</codeph> base classes. </p> <codeblock id="GUID-C5351B54-85D9-5E98-A781-F9B00A06A87D" xml:space="preserve">HBufC* hptr;

_LIT(KSampleText,"Hello World");

...

hptr = HBufC::NewL(15);    // Creates a heap descriptor which can hold up

...                        // to 15 data items. The current length is zero.

*hptr = KSampleText;     // Assigns some data to the heap descriptor.

...                        // The current length of the heap descriptor is now 11.

RBuf buf(hptr);            // Ownership of the heap descriptor is passed

...                        // to the RBuf during construction of the RBuf.

</codeblock> <p>There is an alternative technique that allows you to assign

ownership of the <codeph>HBufC</codeph>  <i>after</i> construction of the <codeph>RBuf</codeph> using

the <codeph>Assign()</codeph> function. This allows you to reuse the same <codeph>RBuf</codeph> object.

For example: </p> <codeblock id="GUID-DE70696E-3E46-5377-8A10-6141BF58DB1B" xml:space="preserve">HBufC* hptr;

_LIT(KSampleText,"Hello World");

...

hptr = HBufC::NewL(15);    // Creates a heap descriptor which can hold up

...                        // to 15 data items. The current length is zero.

*hptr = KSampleText;     // Assigns some data to the heap descriptor.

...                        // The current length of the heap descriptor is now 11.

RBuf buf;

...

buf.Assign(hptr);        // Ownership of the heap descriptor is passed

...                        // to the RBuf after construction of the RBuf.

</codeblock> <p>Once ownership has been transferred, you must not access the

data through the original <codeph>HBufC</codeph> pointer. </p> <p>There is

no mechanism for reversing the transfer of ownership. The freeing of the buffer

can only be done through the <codeph>RBuf</codeph>. See <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita#GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A/GUID-A6368F43-9A67-5583-B279-FE68B8CADEC4">Freeing the buffer</xref>. </p> <p><b>Transferring

ownership of allocated memory</b> </p> <p>In the following code fragment, <codeph>ptr</codeph> is

assumed to contain the address of memory previously allocated. The code fragment

shows how ownership of this memory can be transferred to the <codeph>RBuf</codeph>. </p> <codeblock id="GUID-B9FCCFE5-A448-598A-A1F2-DAEB1563274D" xml:space="preserve">TUint16* ptr;

TInt length(32);

...                // Assume memory of length 32 has been allocated

                // and its address stored in ptr.

RBuf buf;

...

buf.Assign(ptr,length);

...                // The memory passed to the descriptor becomes the

                // descriptor's buffer. In descriptor terminology,

                // the maximum length of the RBuf is 32; its length

                // is zero, meaning that the descriptor represents

                // no data.

</codeblock> <p><b> Transferring

ownership of the buffer owned by a different RBuf</b> </p> <p>In the following

code fragment, an <codeph>RBuf</codeph> is created, a buffer created for it,

and then ownership is transferred to another <codeph>RBuf</codeph>. </p> <codeblock id="GUID-4A96EC93-A868-5463-8FED-E849BF0B7A00" xml:space="preserve">RBuf bufSource;

RBuf bufTarget;

...

bufSource.CreateL(15);    // Creates memory buffer for the descriptor

                        // that can hold up to 15 data items. In descriptor

                        // terminology, the maximum length is set to 15 and

                        // the current length is set to 0.

bufTarget.Assign(bufSource); // Transfers ownership of the memory buffer

                             // to the bufTarget descriptor.

...</codeblock> </section>

<section id="GUID-2B23F296-D414-5ABD-82CA-DDCEE2F48459"><title>Re-allocating

the memory buffer</title> <p>You can change the size of the memory buffer,

by using the <codeph>ReAlloc()</codeph> or <codeph>ReAllocL()</codeph> member

functions of <codeph>RBuf</codeph>. </p> <p>It does not matter how the original

buffer was allocated, whether directly via <codeph>Create()</codeph>, <codeph>CreateL()</codeph>, <codeph>CreateMax()</codeph> or <codeph>CReateMaxL()</codeph>, or by transfer of ownership of an existing buffer (and this includes transfer

from an <codeph>HBufC</codeph>). You do this if you intend to increase (or

significantly decrease) the amount of data that the descriptor is to represent.

Remember that the amount of memory allocated to the buffer is not automatically

changed in response to changes in the amount of data. </p> <p>In the following

code fragment, an <codeph>RBuf</codeph> is created by copying from an existing

descriptor. It is then reallocated so that its maximum length is doubled.

Error conditions, such as out-of-memory conditions are ignored. </p> <codeblock id="GUID-198E0563-2A7E-52B1-A46E-8A1AD5263234" xml:space="preserve">_LIT(KSampleText,"Hello World");

...

TBuf<15> sampletext(KSampleText);

FuncL(sampletext);

...

void FuncL(TDesC& aSource)

    {

    RBuf buf;

    Tint max;

    buf.CreateL(aSource);    // max size is 15, length is 11.

    max = buf.MaxLength() * 2;    

    buf.ReallocL(max);        // max size is now 30, but length is still 11.

    ...

    }

</codeblock> </section>

<section id="GUID-A6368F43-9A67-5583-B279-FE68B8CADEC4"><title>Freeing the

buffer</title> <p>You can free the memory buffer by calling <codeph>ReAlloc()</codeph> or <codeph>ReAllocL()</codeph> and

passing a zero value. </p> <codeblock id="GUID-DCC63874-8DAF-530A-9BA4-F7559E773BEC" xml:space="preserve">_LIT(KSampleText,"Hello World");

...

TBuf<15> sampletext(KSampleText);

FuncL(sampletext);

...

void FuncL(TDesC& aSource)

    {

    RBuf buf;

    buf.CreateL(aSource);    // max size is 15, length is 11.

    buf.ReallocL(0);        // max size is now 0, length is 0, the memory

                            // buffer has been freed, and data

                            // has been thrown away.

    ...

    }

</codeblock> <p>You can also use the <codeph>Close()</codeph> member function

of <codeph>RBuf</codeph>. For example: </p> <codeblock id="GUID-2D298A5F-FFB4-584C-9D9C-58A95A88E078" xml:space="preserve">_LIT(KSampleText,"Hello World");

...

TBuf<15> sampletext(KSampleText);

FuncL(sampletext);

...

void FuncL(TDesC& aSource)

    {

    RBuf buf;

    buf.CreateL(aSource);    // max size is 15, length is 11.

    buf.Close();            // max size is now 0, length is 0, the memory

                            // buffer has been freed, and data

                            // has been thrown away.

    ...

    }

</codeblock> </section>

<section id="GUID-7ECF515D-D538-5F6C-B2A0-88C1B4E3505C"><title>Cleanup rules</title> <ul>

<li id="GUID-38476044-1EB5-5488-93A0-CB2C7D2D38B4"><p>To avoid memory leaks

when the <codeph>RBuf</codeph> object is placed on the stack, you should use

the following programming pattern: </p> <codeblock id="GUID-1B602EF6-BAAC-5F4F-AFF2-B8C2102687D5" xml:space="preserve">{

RBuf buf;

buf.CleanupClosePushL();

...                                 // Use the RBuf

CleanupStack::PopAndDestroy()    //remove from cleanup stack

                                // and free the buffer to avoid memory 

}</codeblock> <p>The <codeph>CleanupClosePushL()</codeph> function puts a

cleanup item onto the cleanup stack. The effect of this is to cause the class's <xref href="GUID-01D2AF56-21E1-3FF3-BF86-0C356A1658EF.dita"><apiname>Close()</apiname></xref> function

to be called in the event of a leave occurring. In its turn, <codeph>Close()</codeph> simply

frees off the buffer. </p> </li>

<li id="GUID-E285FB76-1079-5F34-8CC5-CE1A5AC39E70"><p>If an <codeph>RBuf</codeph> is

a member of a class, then that class's destructor must remember to call either

: <codeph>ReAllocL(0)</codeph> or <codeph>Close()</codeph>. </p> </li>

<li id="GUID-4B09CAD1-6E16-5FB6-9574-277CE75A48C7"><p>An <codeph>RBuf</codeph> can

be reused, but you must remember to call either : <codeph>ReAllocL(0)</codeph> or <codeph>Close()</codeph> before

you assign other memory or another <codeph>HBufC</codeph>. Failure to do this

will result in a memory leak. </p> </li>

<li id="GUID-433E518F-A96F-5EB8-A2BF-DC4D213A2CF0"><p>You should not use an <codeph>RBuf</codeph> as

a member of a 'T' type class. See <xref href="GUID-2458916B-55B2-5E08-A825-4EBDB3503E67.dita">Class

types</xref>. </p> </li>

</ul> </section>

<section id="GUID-6732B0A9-4E6E-50A8-9C4F-ADB2BB8FBAEF"><title>Replacing and

modifying data</title> <p>Data in an <codeph>RBuf</codeph> descriptor can

be replaced. It can also be modified using the standard functionality provided

by the <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> base class. </p> <codeblock id="GUID-A507DCDF-F440-51B0-B6CE-86993FE5D7AB" xml:space="preserve">_LIT(KSampleText,"Hello World");

...

TBuf<15> sampletext(KSampleText);

FuncL(sampletext);

...

void FuncL(TDesC& aSource)

    {

    RBuf buf;

    buf.CreateL(aSource.MaxLength());    // Create the RBuf.

    buf = aSource;                        // Copy "Hello World" using the assignment

                                        // operator.

    buf.Delete(1,1);                    // Delete the 1st character.

    ...

    buf.Close();

    }

</codeblock> </section>

</conbody></concept>