<?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-2DDAAD1C-D9EB-5741-B6AE-2383646E0EDB" xml:lang="en"><title>Pointer

descriptors</title><shortdesc>Describes non-modifiable pointer descriptors and modifiable pointer

descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A pointer descriptor represents data which can live in ROM or RAM and this

location is separate from the pointer descriptor object itself. </p>

<p>A pointer descriptor is an instance of a class that encapsulates a pointer

to the location of the data. </p>

<p>A pointer descriptor comes in two forms: </p>

<ul>

<li id="GUID-A836665F-9AB7-5364-891E-6297D68B291D"><p>a non-modifiable pointer

descriptor. </p> </li>

<li id="GUID-C46BB0C8-08ED-5835-9516-D164383D1313"><p>a modifiable pointer

descriptor. </p> </li>

</ul>

<section id="GUID-DE207726-9C75-4DD9-964A-6B7B16226C4A"><title>Non-modifiable pointer descriptor</title> <p>The data represented

by a non-modifiable pointer descriptor can be accessed, but not changed, through

this descriptor. </p> <p>Data is accessed through functions provided by the

base class. </p> <p>A non-modifiable pointer descriptor is supplied in two

variants: </p> <ul>

<li id="GUID-CF4D06B5-B5EB-5C4D-BA87-B990053CD15D"><p>the 16 bit variant,

a <codeph>TPtrC16</codeph>, for representing Unicode strings. </p> </li>

<li id="GUID-A1005460-2D2A-5DB4-9414-2747056A7DBC"><p>the 8 bit variant, a <codeph>TPtrC8</codeph>,

for representing non-Unicode strings and binary data. </p> </li>

</ul> <p>There is also a build independent type, <codeph>TPtrC</codeph>. This

is the type which is most commonly used in program code; the appropriate variant

is selected at build time. </p> <p>An explicit 8 bit variant is chosen for

binary data. The explicit 16 bit variant is rarely used. </p> <p>The base

class, <codeph>TDesC</codeph>, contains a data member which holds the length

of the data. The following drawing shows the layout of a <codeph>TPtrC</codeph> object

for a string of five characters representing the English word "Hello". </p> <fig id="GUID-D3F0600A-D575-5309-8182-CFA98D184E29">

<image href="GUID-37D2EFAE-FB55-5015-90CE-1361144C411E_d0e220875_href.png" placement="inline"/>

<p>Non-modifiable pointer descriptor</p>

</fig> </section>

<section id="GUID-33072A44-C95A-4688-AB85-019EFDC4F1B2"><title>Modifiable pointer descriptor</title> <p>The data represented

by a modifiable pointer descriptor can be both accessed and changed through

this descriptor. </p> <p>The length of the data can vary between zero and

the maximum length. The maximum length of the descriptor is set by the constructor.

When the length of the data is less than the maximum, a portion of the data

area represented by the descriptor is unused. </p> <p>Data is accessed and

modified through functions provided by the base classes. </p> <p>A modifiable

pointer descriptor is supplied in two variants: </p> <ul>

<li id="GUID-2DD694B8-8408-58F8-BE98-1D031666DEC5"><p>the 16 bit variant,

a <codeph>TPtr16</codeph>, for representing Unicode strings. </p> </li>

<li id="GUID-5D1EB254-6B9D-576C-9631-3461AC8FFD32"><p>the 8 bit variant, a <codeph>TPtr8</codeph>,

for representing non-Unicode strings and binary data. </p> </li>

</ul> <p>There is also a build independent type, <codeph>TPtr</codeph>. This

is the type which is most commonly used in program code; the appropriate variant

is selected at build time. </p> <p>An explicit 8 bit variant is chosen for

binary data. The explicit 16 bit variant is rarely used. </p> <p>The base

class <codeph>TDesC</codeph>, contains a data member that holds the length

of the data. The base class <codeph>TDes</codeph>, contains a data member

that holds the maximum length of the data. The following drawing shows the

layout of a <codeph>TPtr</codeph> object for a string of five characters representing

the English word "Hello". The maximum length to be represented by the descriptor

is 12. </p> <fig id="GUID-B6213E7F-AE00-5854-BBB7-C82BE71CB495">

<image href="GUID-8983A095-3F5A-5262-8920-8A13ADD045DC_d0e220940_href.png" placement="inline"/>

<p>Modifiable pointer descriptor</p>

</fig> </section>