Mercurial Mercurial > oss > MCL > sftools > depl > docscontent / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita
changeset 13 48780e181b38
parent 7 51a74ef9ed63 
--- a/Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita	Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-0817AD1D-58CF-5108-ACBF-26DFD4BA395E.dita	Tue Jul 20 12:00:49 2010 +0100
@@ -1,86 +1,80 @@
-<?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>
+<?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" scope="external">Descriptors Cookbook</xref> at the Symbian Foundation.</p></li>
+<li><p><xref format="html" 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
MCL/sftools/depl/docscontent