--- a/Symbian3/SDK/Source/GUID-E8266924-FA52-5171-BD73-423A46227A74.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-E8266924-FA52-5171-BD73-423A46227A74.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,201 +1,201 @@
-<?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-E8266924-FA52-5171-BD73-423A46227A74" xml:lang="en"><title> Descriptor
-Arrays</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>A descriptor array is a mechanism which allows descriptors to be aggregated
-in a convenient way. </p>
-<section><title>Introduction</title> <p>Descriptor arrays build on the behaviour
-supplied by the Dynamic Arrays API and provides normal array operations for
-inserting, appending, deleting, and accessing elements. </p> <p>There are
-two types of descriptor array, based on the way data is represented by the
-array: </p> <ul>
-<li id="GUID-798A2774-299C-5078-9F48-588AC1EE8143"><p>an array whose elements
-consist of non-modifiable pointer descriptors. </p> </li>
-<li id="GUID-D456390C-34ED-5908-B188-73F55C26559C"><p>an array whose elements
-consist of memory pointers. </p> </li>
-</ul> <p>Either array can be used to represent descriptor data. The difference
-between them is based on the way they are implemented, and this determines
-which one is most suitable for a given situation. </p> <p> <b>NOTE</b>: All
-array classes are provided in variants for narrow and wide characters (for
-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>).
-These concrete types can be used directly, but it is usual to use typedefs
-(for example, <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref>) that are conditionally defined
-to map to the wide or narrow characters depending on the build. Only the conditional
-types are used below. </p> <p>Descriptor arrays has three key concepts - descriptor
-array protocol (<codeph>MDesC16Array</codeph>), general descriptor array (<codeph>CDesC16Array</codeph>)
-and pointer descriptor array (<codeph>CPtrC16Array</codeph>). </p> <p><b>Descriptor
-array protocol</b> </p> <p>This array defines an interface implemented by
-all descriptor array classes, and hence provides a degree of polymorphism.
-It provides a count function, and can return a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> for
-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
-descriptor array</b> </p> <p>This array accepts elements of any descriptor
-type. For each descriptor added, it creates a new heap descriptor (<xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>)
-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>.
-Derived classes provide storage in flat arrays (<xref href="GUID-29384669-FFCE-38FC-A005-61163D99401D.dita"><apiname>CDesCArrayFlat</apiname></xref>)
-and segmented arrays (<xref href="GUID-1B44227C-6F11-3A51-BE2C-8780319C6F72.dita"><apiname>CDesCArraySeg</apiname></xref>). </p> <p><b>Pointer
-descriptor array</b> </p> <p>This array holds only <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptor
-elements, that is, the descriptor type that points to data stored elsewhere.
-The data pointed to by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied
-or moved. </p> <p>The pointer descriptor array is <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref>.
-It implements <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref>, and can be used polymorphically
-with general descriptor arrays. </p> </section>
-<section><title>Array of non-modifiable pointer descriptor elements</title> <p>The
-array is supplied in two variants: </p> <ul>
-<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>
-<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>
-</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>.
-This is used whenever the descriptor elements are used to represent text strings.
-By using the build independent type, the appropriate variant, either 16-bit
-or 8-bit, is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
-has been defined or not. </p> <p>Binary data always requires the 8-bit variant,
-regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit
-use of the 16-bit variant is rare. </p> <p>The elements of this type of array
-consist of non-modifiable pointer descriptors. These pointer descriptors represent
-the data of the descriptors added to the array. The following diagram illustrates
-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">
-<title> Array of non-modifiable pointer descriptor elements
- </title>
-<image href="GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e182924_href.png" placement="inline"/>
-</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
-the non-modifiable pointer descriptors from the array but does <b>not</b> delete
-the data or descriptors that they point to. </p> </section>
-<section><title>Array of pointer elements</title> <p>The elements of this
-type of array consist of <b>pointers</b> to heap descriptors. </p> <p>When
-a descriptor is added to this type of array, a heap descriptor is allocated,
-taking its data from the supplied descriptor. The pointer to this heap descriptor
-is added as an array element. The following diagram illustrates this. The
-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">
-<title> Array of pointer elements </title>
-<image href="GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e182971_href.png" placement="inline"/>
-</fig> <p>There are two implementations of the array, one using a flat buffer
-and the other using a segmented buffer. </p> <p>The flat buffer implementation
-is supplied in two variants: </p> <ul>
-<li id="GUID-8E031CC3-AC57-5882-A96A-40F041543714"><p>the 16-bit variant implemented
-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>
-<li id="GUID-53DE0372-9FE8-55F8-A358-7062CA7FC37A"><p>the 8-bit variant implemented
-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>
-</ul> <p>The segmented buffer implementation is supplied in two variants: </p> <ul>
-<li id="GUID-DAEB51F2-19D5-5BC8-95DA-0375AC759C57"><p>the 16-bit variant implemented
-using a segmented buffer, a <xref href="GUID-F2998F7B-DFB1-3EDA-A6FF-1F3B2065DE4D.dita"><apiname>CDesC16ArraySeg</apiname></xref>, constructed
-from <xref href="GUID-440FF2B4-353B-3097-A2BA-5887D10B8B23.dita"><apiname>TDesC16</apiname></xref> types. </p> </li>
-<li id="GUID-0880573C-40D7-5C27-A2DB-5B9FF808E670"><p>the 8-bit variant implemented
-using a segmented buffer, a <xref href="GUID-DFC1F01A-A107-3C7F-883A-6C4F11859E1C.dita"><apiname>CDesC8ArraySeg</apiname></xref>, constructed
-from <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> types. </p> </li>
-</ul> <p>Both array implementations are also supplied as build independent
-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>.
-These are used whenever the descriptors are used to represent text strings.
-By using the build independent types, the appropriate variants, either 16-bit
-or 8-bit, are selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
-has been defined or not. </p> <p>Binary data always requires the 8-bit variants,
-regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit
-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
-the pointers from the array and also deletes the heap descriptors that they
-point to. </p> </section>
-<section><title>Type of array to be used</title> <p>The advantages of using
-one type over the other are subtle. </p> <p>When using an array of non-modifiable
-pointer descriptors, the data represented by each <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> exists
-independently of the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> itself. The memory required
-by the array is that required to contain the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> elements.
-The data represented by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied
-or moved. On the other hand, that same data must be guaranteed to remain in
-memory if the array is to have any purpose. </p> <p>When using an array of
-pointers, a new heap descriptor is allocated for each descriptor to be added
-to the array. This increases the total memory requirements of the array. On
-the other hand, each array element is smaller because the size of a pointer
-is slightly smaller than the size of a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> object. The
-original descriptor data can also be safely discarded once it has been added
-to the array. </p> <p>This type also has the advantage that there is no commitment
-to a concrete descriptor type. </p> </section>
-<section><title>Relationship between descriptor array classes</title> <p>The
-following diagram illustrates the relationship between the descriptor array
-concrete classes and the base classes which support them. </p> <fig id="GUID-43444E8B-F2F5-539B-BA9D-EDF9B832DFD9">
-<title> The class relationships for CDesCArrayFlat & CDesCArraySeg
- </title>
-<image href="GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e183125_href.png" placement="inline"/>
-</fig> <p> </p> <fig id="GUID-3BD4A73F-1E09-515A-9833-6D9592A98E97">
-<title> The class relationships for CPtrCArray </title>
-<image href="GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e183136_href.png" placement="inline"/>
-</fig> </section>
-<section id="GUID-9948A6D4-19A2-58A2-B2F1-73EC577E1B0B"><title>Copying Descriptor
-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,
-provides a function which can copy elements from any descriptor array. </p> <p>The
-source descriptor array must be one which satisfies the protocol defined by
-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
-to the <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> array to represent the source data. </p> <p>The
-implementation of the copy does not and cannot depend on the type of the source
-descriptor array,that is, whether it is a <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> type
-or a <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref> type. However, the following diagram shows
-the effect of the copy operation based on the concrete type of the source
-array. </p> <fig id="GUID-E320FF9E-CBCA-597C-AE3B-8480A0829EF7">
-<title> Copying descriptor arrays </title>
-<image href="GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e183182_href.png" placement="inline"/>
-</fig> </section>
-<section id="GUID-009C368B-80E3-523B-BC4A-12BB90244CE1"><title>8-Bit Variant,
-16-Bit Variant and Build Independence</title> <p>Descriptor arrays are supplied
-in two variants: </p> <ul>
-<li id="GUID-7819B939-C7C0-5117-812D-B2D05D7650D4"><p>the 16-bit variant for
-16-bit descriptors. These descriptors are used for handling Unicode strings
-and double byte valued data. </p> </li>
-<li id="GUID-A1DCAB83-37F6-51ED-8AEA-0EFE361BE107"><p>the 8-bit variant for
-8-bit variant descriptors. These descriptors are used for handling non-Unicode
-strings and single byte valued data. (binary data). </p> </li>
-</ul> <p>Descriptor arrays are also supplied as build independent types. These
-are used for descriptors which are used to represent text strings. </p> <p>By
-using build independent types, the appropriate variant, either 16-bit or 8-bit,
-is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
-has been defined or not. </p> <p>Binary data always requires the 8-bit variant
-regardless of the build, and it must be explicitly used in program code. Explicit
-use of the 16-bit variant is rare. With a few exceptions, the behaviour of
-both 8-bit and 16-bit variants is the same. </p> </section>
-<section id="GUID-A8D3CD4B-9069-5B98-ADBA-2272F597DE4D"><title>The MDesCArray
-mixin class</title> <p>The <codeph>MDesCArray</codeph> class is a mixin which
-defines a protocol for: </p> <ul>
-<li id="GUID-21092598-F289-5A57-BA93-48F23EF788AF"><p>returning the number
-of elements in a descriptor array </p> </li>
-<li id="GUID-0FAE184F-6D54-5CFF-858C-2A75F70D3969"><p>returning a non-modifiable
-pointer descriptor, a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type representing a specific
-indexed element. </p> </li>
-</ul> <p>The use of the mixin permits a degree of polymorphism amongst the
-descriptor array classes. It permits the number of descriptor array elements
-to be returned and a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type for a specific descriptor
-array element to be returned without knowing the specific concrete descriptor
-array type being accessed. </p> <p id="GUID-DA93F261-9E35-5073-AA06-3991B9B1AA35"><b>MDesCArray
-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
-class is used to return: </p> <ul>
-<li id="GUID-6262BE55-0B74-5779-AEB6-94357104051C"><p>the number of descriptor
-elements in a descriptor array. </p> </li>
-<li id="GUID-4D7F6F00-301C-534F-901E-85DB9847E9FF"><p>a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> representing
-a specific indexed descriptor element. </p> </li>
-</ul> <p>The code uses the build independent forms but the code is equally
-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"> ...
- CDesCArrayFlat* descflat = new( ELeave ) CDesCArrayFlat( 4 );
- CDesCArraySeg* descseg = new( ELeave ) CDesCArraySeg( 4 );
- CPtrCArray* ptrc = new( ELeave ) CPtrCArray( 4 );
- ...
- ... // add descriptor elements to all three arrays
- ...
- foo( descflat );
- foo( descseg );
- foo( ptrc );
- ...</codeblock> <codeblock id="GUID-CF9F694C-2175-5DAF-9666-C34E097B9992" xml:space="preserve">void foo( MDesCArray* anArray )
- {
- ..
- TInt somenumber = anArray->MdcaCount();
- TPtrC someptrc = anArray->MdcaPoint( someindexvalue );
- ..
- }</codeblock> </section>
-</conbody><related-links>
-<link href="GUID-685CF352-372F-5393-97AF-1FA17DC57BA8.dita"><linktext>Constructing
-descriptor arrays</linktext></link>
-<link href="GUID-E3F403EE-717B-5EA6-BC4E-6840097CAC10.dita"><linktext>Using Dynamic
-Arrays</linktext></link>
+<?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-E8266924-FA52-5171-BD73-423A46227A74" xml:lang="en"><title> Descriptor
+Arrays</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>A descriptor array is a mechanism which allows descriptors to be aggregated
+in a convenient way. </p>
+<section><title>Introduction</title> <p>Descriptor arrays build on the behaviour
+supplied by the Dynamic Arrays API and provides normal array operations for
+inserting, appending, deleting, and accessing elements. </p> <p>There are
+two types of descriptor array, based on the way data is represented by the
+array: </p> <ul>
+<li id="GUID-798A2774-299C-5078-9F48-588AC1EE8143"><p>an array whose elements
+consist of non-modifiable pointer descriptors. </p> </li>
+<li id="GUID-D456390C-34ED-5908-B188-73F55C26559C"><p>an array whose elements
+consist of memory pointers. </p> </li>
+</ul> <p>Either array can be used to represent descriptor data. The difference
+between them is based on the way they are implemented, and this determines
+which one is most suitable for a given situation. </p> <p> <b>NOTE</b>: All
+array classes are provided in variants for narrow and wide characters (for
+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>).
+These concrete types can be used directly, but it is usual to use typedefs
+(for example, <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref>) that are conditionally defined
+to map to the wide or narrow characters depending on the build. Only the conditional
+types are used below. </p> <p>Descriptor arrays has three key concepts - descriptor
+array protocol (<codeph>MDesC16Array</codeph>), general descriptor array (<codeph>CDesC16Array</codeph>)
+and pointer descriptor array (<codeph>CPtrC16Array</codeph>). </p> <p><b>Descriptor
+array protocol</b> </p> <p>This array defines an interface implemented by
+all descriptor array classes, and hence provides a degree of polymorphism.
+It provides a count function, and can return a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> for
+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
+descriptor array</b> </p> <p>This array accepts elements of any descriptor
+type. For each descriptor added, it creates a new heap descriptor (<xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>)
+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>.
+Derived classes provide storage in flat arrays (<xref href="GUID-29384669-FFCE-38FC-A005-61163D99401D.dita"><apiname>CDesCArrayFlat</apiname></xref>)
+and segmented arrays (<xref href="GUID-1B44227C-6F11-3A51-BE2C-8780319C6F72.dita"><apiname>CDesCArraySeg</apiname></xref>). </p> <p><b>Pointer
+descriptor array</b> </p> <p>This array holds only <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptor
+elements, that is, the descriptor type that points to data stored elsewhere.
+The data pointed to by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied
+or moved. </p> <p>The pointer descriptor array is <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref>.
+It implements <xref href="GUID-B732E017-EFD5-36BD-B633-7DE2DC57FFA2.dita"><apiname>MDesCArray</apiname></xref>, and can be used polymorphically
+with general descriptor arrays. </p> </section>
+<section><title>Array of non-modifiable pointer descriptor elements</title> <p>The
+array is supplied in two variants: </p> <ul>
+<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>
+<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>
+</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>.
+This is used whenever the descriptor elements are used to represent text strings.
+By using the build independent type, the appropriate variant, either 16-bit
+or 8-bit, is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
+has been defined or not. </p> <p>Binary data always requires the 8-bit variant,
+regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit
+use of the 16-bit variant is rare. </p> <p>The elements of this type of array
+consist of non-modifiable pointer descriptors. These pointer descriptors represent
+the data of the descriptors added to the array. The following diagram illustrates
+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">
+<title> Array of non-modifiable pointer descriptor elements
+ </title>
+<image href="GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e176330_href.png" placement="inline"/>
+</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
+the non-modifiable pointer descriptors from the array but does <b>not</b> delete
+the data or descriptors that they point to. </p> </section>
+<section><title>Array of pointer elements</title> <p>The elements of this
+type of array consist of <b>pointers</b> to heap descriptors. </p> <p>When
+a descriptor is added to this type of array, a heap descriptor is allocated,
+taking its data from the supplied descriptor. The pointer to this heap descriptor
+is added as an array element. The following diagram illustrates this. The
+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">
+<title> Array of pointer elements </title>
+<image href="GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e176377_href.png" placement="inline"/>
+</fig> <p>There are two implementations of the array, one using a flat buffer
+and the other using a segmented buffer. </p> <p>The flat buffer implementation
+is supplied in two variants: </p> <ul>
+<li id="GUID-8E031CC3-AC57-5882-A96A-40F041543714"><p>the 16-bit variant implemented
+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>
+<li id="GUID-53DE0372-9FE8-55F8-A358-7062CA7FC37A"><p>the 8-bit variant implemented
+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>
+</ul> <p>The segmented buffer implementation is supplied in two variants: </p> <ul>
+<li id="GUID-DAEB51F2-19D5-5BC8-95DA-0375AC759C57"><p>the 16-bit variant implemented
+using a segmented buffer, a <xref href="GUID-F2998F7B-DFB1-3EDA-A6FF-1F3B2065DE4D.dita"><apiname>CDesC16ArraySeg</apiname></xref>, constructed
+from <xref href="GUID-440FF2B4-353B-3097-A2BA-5887D10B8B23.dita"><apiname>TDesC16</apiname></xref> types. </p> </li>
+<li id="GUID-0880573C-40D7-5C27-A2DB-5B9FF808E670"><p>the 8-bit variant implemented
+using a segmented buffer, a <xref href="GUID-DFC1F01A-A107-3C7F-883A-6C4F11859E1C.dita"><apiname>CDesC8ArraySeg</apiname></xref>, constructed
+from <xref href="GUID-FB97E0A3-352A-316F-97C6-69E4741A8120.dita"><apiname>TDesC8</apiname></xref> types. </p> </li>
+</ul> <p>Both array implementations are also supplied as build independent
+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>.
+These are used whenever the descriptors are used to represent text strings.
+By using the build independent types, the appropriate variants, either 16-bit
+or 8-bit, are selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
+has been defined or not. </p> <p>Binary data always requires the 8-bit variants,
+regardless of the build, and this should be explicitly used in program code. </p> <p>Explicit
+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
+the pointers from the array and also deletes the heap descriptors that they
+point to. </p> </section>
+<section><title>Type of array to be used</title> <p>The advantages of using
+one type over the other are subtle. </p> <p>When using an array of non-modifiable
+pointer descriptors, the data represented by each <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> exists
+independently of the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> itself. The memory required
+by the array is that required to contain the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> elements.
+The data represented by the <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> descriptors is not copied
+or moved. On the other hand, that same data must be guaranteed to remain in
+memory if the array is to have any purpose. </p> <p>When using an array of
+pointers, a new heap descriptor is allocated for each descriptor to be added
+to the array. This increases the total memory requirements of the array. On
+the other hand, each array element is smaller because the size of a pointer
+is slightly smaller than the size of a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> object. The
+original descriptor data can also be safely discarded once it has been added
+to the array. </p> <p>This type also has the advantage that there is no commitment
+to a concrete descriptor type. </p> </section>
+<section><title>Relationship between descriptor array classes</title> <p>The
+following diagram illustrates the relationship between the descriptor array
+concrete classes and the base classes which support them. </p> <fig id="GUID-43444E8B-F2F5-539B-BA9D-EDF9B832DFD9">
+<title> The class relationships for CDesCArrayFlat & CDesCArraySeg
+ </title>
+<image href="GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e176531_href.png" placement="inline"/>
+</fig> <p> </p> <fig id="GUID-3BD4A73F-1E09-515A-9833-6D9592A98E97">
+<title> The class relationships for CPtrCArray </title>
+<image href="GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e176542_href.png" placement="inline"/>
+</fig> </section>
+<section id="GUID-9948A6D4-19A2-58A2-B2F1-73EC577E1B0B"><title>Copying Descriptor
+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,
+provides a function which can copy elements from any descriptor array. </p> <p>The
+source descriptor array must be one which satisfies the protocol defined by
+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
+to the <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> array to represent the source data. </p> <p>The
+implementation of the copy does not and cannot depend on the type of the source
+descriptor array,that is, whether it is a <xref href="GUID-FC3F3E4A-C86C-3DDB-B851-538BF20D5B27.dita"><apiname>CPtrCArray</apiname></xref> type
+or a <xref href="GUID-1ABD9C74-01F0-3144-9E5C-550E83F4D424.dita"><apiname>CDesCArray</apiname></xref> type. However, the following diagram shows
+the effect of the copy operation based on the concrete type of the source
+array. </p> <fig id="GUID-E320FF9E-CBCA-597C-AE3B-8480A0829EF7">
+<title> Copying descriptor arrays </title>
+<image href="GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e176588_href.png" placement="inline"/>
+</fig> </section>
+<section id="GUID-009C368B-80E3-523B-BC4A-12BB90244CE1"><title>8-Bit Variant,
+16-Bit Variant and Build Independence</title> <p>Descriptor arrays are supplied
+in two variants: </p> <ul>
+<li id="GUID-7819B939-C7C0-5117-812D-B2D05D7650D4"><p>the 16-bit variant for
+16-bit descriptors. These descriptors are used for handling Unicode strings
+and double byte valued data. </p> </li>
+<li id="GUID-A1DCAB83-37F6-51ED-8AEA-0EFE361BE107"><p>the 8-bit variant for
+8-bit variant descriptors. These descriptors are used for handling non-Unicode
+strings and single byte valued data. (binary data). </p> </li>
+</ul> <p>Descriptor arrays are also supplied as build independent types. These
+are used for descriptors which are used to represent text strings. </p> <p>By
+using build independent types, the appropriate variant, either 16-bit or 8-bit,
+is selected at build time depending on whether the <codeph>_UNICODE</codeph> macro
+has been defined or not. </p> <p>Binary data always requires the 8-bit variant
+regardless of the build, and it must be explicitly used in program code. Explicit
+use of the 16-bit variant is rare. With a few exceptions, the behaviour of
+both 8-bit and 16-bit variants is the same. </p> </section>
+<section id="GUID-A8D3CD4B-9069-5B98-ADBA-2272F597DE4D"><title>The MDesCArray
+mixin class</title> <p>The <codeph>MDesCArray</codeph> class is a mixin which
+defines a protocol for: </p> <ul>
+<li id="GUID-21092598-F289-5A57-BA93-48F23EF788AF"><p>returning the number
+of elements in a descriptor array </p> </li>
+<li id="GUID-0FAE184F-6D54-5CFF-858C-2A75F70D3969"><p>returning a non-modifiable
+pointer descriptor, a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type representing a specific
+indexed element. </p> </li>
+</ul> <p>The use of the mixin permits a degree of polymorphism amongst the
+descriptor array classes. It permits the number of descriptor array elements
+to be returned and a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> type for a specific descriptor
+array element to be returned without knowing the specific concrete descriptor
+array type being accessed. </p> <p id="GUID-DA93F261-9E35-5073-AA06-3991B9B1AA35"><b>MDesCArray
+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
+class is used to return: </p> <ul>
+<li id="GUID-6262BE55-0B74-5779-AEB6-94357104051C"><p>the number of descriptor
+elements in a descriptor array. </p> </li>
+<li id="GUID-4D7F6F00-301C-534F-901E-85DB9847E9FF"><p>a <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC</apiname></xref> representing
+a specific indexed descriptor element. </p> </li>
+</ul> <p>The code uses the build independent forms but the code is equally
+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"> ...
+ CDesCArrayFlat* descflat = new( ELeave ) CDesCArrayFlat( 4 );
+ CDesCArraySeg* descseg = new( ELeave ) CDesCArraySeg( 4 );
+ CPtrCArray* ptrc = new( ELeave ) CPtrCArray( 4 );
+ ...
+ ... // add descriptor elements to all three arrays
+ ...
+ foo( descflat );
+ foo( descseg );
+ foo( ptrc );
+ ...</codeblock> <codeblock id="GUID-CF9F694C-2175-5DAF-9666-C34E097B9992" xml:space="preserve">void foo( MDesCArray* anArray )
+ {
+ ..
+ TInt somenumber = anArray->MdcaCount();
+ TPtrC someptrc = anArray->MdcaPoint( someindexvalue );
+ ..
+ }</codeblock> </section>
+</conbody><related-links>
+<link href="GUID-685CF352-372F-5393-97AF-1FA17DC57BA8.dita"><linktext>Constructing
+descriptor arrays</linktext></link>
+<link href="GUID-E3F403EE-717B-5EA6-BC4E-6840097CAC10.dita"><linktext>Using Dynamic
+Arrays</linktext></link>
</related-links></concept>
\ No newline at end of file