Symbian3/SDK/Source/GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita
changeset 7 51a74ef9ed63
child 8 ae94777fff8f
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,53 @@
+<?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_d0e224523_href.png" placement="inline"/>
+<p>Example of a Heap descriptor</p>
+</fig>
+</conbody></concept>
\ No newline at end of file