<?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-14FAE656-7CDE-56ED-ACB2-7853276C24E9" xml:lang="en"><title>Descriptor

Example Code</title><shortdesc>Examples that explains how to use descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-A0CE5E5F-9436-5499-AB97-7D26B785BE2A"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-90645A43-313B-55FC-91D0-547C237B680B">BinaryData: handling general binary data with descriptors</xref>  </p> </li>

<li id="GUID-B42110C1-038D-55E8-A6A3-390C357477C9"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-FC2B9B70-F849-5F19-9F3C-25D5FDCC576D">Buffer: basic buffer descriptors</xref>  </p> </li>

<li id="GUID-E935308D-FB46-5113-A90E-FDFA134DBB2F"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-5040249B-55ED-5ACD-837B-6B0FD4AF24FE">InFunct: using descriptors in function interfaces</xref>  </p> </li>

<li id="GUID-6C9C2E14-FEF8-5DA7-B9C5-70C356648F4A"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-CE601E1E-AF03-56E8-B7FB-0CDFF4EA4386">HeapBuffer: heap buffer descriptors</xref>  </p> </li>

<li id="GUID-BD6288C3-B2F5-51FF-92DE-420019239E3F"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-C79042EB-4ACF-5972-9F57-E7C0F37DECF6">Modifier: modifiable descriptors</xref>  </p> </li>

<li id="GUID-CC9EB05B-899D-5471-BD3D-D9BCF90CFC99"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-927CFF04-C0D1-5BDE-B221-4245113924F7">NonModifier: non-modifiable descriptors</xref>  </p> </li>

<li id="GUID-A71AB00F-EEE9-5696-B91E-DB7781B50586"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-5AEFA6EB-A100-5B96-935D-2537EEFB56F5">Pointer: basic pointer descriptors</xref>  </p> </li>

<li id="GUID-0D06F662-BF6C-5F29-A5EB-1F17D9455368"><p><xref href="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita#GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9/GUID-1636C0BB-9B23-5C47-8F26-CF080DBE64EB">WriteToFile: writes "Hello World!" to a file</xref>. </p> </li>

</ul>

<section id="GUID-90645A43-313B-55FC-91D0-547C237B680B"><title>BinaryData:

handling general binary data with descriptors</title> <p><b>Download</b> </p> <p>Click

on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-c4df8866-07d0-4b84-8715-6dacf56406ae.zip" scope="external">BinaryData .zip </xref>.</p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-c4df8866-07d0-4b84-8715-6dacf56406ae.html" scope="peer"> browse </xref>. View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>The example

shows how descriptors can handle general binary data by explicitly using the

8 bit descriptor class variants <codeph>TBufC8&lt;TInt&gt;</codeph>, <codeph>TBuf8&lt;TInt&gt;</codeph>, <codeph>TPtr8</codeph> etc. </p> <p>Contrast

this with examples where descriptors contain text. These examples almost always

use the non-explicit forms <codeph>TBufC&lt;TInt&gt;</codeph>, <codeph>TBuf&lt;TInt&gt;</codeph>, <codeph>TPtr</codeph> etc;

these are typedef'd to the 16 bit variant. </p><p><b>Class summary</b></p><p><xref href="GUID-78E993D5-A845-32B4-B41A-947ABEF16AA0.dita"><apiname>TBuf8</apiname></xref></p> <p><b>Security

issues</b> </p> <p>The example requires no specific capabilities in order

to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-FC2B9B70-F849-5F19-9F3C-25D5FDCC576D"><title>Buffer: basic

buffer descriptors</title> <p><b>Download</b> </p> <p>Click on the following

link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-454779b7-0369-4010-8d98-8b0f11bad653.zip" scope="external">Buffer .zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code:<xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-454779b7-0369-4010-8d98-8b0f11bad653.html" scope="peer"> browse </xref> . View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>This example

shows the basic idea of buffer descriptors and how they are used. </p><p><b>Class

