<?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_d0e220085_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_d0e220093_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_d0e220101_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_d0e220109_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>