1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE" xml:lang="en"><title>Heap

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

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

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

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

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

    18 the assignment operators. </p>

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

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

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

    22 is not done automatically. </p>

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

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

    25 <ul>

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

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

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

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

    30 </ul>

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

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

    33 is selected at build time. </p>

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

    35 variant is rarely used. </p>

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

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

    38 initialised with the string of five characters representing the English word

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

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

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

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

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

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

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

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

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

    48 descriptor</xref>. </p>

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

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

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

    52 </fig>

    53 </conbody></concept>