<?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-0817AD1D-58CF-5108-ACBF-26DFD4BA395E" xml:lang="en"><title>Descriptors
Overview</title><shortdesc>This document provides an overview of descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-B9DAC214-E22A-4E05-AC39-CE994E87C8CA"><title>Purpose</title> <p>Manipulates string and data buffers. </p> </section>
<section id="GUID-A49ACEBD-15DA-4525-BAA7-C15635518D52"><title>Description</title> <p>Descriptors are a family of classes
that are used in Symbian platform for string handling. They are used in preference
to NULL-terminated C strings. The same classes are used for general binary
data. </p> <p>The basic classification of descriptor types is given below.
Concrete descriptor classes implement variations on these basic types for
different data widths and for different abilities to modify the data. The
names of the concrete classes follow certain naming conventions that modify
the basic name given in the table. </p> <p><b>Basic
classification</b> </p> <table id="GUID-F074AE70-AC9D-53E5-AD5F-BB391CD32831">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<tbody>
<row>
<entry><p> <b>Type</b>  </p> </entry>
<entry><p> <b>Description</b>  </p> </entry>
<entry><p> <b>Basic name</b>  </p> </entry>
</row>
<row>
<entry><p>abstract </p> </entry>
<entry><p>Base interface: allows descriptors of different types to be use
polymorphically </p> </entry>
<entry><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>buffer </p> </entry>
<entry><p>Stack based: contains the data as part of itself. Buffer descriptors
have a maximum length set at compile time. </p> </entry>
<entry><p> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>pointer </p> </entry>
<entry><p>Refer to data stored elsewhere that is not owned by the descriptor </p> </entry>
<entry><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref>  </p> </entry>
</row>
<row>
<entry><p>heap </p> </entry>
<entry><p>Refers to data stored on the heap that is owned by the descriptor.
The maximum length of this data can be set and changed dynamically. </p> </entry>
<entry><p> <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>  </p> <p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>  </p> </entry>
</row>
</tbody>
</tgroup>
</table> <p><b>Width</b> </p> <p>Descriptor
types can store 8-bit or 16-bit data. These types are indicated by the convention
of appending 8 or 16 on the basic name, e.g. <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes16</apiname></xref>. In
practice, the basic names correspond to 16-bit types, for example <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref> is
defined to be <xref href="GUID-EF25E407-26DF-3D97-B725-2DD0345975BA.dita"><apiname>TBuf16</apiname></xref>. </p> <p><b>Modifiable and non-modifiable</b> </p> <p>Modifiable descriptor types
have an interface that allows callers to alter their contents, such as appending
characters. </p> <p>Non-modifiable descriptor types can have their contents
reset, but not modified. The convention is for non-modifiable types to append
a C on the basic name, e.g. <xref href="GUID-4D64E4B7-6BEE-3900-A115-460FE5B2D79E.dita"><apiname>TBufC</apiname></xref>. </p> <p>Heap type descriptors
are an exceptional case: they are available only in the non-modifiable form,
but can, nevertheless, be modified through use of a pointer: see <codeph>HBufC::Des()</codeph>.
Alternatively, you can use the <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> descriptor, which is
simpler to use than <codeph>HBufC</codeph>. The general rule is: </p> <ul>
<li id="GUID-82384688-B4EB-545B-869D-9BF5C0BC3DD2"><p>use <codeph>HBufC</codeph> for
data that rarely changes. </p> </li>
<li id="GUID-A15A3A8B-4B8A-58FB-A972-91242331502D"><p>Use <codeph>RBuf</codeph> for
data that changes frequently. </p> </li>
</ul> </section>
<section id="GUID-72EDBF0F-A0EB-4D93-85D0-55D0EA4740BB"><title>See also</title> <p> <xref href="GUID-EA98D77C-743B-5BA5-B131-A327B12A099C.dita">Character
Representation Of Real Numbers Overview</xref>  </p> <p> <xref href="GUID-949EE53F-8D85-50B8-B8BA-541B6BF0DAC4.dita">Descriptor
Arrays Overview</xref>  </p> <p> <xref href="GUID-C15F56E3-753C-55CA-B3EF-63B2D139BCE4.dita">Dynamic
Buffers Overview</xref>  </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals
Overview</xref>  </p> </section>
</conbody></concept>