Week 23 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462.
<?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>