|
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> <p><b>Example code</b></p><p>For |
|
75 examples, see:</p><ul> |
|
76 <li><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita">Descriptor Example |
|
77 Code</xref></p></li> |
|
78 <li><p><xref href="http://developer.symbian.org/wiki/index.php/Descriptors_Cookbook.dita">Descriptors |
|
79 Cookbook</xref> at the Symbian Foundation.</p></li> |
|
80 <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> |
|
81 </ul></section> |
|
82 <section id="GUID-72EDBF0F-A0EB-4D93-85D0-55D0EA4740BB"><title>See also</title> <p> <xref href="GUID-EA98D77C-743B-5BA5-B131-A327B12A099C.dita">Character Representation |
|
83 Of Real Numbers Overview</xref> </p> <p> <xref href="GUID-C15F56E3-753C-55CA-B3EF-63B2D139BCE4.dita">Dynamic |
|
84 Buffers Overview</xref> </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals |
|
85 Overview</xref> </p> </section> |
|
86 </conbody></concept> |