<?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.dita">Descriptors
Cookbook</xref> at the Symbian Foundation.</p></li>
<li><p><xref 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>