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