7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E" xml:lang="en"><title>Descriptors |
12 <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> |
13 Overview</title><shortdesc>This document provides an overview of descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
13 <section id="GUID-B9DAC214-E22A-4E05-AC39-CE994E87C8CA"><title>Purpose</title> <p>Manipulates string and data buffers. </p> </section> |
14 <section id="GUID-B9DAC214-E22A-4E05-AC39-CE994E87C8CA"><title>Purpose</title> <p>Manipulates |
14 <section id="GUID-A49ACEBD-15DA-4525-BAA7-C15635518D52"><title>Description</title> <p>Descriptors are a family of classes that are used in Symbian |
15 string and data buffers. </p> </section> |
15 platform for string handling. They are used in preference to NULL-terminated |
16 <section id="GUID-A49ACEBD-15DA-4525-BAA7-C15635518D52"><title>Description</title> <p>Descriptors |
16 C strings. The same classes are used for general binary data. </p> <p>The basic classification of descriptor types is given below. |
17 are a family of classes that are used in Symbian platform for string handling. |
17 Concrete descriptor classes implement variations on these basic types |
18 They are used in preference to NULL-terminated C strings. The same classes |
18 for different data widths and for different abilities to modify the |
19 are used for general binary data. </p> <p>The basic classification of descriptor |
19 data. The names of the concrete classes follow certain naming conventions |
20 types is given below. Concrete descriptor classes implement variations on |
20 that modify the basic name given in the table. </p> <p><b>Basic classification</b> </p> <table id="GUID-F074AE70-AC9D-53E5-AD5F-BB391CD32831"> |
21 these basic types for different data widths and for different abilities to |
21 <tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/> |
22 modify the data. The names of the concrete classes follow certain naming conventions |
22 <colspec colname="col2"/> |
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> |
23 <tbody> |
27 <row> |
24 <row> |
28 <entry><p> <b>Type</b> </p> </entry> |
25 <entry><p> <b>Type</b> </p> </entry> |
29 <entry><p> <b>Description</b> </p> </entry> |
26 <entry><p> <b>Description</b> </p> </entry> |
30 <entry><p> <b>Basic name</b> </p> </entry> |
27 <entry><p> <b>Basic name</b> </p> </entry> |
31 </row> |
28 </row> |
32 <row> |
29 <row> |
33 <entry><p>abstract </p> </entry> |
30 <entry><p>abstract </p> </entry> |
34 <entry><p>Base interface: allows descriptors of different types to be use |
31 <entry><p>Base interface: allows descriptors of different types to |
35 polymorphically </p> </entry> |
32 be use polymorphically </p> </entry> |
36 <entry><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> </p> </entry> |
33 <entry><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> </p> </entry> |
37 </row> |
34 </row> |
38 <row> |
35 <row> |
39 <entry><p>buffer </p> </entry> |
36 <entry><p>buffer </p> </entry> |
40 <entry><p>Stack based: contains the data as part of itself. Buffer descriptors |
37 <entry><p>Stack based: contains the data as part of itself. Buffer |
41 have a maximum length set at compile time. </p> </entry> |
38 descriptors 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> |
39 <entry><p> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref> </p> </entry> |
43 </row> |
40 </row> |
44 <row> |
41 <row> |
45 <entry><p>pointer </p> </entry> |
42 <entry><p>pointer </p> </entry> |
46 <entry><p>Refer to data stored elsewhere that is not owned by the descriptor </p> </entry> |
43 <entry><p>Refer to data stored elsewhere that is not owned by the |
|
44 descriptor </p> </entry> |
47 <entry><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> </p> </entry> |
45 <entry><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref> </p> </entry> |
48 </row> |
46 </row> |
49 <row> |
47 <row> |
50 <entry><p>heap </p> </entry> |
48 <entry><p>heap </p> </entry> |
51 <entry><p>Refers to data stored on the heap that is owned by the descriptor. |
49 <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> |
50 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> |
51 <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> |
52 </row> |
55 </tbody> |
53 </tbody> |
56 </tgroup> |
54 </tgroup> |
57 </table> <p><b>Width</b> </p> <p>Descriptor |
55 </table> <p><b>Width</b> </p> <p>Descriptor types can store 8-bit or 16-bit data. |
58 types can store 8-bit or 16-bit data. These types are indicated by the convention |
56 These types are indicated by the convention of appending 8 or 16 on |
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 |
57 the basic name, e.g. <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes16</apiname></xref>. In practice, the basic |
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 |
58 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 |
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 |
59 types have an interface that allows callers to alter their contents, |
62 have an interface that allows callers to alter their contents, such as appending |
60 such as appending characters. </p> <p>Non-modifiable descriptor types |
63 characters. </p> <p>Non-modifiable descriptor types can have their contents |
61 can have their contents reset, but not modified. The convention is |
64 reset, but not modified. The convention is for non-modifiable types to append |
62 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 |
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 |
63 case: they are available only in the non-modifiable form, but can, |
66 are an exceptional case: they are available only in the non-modifiable form, |
64 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, |
67 but can, nevertheless, be modified through use of a pointer: see <codeph>HBufC::Des()</codeph>. |
65 which is simpler to use than <codeph>HBufC</codeph>. The general rule |
68 Alternatively, you can use the <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> descriptor, which is |
66 is: </p> <ul> |
69 simpler to use than <codeph>HBufC</codeph>. The general rule is: </p> <ul> |
67 <li id="GUID-82384688-B4EB-545B-869D-9BF5C0BC3DD2"><p>Use <codeph>HBufC</codeph> for data that rarely changes. </p> </li> |
70 <li id="GUID-82384688-B4EB-545B-869D-9BF5C0BC3DD2"><p>use <codeph>HBufC</codeph> for |
68 <li id="GUID-A15A3A8B-4B8A-58FB-A972-91242331502D"><p>Use <codeph>RBuf</codeph> for data that changes frequently. </p> </li> |
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 |
69 </ul> <p><b>Example code</b></p><p>For |
75 examples, see:</p><ul> |
70 examples, see:</p><ul> |
76 <li><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita">Descriptor Example |
71 <li><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita">Descriptor |
77 Code</xref></p></li> |
72 Example Code</xref></p></li> |
78 <li><p><xref href="http://developer.symbian.org/wiki/index.php/Descriptors_Cookbook.dita">Descriptors |
73 <li><p><xref href="http://developer.symbian.org/wiki/index.php/Descriptors_Cookbook" scope="external">Descriptors Cookbook</xref> at the Symbian Foundation.</p></li> |
79 Cookbook</xref> at the Symbian Foundation.</p></li> |
74 <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 |
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> |
75 Nokia.</p></li> |
81 </ul></section> |
76 </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 |
77 <section id="GUID-72EDBF0F-A0EB-4D93-85D0-55D0EA4740BB"><title>See |
83 Of Real Numbers Overview</xref> </p> <p> <xref href="GUID-C15F56E3-753C-55CA-B3EF-63B2D139BCE4.dita">Dynamic |
78 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 |
84 Buffers Overview</xref> </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals |
79 Overview</xref> </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals Overview</xref> </p> </section> |
85 Overview</xref> </p> </section> |
|
86 </conbody></concept> |
80 </conbody></concept> |