summary</b></p><p><xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf </apiname></xref>  <xref href="GUID-4D64E4B7-6BEE-3900-A115-460FE5B2D79E.dita"><apiname>TBufC </apiname></xref>  <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC </apiname></xref> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr </apiname></xref> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname> TDes</apiname></xref> </p> <p><b>Security issues</b> </p> <p>The example requires no specific

capabilities in order to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-5040249B-55ED-5ACD-837B-6B0FD4AF24FE"><title>InFunct: using

descriptors in function interfaces</title> <p><b>Download</b> </p> <p>Click

on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-3c092b34-8554-49d7-9a0a-8b6eaeb6cbcf.zip" scope="external"> InFunct.zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-3c092b34-8554-49d7-9a0a-8b6eaeb6cbcf.html" scope="peer">browse</xref> . View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>This example

shows how descriptors can be used in function interfaces. Specifically, it

shows the use of: </p> <ul>

<li id="GUID-2ABA16E0-95CB-5792-B08C-E26F45B27E2C"><p> <codeph>const TDesC&amp;

aString</codeph>  </p> </li>

<li id="GUID-E4787B9F-BC31-52D4-AD4E-1A7F72958CD8"><p> <codeph>TDes&amp;</codeph>  </p> </li>

<li id="GUID-1DF4E7EB-1531-5CFD-882F-B9A38B1C58EC"><p> <codeph>const TDesC8&amp;

aBuffer</codeph>  </p> </li>

<li id="GUID-8FC40660-48C9-5A75-A9B6-37EA23C3F4CC"><p> <codeph>TDes8&amp;

aBuffer</codeph>. </p> </li>

</ul> <p>as function arguments. </p><p><b>Class summary</b></p><p> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf </apiname></xref> <xref href="GUID-4D64E4B7-6BEE-3900-A115-460FE5B2D79E.dita"><apiname>TBufC </apiname></xref>  <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr </apiname></xref> <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC </apiname></xref> <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname> HBufC</apiname></xref>  </p> <p><b>Security issues</b> </p> <p>The

example requires no specific capabilities in order to run - and does not demonstrate

any security issues. </p> </section>

<section id="GUID-CE601E1E-AF03-56E8-B7FB-0CDFF4EA4386"><title>HeapBuffer:

heap buffer descriptors</title> <p><b>Download</b> </p> <p>Click on the following

link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-85049b4c-d60e-490d-bd13-78355faa760a.zip" scope="external">HeapBuffer .zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-85049b4c-d60e-490d-bd13-78355faa760a.html" scope="peer"> browse </xref>.  View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>The example

shows use of the <codeph>HBufC</codeph> heap buffer descriptor and: </p> <ul>

<li id="GUID-92C829F9-9697-57B2-A4F7-BD9D9AC4DBBF"><p>how it can be created

using the <codeph>HBufC::NewL()</codeph> static function </p> </li>

<li id="GUID-EED79AF9-AA29-532A-83BD-63C5DBCDF0A0"><p>how it can be reallocated

using the <codeph>ReAllocL()</codeph> function </p> </li>

<li id="GUID-7CD4D38E-B726-58CA-8027-DE73CF415A8F"><p>how its data can be

changed through a <codeph>TPtr</codeph> constructed by calling the <codeph>Des()</codeph> function </p> </li>

</ul><p><b>class summary</b></p><p><xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC </apiname></xref> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr </apiname></xref> <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref> </p> <p><b>Security

issues</b> </p> <p>The example requires no specific capabilities in order

to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-C79042EB-4ACF-5972-9F57-E7C0F37DECF6"><title>Modifier: modifiable

descriptors</title> <p><b>Download</b> </p> <p>Click on the following link

to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-46410e6f-1ea3-42db-8966-9870bd3659da.zip" scope="external">Modifier .zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code:

 <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-46410e6f-1ea3-42db-8966-9870bd3659da.html" scope="peer"> browse </xref>.  View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>The example

shows the usage of descriptor functions which can modify the descriptor. These

are the functions defined and implemented by the <codeph>TDes</codeph> class:

for example <codeph>SetLength()</codeph>, <codeph>Copy()</codeph> and <codeph>Insert()</codeph>. </p><p><b>Class

