<?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> <p><b>Example code</b></p><p>For
examples, see:</p><ul>
<li><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita">Descriptor
Example Code</xref></p></li>
<li><p><xref href="http://developer.symbian.org/wiki/index.php/Descriptors_Cookbook" scope="external">Descriptors Cookbook</xref> at the Symbian Foundation.</p></li>
<li><p><xref format="html" href="http://www.forum.nokia.com/info/sw.nokia.com/id/9c61aadd-8ae7-4c19-9484-2b165f0cb55e/S60_Platform_Descriptor_Example_v2_1_en.zip.html" scope="external">S60 Platform: Descriptor Example v2.1</xref> on Forum
Nokia.</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-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>