<?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>