<?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-EA3419BD-D757-5AC3-AE6F-DF21F794AE47" xml:lang="en"><title>Descriptor
basics</title><shortdesc>This document describes buffer descriptors, heap descriptors, pointer
descriptors and resizable buffer descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Descriptors provide a safe, consistent and economical mechanism for accessing
and manipulating strings and general binary data. </p>
<p>A descriptor represents data which can reside in any memory location, either
ROM or RAM. A descriptor object maintains pointer and length information to
describe the data. All access to the data is made through the descriptor object. </p>
<p>The area occupied by data represented by a given descriptor is considered
to be non-expandable, even though the length of data represented can shrink
or expand to fill that area. </p>
<p>The set of operations which can be performed on data represented by a descriptor
is divided into those that can modify the data and those which provide access
but do not modify the data. This split is reflected in the structure of the
descriptor classes. </p>
<p>Operations on data represented by a descriptor are safe. Accidental or
deliberate attempts to access memory outside the data area represented by
a descriptor are caught. An illegal access is treated as bad programming rather
than an environment or resource problem and raises an exception known as a
panic. </p>
<p>Descriptors make no distinction between the type of data represented; both
strings and binary data are treated in the same way. Although some operations
on a descriptor are intended to operate on a string, they also work on binary
data. This unifies the handling of both strings and binary data and increases
efficiency by allowing code to be shared. This also means that data can consist
of a mix of string data and binary data. </p>
<p>The concrete descriptors that programs create come in four types: </p>
<ul>
<li id="GUID-FFBB1AD9-1B31-5B37-8DA5-2B441385BE06"><p>Buffer descriptors -
where the data is part of the descriptor object and the descriptor object
lives on the program stack. </p> </li>
<li id="GUID-2E7EF74C-0079-597F-B15A-4351D9682BA6"><p>Heap descriptors - where
the data is part of the descriptor object and the descriptor object lives
on the heap. </p> </li>
<li id="GUID-DFB5D25C-FBF9-54F6-B0A4-51E58602935C"><p>Pointer descriptors
- where the descriptor object is separate from the data it represents. </p> </li>
<li id="GUID-AF5F3732-5E41-5E1A-AA88-C2A900C7F004"><p>Resizable buffer descriptors
- where the descriptor is separate from the data it represents, and the data
resides in a buffer allocated on the heap. </p> </li>
</ul>
<fig id="GUID-3FE00A17-DC27-5AB3-AAC8-05B4259C0834">
<title>           Buffer descriptor         </title>
<image href="GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e223822_href.png" placement="inline"/>
</fig>
<fig id="GUID-646F7A87-3D87-5856-886D-F3844D5D046C">
<title>           Heap descriptor         </title>
<image href="GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e223830_href.png" placement="inline"/>
</fig>
<fig id="GUID-6A2463A0-CF76-5746-9BF3-2FC24F714A73">
<title>           Pointer descriptor         </title>
<image href="GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e223838_href.png" placement="inline"/>
</fig>
<fig id="GUID-5EE9C2A2-E654-5736-A72B-4F7A705E12DE">
<title>           Resizable buffer descriptor         </title>
<image href="GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e223846_href.png" placement="inline"/>
</fig>
<p>Although the four types seem to be different, the underlying class structure
makes such differences transparent allowing them to be treated in the same
way. </p>
<p>Descriptor objects generally, behave as built-in types, as they can be
safely created on the program stack and can also be safely orphaned. The heap
descriptor is an exception to this rule. </p>
<p>The design also avoids the memory overhead associated with virtual functions. </p>
</conbody></concept>