|
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-E8266924-FA52-5171-BD73-423A46227A74" xml:lang="en"><title> Descriptor |
|
13 Arrays</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A descriptor array is a mechanism which allows descriptors to be aggregated |
|
15 in a convenient way. </p> |
|
16 <section><title>Introduction</title> <p>Descriptor arrays build on the behaviour |
|
17 supplied by the Dynamic Arrays API and provides normal array operations for |
|
18 inserting, appending, deleting, and accessing elements. </p> <p>There are |
|
19 two types of descriptor array, based on the way data is represented by the |
|
20 array: </p> <ul> |
|
21 <li id="GUID-798A2774-299C-5078-9F48-588AC1EE8143"><p>an array whose elements |
|
22 consist of non-modifiable pointer descriptors. </p> </li> |
|
23 <li id="GUID-D456390C-34ED-5908-B188-73F55C26559C"><p>an array whose elements |
|
24 consist of memory pointers. </p> </li> |
|
25 </ul> <p>Either array can be used to represent descriptor data. The difference |
|
26 between them is based on the way they are implemented, and this determines |
|
27 which one is most suitable for a given situation. </p> <p> <b>NOTE</b>: All |
|
28 array classes are provided in variants for narrow and wide characters (for |
|
29 example, <xref href="GUID-5C0DD165-5C23-38C0-983E-B856F9F46F12.dita"><apiname>CDesC8Array</apiname></xref> and <xref href="GUID-9EC9CD13-91FB-38F7-9E55-F41C584AC5A6.dita"><apiname>CDesC16Array</apiname></xref>). |
|
30 These concrete types can be used directly, but it is usual to use typedefs |
|
31 (for example, <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref>) that are conditionally defined |
|
32 to map to the wide or narrow characters depending on the build. Only the conditional |
|
33 types are used below. </p> <p>Descriptor arrays has three key concepts - descriptor |
|
34 array protocol (<codeph>MDesC16Array</codeph>), general descriptor array (<codeph>CDesC16Array</codeph>) |
|
35 and pointer descriptor array (<codeph>CPtrC16Array</codeph>). </p> <p><b>Descriptor |
|
36 array protocol</b> </p> <p>This array defines an interface implemented by |
|
37 all descriptor array classes, and hence provides a degree of polymorphism. |
|
38 It provides a count function, and can return a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> for |
|
39 an indexed element. </p> <p>The interface is defined by <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref>. </p> <p><b>General |
|
40 descriptor array</b> </p> <p>This array accepts elements of any descriptor |
|
41 type. For each descriptor added, it creates a new heap descriptor (<xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>) |
|
42 and copies the contents into it. </p> <p>The base class is <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref>. |
|
43 Derived classes provide storage in flat arrays (<xref href="GUID-29384669-FFCE-38FC-A005-61163D99401D.dita"><apiname>CDesCArrayFlat</apiname></xref>) |
|
44 and segmented arrays (<xref href="GUID-1B44227C-6F11-3A51-BE2C-8780319C6F72.dita"><apiname>CDesCArraySeg</apiname></xref>). </p> <p><b>Pointer |
|
45 descriptor array</b> </p> <p>This array holds only <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptor |
|
46 elements, that is, the descriptor type that points to data stored elsewhere. |
|
47 The data pointed to by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied |
|
48 or moved. </p> <p>The pointer descriptor array is <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref>. |
|
49 It implements <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref>, and can be used polymorphically |
|
50 with general descriptor arrays. </p> </section> |
|
51 <section><title>Array of non-modifiable pointer descriptor elements</title> <p>The |
|
52 array is supplied in two variants: </p> <ul> |
|
53 <li id="GUID-B55063AC-A34D-5156-B35A-085BADDD66B2"><p>the 16-bit variant <xref href="GUID-3A648EBA-DD13-31A8-863C-602D84E1913D.dita"><apiname>CPtrC16Array</apiname></xref> containing <xref href="GUID-8FE95467-D48B-3E61-9028-29C0F15F567E.dita"><apiname>TPtrC16</apiname></xref> types. </p> </li> |
|
54 <li id="GUID-E51F01E9-4956-5E0A-A422-4A5A1E7B642C"><p>the 8-bit variant <xref href="GUID-421D5F30-909F-39AC-A945-F1AE4B401E2F.dita"><apiname>CPtrC8Array</apiname></xref> containing <xref href="GUID-6DF731E4-5691-31C4-BEE0-03A3873F15EC.dita"><apiname>TPtrC8</apiname></xref> types. </p> </li> |
|
55 </ul> <p>The array is also supplied as a build independent type, <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref>. |
|
56 This is used whenever the descriptor elements are used to represent text strings. |
|
57 By using the build independent type, the appropriate variant, either 16-bit |
|
58 or 8-bit, is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro |
|
59 has been defined or not. </p> <p>Binary data always requires the 8-bit variant, |
|
60 regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit |
|
61 use of the 16-bit variant is rare. </p> <p>The elements of this type of array |
|
62 consist of non-modifiable pointer descriptors. These pointer descriptors represent |
|
63 the data of the descriptors added to the array. The following diagram illustrates |
|
64 this. The diagram is also true for <xref href="GUID-6DF731E4-5691-31C4-BEE0-03A3873F15EC.dita"><apiname>TPtrC8</apiname></xref> and <xref href="GUID-8FE95467-D48B-3E61-9028-29C0F15F567E.dita"><apiname>TPtrC16</apiname></xref>. </p> <fig id="GUID-AB7B77C5-31BC-5DD0-B1FC-D02436E18D14"> |
|
65 <title> Array of non-modifiable pointer descriptor elements |
|
66 </title> |
|
67 <image href="GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e182924_href.png" placement="inline"/> |
|
68 </fig> <p> <b>NOTE:</b> <xref href="GUID-B24BD746-98D1-3837-B834-5C12D4D516FC.dita"><apiname>delete()</apiname></xref> and <xref href="GUID-FA50BA77-E578-3652-B1FB-AD2D0523CC17.dita"><apiname>reset()</apiname></xref> removes |
|
69 the non-modifiable pointer descriptors from the array but does <b>not</b> delete |
|
70 the data or descriptors that they point to. </p> </section> |
|
71 <section><title>Array of pointer elements</title> <p>The elements of this |
|
72 type of array consist of <b>pointers</b> to heap descriptors. </p> <p>When |
|
73 a descriptor is added to this type of array, a heap descriptor is allocated, |
|
74 taking its data from the supplied descriptor. The pointer to this heap descriptor |
|
75 is added as an array element. The following diagram illustrates this. The |
|
76 diagram is also true for <xref href="GUID-2A528453-0279-3E47-838C-F8A8D29B88F1.dita"><apiname>HBufC8</apiname></xref> and <xref href="GUID-3D3D9CD7-C8FD-3F81-9CC5-1A71D4F9751E.dita"><apiname>HBufC16</apiname></xref>. </p> <fig id="GUID-D6B993E5-AF6B-5AD2-A30F-834C6815EFEF"> |
|
77 <title> Array of pointer elements </title> |
|
78 <image href="GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e182971_href.png" placement="inline"/> |
|
79 </fig> <p>There are two implementations of the array, one using a flat buffer |
|
80 and the other using a segmented buffer. </p> <p>The flat buffer implementation |
|
81 is supplied in two variants: </p> <ul> |
|
82 <li id="GUID-8E031CC3-AC57-5882-A96A-40F041543714"><p>the 16-bit variant implemented |
|
83 using a flat buffer, a <xref href="GUID-0DF28074-4B76-3767-9FD8-EADF36E3EA14.dita"><apiname>CDesC16ArrayFlat</apiname></xref>, constructed from <xref href="GUID-440FF2B4-353B-3097-A2BA-5887D10B8B23.dita"><apiname>TDesC16</apiname></xref> types. </p> </li> |
|
84 <li id="GUID-53DE0372-9FE8-55F8-A358-7062CA7FC37A"><p>the 8-bit variant implemented |
|
85 using a flat buffer, a <xref href="GUID-A774AF80-82C3-3031-A197-5625DACD60FE.dita"><apiname>CDesC8ArrayFlat</apiname></xref>, constructed from <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> types. </p> </li> |
|
86 </ul> <p>The segmented buffer implementation is supplied in two variants: </p> <ul> |
|
87 <li id="GUID-DAEB51F2-19D5-5BC8-95DA-0375AC759C57"><p>the 16-bit variant implemented |
|
88 using a segmented buffer, a <xref href="GUID-F2998F7B-DFB1-3EDA-A6FF-1F3B2065DE4D.dita"><apiname>CDesC16ArraySeg</apiname></xref>, constructed |
|
89 from <xref href="GUID-440FF2B4-353B-3097-A2BA-5887D10B8B23.dita"><apiname>TDesC16</apiname></xref> types. </p> </li> |
|
90 <li id="GUID-0880573C-40D7-5C27-A2DB-5B9FF808E670"><p>the 8-bit variant implemented |
|
91 using a segmented buffer, a <xref href="GUID-DFC1F01A-A107-3C7F-883A-6C4F11859E1C.dita"><apiname>CDesC8ArraySeg</apiname></xref>, constructed |
|
92 from <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> types. </p> </li> |
|
93 </ul> <p>Both array implementations are also supplied as build independent |
|
94 types, <xref href="GUID-29384669-FFCE-38FC-A005-61163D99401D.dita"><apiname>CDesCArrayFlat</apiname></xref> and <xref href="GUID-1B44227C-6F11-3A51-BE2C-8780319C6F72.dita"><apiname>CDesCArraySeg</apiname></xref>. |
|
95 These are used whenever the descriptors are used to represent text strings. |
|
96 By using the build independent types, the appropriate variants, either 16-bit |
|
97 or 8-bit, are selected at build time depending on whether the <codeph>_UNICODE</codeph> macro |
|
98 has been defined or not. </p> <p>Binary data always requires the 8-bit variants, |
|
99 regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit |
|
100 use of the 16-bit variants is rare. </p> <p> <b>NOTE:</b> <xref href="GUID-B24BD746-98D1-3837-B834-5C12D4D516FC.dita"><apiname>delete()</apiname></xref> and <xref href="GUID-FA50BA77-E578-3652-B1FB-AD2D0523CC17.dita"><apiname>reset()</apiname></xref> removes |
|
101 the pointers from the array and also deletes the heap descriptors that they |
|
102 point to. </p> </section> |
|
103 <section><title>Type of array to be used</title> <p>The advantages of using |
|
104 one type over the other are subtle. </p> <p>When using an array of non-modifiable |
|
105 pointer descriptors, the data represented by each <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> exists |
|
106 independently of the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> itself. The memory required |
|
107 by the array is that required to contain the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> elements. |
|
108 The data represented by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied |
|
109 or moved. On the other hand, that same data must be guaranteed to remain in |
|
110 memory if the array is to have any purpose. </p> <p>When using an array of |
|
111 pointers, a new heap descriptor is allocated for each descriptor to be added |
|
112 to the array. This increases the total memory requirements of the array. On |
|
113 the other hand, each array element is smaller because the size of a pointer |
|
114 is slightly smaller than the size of a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> object. The |
|
115 original descriptor data can also be safely discarded once it has been added |
|
116 to the array. </p> <p>This type also has the advantage that there is no commitment |
|
117 to a concrete descriptor type. </p> </section> |
|
118 <section><title>Relationship between descriptor array classes</title> <p>The |
|
119 following diagram illustrates the relationship between the descriptor array |
|
120 concrete classes and the base classes which support them. </p> <fig id="GUID-43444E8B-F2F5-539B-BA9D-EDF9B832DFD9"> |
|
121 <title> The class relationships for CDesCArrayFlat & CDesCArraySeg |
|
122 </title> |
|
123 <image href="GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e183125_href.png" placement="inline"/> |
|
124 </fig> <p> </p> <fig id="GUID-3BD4A73F-1E09-515A-9833-6D9592A98E97"> |
|
125 <title> The class relationships for CPtrCArray </title> |
|
126 <image href="GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e183136_href.png" placement="inline"/> |
|
127 </fig> </section> |
|
128 <section id="GUID-9948A6D4-19A2-58A2-B2F1-73EC577E1B0B"><title>Copying Descriptor |
|
129 Arrays </title> <p>An array of non-modifiable pointer descriptors, a <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> type, |
|
130 provides a function which can copy elements from any descriptor array. </p> <p>The |
|
131 source descriptor array must be one which satisfies the protocol defined by |
|
132 the <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref> mixin class. Add the new <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> elements |
|
133 to the <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> array to represent the source data. </p> <p>The |
|
134 implementation of the copy does not and cannot depend on the type of the source |
|
135 descriptor array,that is, whether it is a <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> type |
|
136 or a <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref> type. However, the following diagram shows |
|
137 the effect of the copy operation based on the concrete type of the source |
|
138 array. </p> <fig id="GUID-E320FF9E-CBCA-597C-AE3B-8480A0829EF7"> |
|
139 <title> Copying descriptor arrays </title> |
|
140 <image href="GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e183182_href.png" placement="inline"/> |
|
141 </fig> </section> |
|
142 <section id="GUID-009C368B-80E3-523B-BC4A-12BB90244CE1"><title>8-Bit Variant, |
|
143 16-Bit Variant and Build Independence</title> <p>Descriptor arrays are supplied |
|
144 in two variants: </p> <ul> |
|
145 <li id="GUID-7819B939-C7C0-5117-812D-B2D05D7650D4"><p>the 16-bit variant for |
|
146 16-bit descriptors. These descriptors are used for handling Unicode strings |
|
147 and double byte valued data. </p> </li> |
|
148 <li id="GUID-A1DCAB83-37F6-51ED-8AEA-0EFE361BE107"><p>the 8-bit variant for |
|
149 8-bit variant descriptors. These descriptors are used for handling non-Unicode |
|
150 strings and single byte valued data. (binary data). </p> </li> |
|
151 </ul> <p>Descriptor arrays are also supplied as build independent types. These |
|
152 are used for descriptors which are used to represent text strings. </p> <p>By |
|
153 using build independent types, the appropriate variant, either 16-bit or 8-bit, |
|
154 is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro |
|
155 has been defined or not. </p> <p>Binary data always requires the 8-bit variant |
|
156 regardless of the build, and it must be explicitly used in program code. Explicit |
|
157 use of the 16-bit variant is rare. With a few exceptions, the behaviour of |
|
158 both 8-bit and 16-bit variants is the same. </p> </section> |
|
159 <section id="GUID-A8D3CD4B-9069-5B98-ADBA-2272F597DE4D"><title>The MDesCArray |
|
160 mixin class</title> <p>The <codeph>MDesCArray</codeph> class is a mixin which |
|
161 defines a protocol for: </p> <ul> |
|
162 <li id="GUID-21092598-F289-5A57-BA93-48F23EF788AF"><p>returning the number |
|
163 of elements in a descriptor array </p> </li> |
|
164 <li id="GUID-0FAE184F-6D54-5CFF-858C-2A75F70D3969"><p>returning a non-modifiable |
|
165 pointer descriptor, a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type representing a specific |
|
166 indexed element. </p> </li> |
|
167 </ul> <p>The use of the mixin permits a degree of polymorphism amongst the |
|
168 descriptor array classes. It permits the number of descriptor array elements |
|
169 to be returned and a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type for a specific descriptor |
|
170 array element to be returned without knowing the specific concrete descriptor |
|
171 array type being accessed. </p> <p id="GUID-DA93F261-9E35-5073-AA06-3991B9B1AA35"><b>MDesCArray |
|
172 example</b> </p> <p>The following code fragments illustrate how the <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref> mixin |
|
173 class is used to return: </p> <ul> |
|
174 <li id="GUID-6262BE55-0B74-5779-AEB6-94357104051C"><p>the number of descriptor |
|
175 elements in a descriptor array. </p> </li> |
|
176 <li id="GUID-4D7F6F00-301C-534F-901E-85DB9847E9FF"><p>a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> representing |
|
177 a specific indexed descriptor element. </p> </li> |
|
178 </ul> <p>The code uses the build independent forms but the code is equally |
|
179 valid while using the explicit 8-bit or 16-bit variants. </p> <p>In this case, <xref href="GUID-29384669-FFCE-38FC-A005-61163D99401D.dita"><apiname>CDesCArrayFlat</apiname></xref>, <xref href="GUID-1B44227C-6F11-3A51-BE2C-8780319C6F72.dita"><apiname>CDesCArraySeg</apiname></xref> and <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> can be handled by the single function <codeph>foo()</codeph>. </p> <codeblock id="GUID-83C3574E-9FA6-57A3-AD5E-58705C6F5A68" xml:space="preserve"> ... |
|
180 CDesCArrayFlat* descflat = new( ELeave ) CDesCArrayFlat( 4 ); |
|
181 CDesCArraySeg* descseg = new( ELeave ) CDesCArraySeg( 4 ); |
|
182 CPtrCArray* ptrc = new( ELeave ) CPtrCArray( 4 ); |
|
183 ... |
|
184 ... // add descriptor elements to all three arrays |
|
185 ... |
|
186 foo( descflat ); |
|
187 foo( descseg ); |
|
188 foo( ptrc ); |
|
189 ...</codeblock> <codeblock id="GUID-CF9F694C-2175-5DAF-9666-C34E097B9992" xml:space="preserve">void foo( MDesCArray* anArray ) |
|
190 { |
|
191 .. |
|
192 TInt somenumber = anArray->MdcaCount(); |
|
193 TPtrC someptrc = anArray->MdcaPoint( someindexvalue ); |
|
194 .. |
|
195 }</codeblock> </section> |
|
196 </conbody><related-links> |
|
197 <link href="GUID-685CF352-372F-5393-97AF-1FA17DC57BA8.dita"><linktext>Constructing |
|
198 descriptor arrays</linktext></link> |
|
199 <link href="GUID-E3F403EE-717B-5EA6-BC4E-6840097CAC10.dita"><linktext>Using Dynamic |
|
200 Arrays</linktext></link> |
|
201 </related-links></concept> |