1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E" xml:lang="en"><title>Descriptors

    13 Overview</title><shortdesc>This document provides an overview of descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-B9DAC214-E22A-4E05-AC39-CE994E87C8CA"><title>Purpose</title> <p>Manipulates

    15 string and data buffers. </p> </section>

    16 <section id="GUID-A49ACEBD-15DA-4525-BAA7-C15635518D52"><title>Description</title> <p>Descriptors

    17 are a family of classes that are used in Symbian platform for string handling.

    18 They are used in preference to NULL-terminated C strings. The same classes

    19 are used for general binary data. </p> <p>The basic classification of descriptor

    20 types is given below. Concrete descriptor classes implement variations on

    21 these basic types for different data widths and for different abilities to

    22 modify the data. The names of the concrete classes follow certain naming conventions

    23 that modify the basic name given in the table. </p> <p><b>Basic

    24 classification</b> </p> <table id="GUID-F074AE70-AC9D-53E5-AD5F-BB391CD32831">

    25 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

    26 <tbody>

    27 <row>

    28 <entry><p> <b>Type</b>  </p> </entry>

    29 <entry><p> <b>Description</b>  </p> </entry>

    30 <entry><p> <b>Basic name</b>  </p> </entry>

    31 </row>

    32 <row>

    33 <entry><p>abstract </p> </entry>

    34 <entry><p>Base interface: allows descriptors of different types to be use

    35 polymorphically </p> </entry>

    36 <entry><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref>  </p> </entry>

    37 </row>

    38 <row>

    39 <entry><p>buffer </p> </entry>

    40 <entry><p>Stack based: contains the data as part of itself. Buffer descriptors

    41 have a maximum length set at compile time. </p> </entry>

    42 <entry><p> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref>  </p> </entry>

    43 </row>

    44 <row>

    45 <entry><p>pointer </p> </entry>

    46 <entry><p>Refer to data stored elsewhere that is not owned by the descriptor </p> </entry>

    47 <entry><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref>  </p> </entry>

    48 </row>

    49 <row>

    50 <entry><p>heap </p> </entry>

    51 <entry><p>Refers to data stored on the heap that is owned by the descriptor.

    52 The maximum length of this data can be set and changed dynamically. </p> </entry>

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

    54 </row>

    55 </tbody>

    56 </tgroup>

    57 </table> <p><b>Width</b> </p> <p>Descriptor

    58 types can store 8-bit or 16-bit data. These types are indicated by the convention

    59 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

    60 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

    61 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

    62 have an interface that allows callers to alter their contents, such as appending

    63 characters. </p> <p>Non-modifiable descriptor types can have their contents

    64 reset, but not modified. The convention is for non-modifiable types to append

    65 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

    66 are an exceptional case: they are available only in the non-modifiable form,

    67 but can, nevertheless, be modified through use of a pointer: see <codeph>HBufC::Des()</codeph>.

    68 Alternatively, you can use the <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> descriptor, which is

    69 simpler to use than <codeph>HBufC</codeph>. The general rule is: </p> <ul>

    70 <li id="GUID-82384688-B4EB-545B-869D-9BF5C0BC3DD2"><p>use <codeph>HBufC</codeph> for

    71 data that rarely changes. </p> </li>

    72 <li id="GUID-A15A3A8B-4B8A-58FB-A972-91242331502D"><p>Use <codeph>RBuf</codeph> for

    73 data that changes frequently. </p> </li>

    74 </ul> </section>

    75 <section id="GUID-72EDBF0F-A0EB-4D93-85D0-55D0EA4740BB"><title>See also</title> <p> <xref href="GUID-EA98D77C-743B-5BA5-B131-A327B12A099C.dita">Character Representation

    76 Of Real Numbers Overview</xref>  </p> <p> <xref href="GUID-C15F56E3-753C-55CA-B3EF-63B2D139BCE4.dita">Dynamic

    77 Buffers Overview</xref>  </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals

    78 Overview</xref>  </p> </section>

    79 </conbody></concept>