<?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_d0e222099_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_d0e222146_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 &amp; CDesCArraySeg

           </title>

<image href="GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e222300_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_d0e222311_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_d0e222357_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>