<?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-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE" xml:lang="en"><title>Heap

descriptors</title><shortdesc>Describes heap descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A heap descriptor provides a fixed length buffer, allocated on the heap,

to contain and access data. The data is part of the descriptor object. </p>

<p>The data contained in a heap descriptor can be accessed, but not changed,

through this descriptor. The data can, however, be completely replaced using

the assignment operators. </p>

<p>A heap descriptor also has the important property that it can be made larger

or smaller, changing the size of the descriptor's buffer. This is achieved

by reallocating the descriptor. Unlike the behaviour of dynamic buffers, reallocation

is not done automatically. </p>

<p>Data is accessed through functions provided by the base class. </p>

<p>A heap descriptor is supplied in two variants: </p>

<ul>

<li id="GUID-7FE093CF-5C0A-58F4-8C5E-63465F1B1B64"><p>the 16 bit variant,

a <codeph>HBufC16</codeph>, to contain Unicode strings. </p> </li>

<li id="GUID-2F6606E5-E985-58A2-86DE-DCC69C137F50"><p>the 8 bit variant, a <codeph>HBufC8</codeph>,

to contain non-Unicode strings and binary data. </p> </li>

</ul>

<p>There is also a build independent type, <codeph>HBufC</codeph>. This is

the type which is most commonly used in program code; the appropriate variant

is selected at build time. </p>

<p>An explicit 8 bit variant is chosen for binary data. An explicit 16 bit

variant is rarely used. </p>

<p>The base class, <codeph>TDesC</codeph>, contains a data member which holds

the length of the data. The following drawing shows the layout of a <codeph>HBufC</codeph> object

initialised with the string of five characters representing the English word

"Hello". The descriptor object is allocated on the heap. </p>

<p>Although it is not possible to change the data in the descriptor directly

through the descriptor member functions, it <i>is</i> possible to do this

indirectly by using the <codeph>Des()</codeph> member function of <codeph>HBufC</codeph> to

first create a modifiable <xref href="GUID-2DDAAD1C-D9EB-5741-B6AE-2383646E0EDB.dita">pointer

descriptor</xref>, a <codeph>TPtr</codeph> type, and then to use <i>this</i> descriptor's

member functions. For this reason, heap descriptors are best suited for data

that rarely changes. For data that changes frequently, it is much better to

use the <xref href="GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita">resizable buffer

descriptor</xref>. </p>

<fig id="GUID-975888DA-9685-504E-B089-F5F632729921">

<image href="GUID-10C32642-CF1C-5C60-A81B-9D65F03A45C4_d0e220786_href.png" placement="inline"/>

<p>Example of a Heap descriptor</p>

</fig>