|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9" xml:lang="en"><title>Descriptor |
|
13 Example Code</title><shortdesc>Examples that explains how to use descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <ul> |
|
15 <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> |
|
16 <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> |
|
17 <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> |
|
18 <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> |
|
19 <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> |
|
20 <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> |
|
21 <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> |
|
22 <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> |
|
23 </ul> |
|
24 <section id="GUID-90645A43-313B-55FC-91D0-547C237B680B"><title>BinaryData: |
|
25 handling general binary data with descriptors</title> <p><b>Download</b> </p> <p>Click |
|
26 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 |
|
27 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 |
|
28 shows how descriptors can handle general binary data by explicitly using the |
|
29 8 bit descriptor class variants <codeph>TBufC8<TInt></codeph>, <codeph>TBuf8<TInt></codeph>, <codeph>TPtr8</codeph> etc. </p> <p>Contrast |
|
30 this with examples where descriptors contain text. These examples almost always |
|
31 use the non-explicit forms <codeph>TBufC<TInt></codeph>, <codeph>TBuf<TInt></codeph>, <codeph>TPtr</codeph> etc; |
|
32 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 |
|
33 issues</b> </p> <p>The example requires no specific capabilities in order |
|
34 to run - and does not demonstrate any security issues. </p> </section> |
|
35 <section id="GUID-FC2B9B70-F849-5F19-9F3C-25D5FDCC576D"><title>Buffer: basic |
|
36 buffer descriptors</title> <p><b>Download</b> </p> <p>Click on the following |
|
37 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 |
|
38 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 |
|
39 shows the basic idea of buffer descriptors and how they are used. </p><p><b>Class |
|
40 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 |
|
41 capabilities in order to run - and does not demonstrate any security issues. </p> </section> |
|
42 <section id="GUID-5040249B-55ED-5ACD-837B-6B0FD4AF24FE"><title>InFunct: using |
|
43 descriptors in function interfaces</title> <p><b>Download</b> </p> <p>Click |
|
44 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 |
|
45 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 |
|
46 shows how descriptors can be used in function interfaces. Specifically, it |
|
47 shows the use of: </p> <ul> |
|
48 <li id="GUID-2ABA16E0-95CB-5792-B08C-E26F45B27E2C"><p> <codeph>const TDesC& |
|
49 aString</codeph> </p> </li> |
|
50 <li id="GUID-E4787B9F-BC31-52D4-AD4E-1A7F72958CD8"><p> <codeph>TDes&</codeph> </p> </li> |
|
51 <li id="GUID-1DF4E7EB-1531-5CFD-882F-B9A38B1C58EC"><p> <codeph>const TDesC8& |
|
52 aBuffer</codeph> </p> </li> |
|
53 <li id="GUID-8FC40660-48C9-5A75-A9B6-37EA23C3F4CC"><p> <codeph>TDes8& |
|
54 aBuffer</codeph>. </p> </li> |
|
55 </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 |
|
56 example requires no specific capabilities in order to run - and does not demonstrate |
|
57 any security issues. </p> </section> |
|
58 <section id="GUID-CE601E1E-AF03-56E8-B7FB-0CDFF4EA4386"><title>HeapBuffer: |
|
59 heap buffer descriptors</title> <p><b>Download</b> </p> <p>Click on the following |
|
60 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 |
|
61 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 |
|
62 shows use of the <codeph>HBufC</codeph> heap buffer descriptor and: </p> <ul> |
|
63 <li id="GUID-92C829F9-9697-57B2-A4F7-BD9D9AC4DBBF"><p>how it can be created |
|
64 using the <codeph>HBufC::NewL()</codeph> static function </p> </li> |
|
65 <li id="GUID-EED79AF9-AA29-532A-83BD-63C5DBCDF0A0"><p>how it can be reallocated |
|
66 using the <codeph>ReAllocL()</codeph> function </p> </li> |
|
67 <li id="GUID-7CD4D38E-B726-58CA-8027-DE73CF415A8F"><p>how its data can be |
|
68 changed through a <codeph>TPtr</codeph> constructed by calling the <codeph>Des()</codeph> function </p> </li> |
|
69 </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 |
|
70 issues</b> </p> <p>The example requires no specific capabilities in order |
|
71 to run - and does not demonstrate any security issues. </p> </section> |
|
72 <section id="GUID-C79042EB-4ACF-5972-9F57-E7C0F37DECF6"><title>Modifier: modifiable |
|
73 descriptors</title> <p><b>Download</b> </p> <p>Click on the following link |
|
74 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 |
|
75 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: |
|
76 <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 |
|
77 shows the usage of descriptor functions which can modify the descriptor. These |
|
78 are the functions defined and implemented by the <codeph>TDes</codeph> class: |
|
79 for example <codeph>SetLength()</codeph>, <codeph>Copy()</codeph> and <codeph>Insert()</codeph>. </p><p><b>Class |
|
80 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 |
|
81 issues</b> </p> <p>The example requires no specific capabilities in order |
|
82 to run - and does not demonstrate any security issues. </p> </section> |
|
83 <section id="GUID-927CFF04-C0D1-5BDE-B221-4245113924F7"><title>NonModifier: |
|
84 non-modifiable descriptors</title> <p><b>Download</b> </p> <p>Click on the |
|
85 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 |
|
86 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: |
|
87 <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 |
|
88 shows the use of descriptor functions which do not modify the descriptor. |
|
89 These are the functions defined and implemented by the <codeph>TDesC</codeph> class; |
|
90 for example <codeph>Length()</codeph>, <codeph>Size()</codeph> and <codeph>Compare()</codeph>. </p><p><b>Class |
|
91 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 |
|
92 issues</b> </p> <p>The example requires no specific capabilities in order |
|
93 to run - and does not demonstrate any security issues. </p> </section> |
|
94 <section id="GUID-5AEFA6EB-A100-5B96-935D-2537EEFB56F5"><title>Pointer: basic |
|
95 pointer descriptors</title> <p><b>Download</b> </p> <p>Click on the following |
|
96 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 |
|
97 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: |
|
98 <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 |
|
99 the basic idea of pointer descriptors and how they are used. </p><p><b>Class |
|
100 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 |
|
101 issues</b> </p> <p>The example requires no specific capabilities in order |
|
102 to run - and does not demonstrate any security issues. </p> </section> |
|
103 <section id="GUID-1636C0BB-9B23-5C47-8F26-CF080DBE64EB"><title>WriteToFiles: |
|
104 writes:"Hello World!" to a file</title> <p><b>Download</b> </p> <p>Click on |
|
105 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 |
|
106 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 |
|
107 the text "Hello World!" to a file. It is used as the basis of all examples |
|
108 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 |
|
109 example writes files to the executable's process private directory: <filepath>C:\private\0FFFFF00\</filepath>. </p> <p>The |
|
110 second UID in the <filepath>.mmp</filepath> file is defined as <codeph>0x0FFFFF00</codeph> and |
|
111 this is used as the secure ID on which the name of the private directory is |
|
112 based. </p> </section> |
|
113 </conbody></concept> |