<?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_d0e225869_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_d0e225934_href.png" placement="inline"/>
<p>Modifiable pointer descriptor</p>
</fig> </section>
</conbody></concept>