--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,86 @@
+<?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-0817AD1D-58CF-5108-ACBF-26DFD4BA395E" xml:lang="en"><title>Descriptors
+Overview</title><shortdesc>This document provides an overview of descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-B9DAC214-E22A-4E05-AC39-CE994E87C8CA"><title>Purpose</title> <p>Manipulates
+string and data buffers. </p> </section>
+<section id="GUID-A49ACEBD-15DA-4525-BAA7-C15635518D52"><title>Description</title> <p>Descriptors
+are a family of classes that are used in Symbian platform for string handling.
+They are used in preference to NULL-terminated C strings. The same classes
+are used for general binary data. </p> <p>The basic classification of descriptor
+types is given below. Concrete descriptor classes implement variations on
+these basic types for different data widths and for different abilities to
+modify the data. The names of the concrete classes follow certain naming conventions
+that modify the basic name given in the table. </p> <p><b>Basic
+classification</b> </p> <table id="GUID-F074AE70-AC9D-53E5-AD5F-BB391CD32831">
+<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
+<tbody>
+<row>
+<entry><p> <b>Type</b>  </p> </entry>
+<entry><p> <b>Description</b>  </p> </entry>
+<entry><p> <b>Basic name</b>  </p> </entry>
+</row>
+<row>
+<entry><p>abstract </p> </entry>
+<entry><p>Base interface: allows descriptors of different types to be use
+polymorphically </p> </entry>
+<entry><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>buffer </p> </entry>
+<entry><p>Stack based: contains the data as part of itself. Buffer descriptors
+have a maximum length set at compile time. </p> </entry>
+<entry><p> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>pointer </p> </entry>
+<entry><p>Refer to data stored elsewhere that is not owned by the descriptor </p> </entry>
+<entry><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref>  </p> </entry>
+</row>
+<row>
+<entry><p>heap </p> </entry>
+<entry><p>Refers to data stored on the heap that is owned by the descriptor.
+The maximum length of this data can be set and changed dynamically. </p> </entry>
+<entry><p> <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>  </p> <p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>  </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p><b>Width</b> </p> <p>Descriptor
+types can store 8-bit or 16-bit data. These types are indicated by the convention
+of appending 8 or 16 on the basic name, e.g. <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes16</apiname></xref>. In
+practice, the basic names correspond to 16-bit types, for example <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref> is
+defined to be <xref href="GUID-EF25E407-26DF-3D97-B725-2DD0345975BA.dita"><apiname>TBuf16</apiname></xref>. </p> <p><b>Modifiable and non-modifiable</b> </p> <p>Modifiable descriptor types
+have an interface that allows callers to alter their contents, such as appending
+characters. </p> <p>Non-modifiable descriptor types can have their contents
+reset, but not modified. The convention is for non-modifiable types to append
+a C on the basic name, e.g. <xref href="GUID-4D64E4B7-6BEE-3900-A115-460FE5B2D79E.dita"><apiname>TBufC</apiname></xref>. </p> <p>Heap type descriptors
+are an exceptional case: they are available only in the non-modifiable form,
+but can, nevertheless, be modified through use of a pointer: see <codeph>HBufC::Des()</codeph>.
+Alternatively, you can use the <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> descriptor, which is
+simpler to use than <codeph>HBufC</codeph>. The general rule is: </p> <ul>
+<li id="GUID-82384688-B4EB-545B-869D-9BF5C0BC3DD2"><p>use <codeph>HBufC</codeph> for
+data that rarely changes. </p> </li>
+<li id="GUID-A15A3A8B-4B8A-58FB-A972-91242331502D"><p>Use <codeph>RBuf</codeph> for
+data that changes frequently. </p> </li>
+</ul> <p><b>Example code</b></p><p>For
+examples, see:</p><ul>
+<li><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita">Descriptor Example
+Code</xref></p></li>
+<li><p><xref href="http://developer.symbian.org/wiki/index.php/Descriptors_Cookbook.dita">Descriptors
+Cookbook</xref> at the Symbian Foundation.</p></li>
+<li><p><xref href="http://www.forum.nokia.com/info/sw.nokia.com/id/9c61aadd-8ae7-4c19-9484-2b165f0cb55e/S60_Platform_Descriptor_Example_v2_1_en.zip.html" scope="external">S60 Platform: Descriptor Example v2.1</xref> on Forum Nokia.</p></li>
+</ul></section>
+<section id="GUID-72EDBF0F-A0EB-4D93-85D0-55D0EA4740BB"><title>See also</title> <p> <xref href="GUID-EA98D77C-743B-5BA5-B131-A327B12A099C.dita">Character Representation
+Of Real Numbers Overview</xref>  </p> <p> <xref href="GUID-C15F56E3-753C-55CA-B3EF-63B2D139BCE4.dita">Dynamic
+Buffers Overview</xref>  </p> <p> <xref href="GUID-106B5A31-012E-503D-A972-A745ECADC1E7.dita">Literals
+Overview</xref>  </p> </section>
+</conbody></concept>
\ No newline at end of file