summary</b></p><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes </apiname></xref> <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf </apiname></xref> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr</apiname></xref>  </p> <p><b>Security

issues</b> </p> <p>The example requires no specific capabilities in order

to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-927CFF04-C0D1-5BDE-B221-4245113924F7"><title>NonModifier:

non-modifiable descriptors</title> <p><b>Download</b> </p> <p>Click on the

following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-9f4be784-fb23-4a66-9f7f-d44b28fe98c1.zip" scope="external">NonModifier .zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code:

 <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-9f4be784-fb23-4a66-9f7f-d44b28fe98c1.html" scope="peer"> browse </xref> . View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>The example

shows the use of descriptor functions which do not modify the descriptor.

These are the functions defined and implemented by the <codeph>TDesC</codeph> class;

for example <codeph>Length()</codeph>, <codeph>Size()</codeph> and <codeph>Compare()</codeph>. </p><p><b>Class

summary</b></p><p> <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC </apiname></xref> <xref href="GUID-4D64E4B7-6BEE-3900-A115-460FE5B2D79E.dita"><apiname>TBufC </apiname></xref> <xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname> TPtrC</apiname></xref>  </p> <p><b>Security

issues</b> </p> <p>The example requires no specific capabilities in order

to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-5AEFA6EB-A100-5B96-935D-2537EEFB56F5"><title>Pointer: basic

pointer descriptors</title> <p><b>Download</b> </p> <p>Click on the following

link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-00b1bc4a-bf04-4964-81b0-82cbbf393a03.zip" scope="external">Pointer .zip </xref></p><p>Download some additional files

required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code:

 <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-00b1bc4a-bf04-4964-81b0-82cbbf393a03.html" scope="peer"> browse </xref>. View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p><p><b>Description</b> </p> <p>The example shows

the basic idea of pointer descriptors and how they are used. </p><p><b>Class

summary</b></p><p> <xref href="GUID-EA7DEFA4-D4D9-3B2B-86A3-C3FB1A682E61.dita"><apiname>TPtr </apiname></xref><xref href="GUID-5CD07A27-E3ED-3273-A560-680501468C91.dita"><apiname>TPtrC </apiname></xref> <xref href="GUID-6DF731E4-5691-31C4-BEE0-03A3873F15EC.dita"><apiname>TPtrC8 </apiname></xref> <xref href="GUID-8FE95467-D48B-3E61-9028-29C0F15F567E.dita"><apiname>TPtrC16</apiname></xref>  </p> <p><b>Security

issues</b> </p> <p>The example requires no specific capabilities in order

to run - and does not demonstrate any security issues. </p> </section>

<section id="GUID-1636C0BB-9B23-5C47-8F26-CF080DBE64EB"><title>WriteToFiles:

writes:"Hello World!" to a file</title> <p><b>Download</b> </p> <p>Click on

the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4a96349b-7287-40b7-99dd-64f3a2dc20a3.zip" scope="external">WriteToFiles .zip </xref></p><p>Download some additional

files required by the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.zip" scope="external">CommonFramework.zip</xref>.</p><p>View the example code: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4a96349b-7287-40b7-99dd-64f3a2dc20a3.html" scope="peer"> browse </xref>. View the additional files: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4184e6d4-8dbe-4267-b1a3-8737c8bf64ce.html" scope="peer">browse</xref>.</p> <p><b>Description</b> </p> <p>This writes

the text "Hello World!" to a file. It is used as the basis of all examples

which depend on just the Base and the file server. </p><p><b>Class summary</b></p><p><xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname> RFs </apiname></xref>  <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile </apiname></xref>  <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User </apiname></xref>  <xref href="GUID-6DF731E4-5691-31C4-BEE0-03A3873F15EC.dita"><apiname>TPtrC8</apiname></xref>  </p> <p><b>Security issues</b> </p> <p>The

example writes files to the executable's process private directory: <filepath>C:\private\0FFFFF00\</filepath>. </p> <p>The

second UID in the <filepath>.mmp</filepath> file is defined as <codeph>0x0FFFFF00</codeph> and

this is used as the secure ID on which the name of the private directory is

based. </p> </section>

</conbody></concept>