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