7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE reference |
10 <!DOCTYPE reference |
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
12 <reference id="GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC" xml:lang="en"><title>EUserHlExample: |
12 <reference id="GUID-E26E46AE-914E-5F21-AB44-10F926BAA8AC" xml:lang="en"><title>EUserHlExample: EUser High Level example</title><shortdesc>This example demonstrates how to use the EUser High Level |
13 EUser High Level example</title><shortdesc>This example demonstrates how to use the EUser High Level library |
13 library and includes the ceratian features supported by the library. |
14 and includes the ceratian features supported by the library. It also demonstrates |
14 It also demonstrates the usage of specific APIs associated with the |
15 the usage of specific APIs associated with the EUser High Level Library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
15 EUser High Level Library. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
16 <section id="GUID-EB6346F5-1C3C-5DEB-AD3A-36474C372E1C"><title>Purpose</title> <p>This |
16 <section id="GUID-EB6346F5-1C3C-5DEB-AD3A-36474C372E1C"><title>Purpose</title> <p>This example demonstrates the following features of EUserHL: </p> <ul> |
17 example demonstrates the following features of EUserHL: </p> <ul> |
|
18 <li id="GUID-31A8E1A2-F2A9-5DDB-A880-FF27A41F1C3B"><p>String handling </p> </li> |
17 <li id="GUID-31A8E1A2-F2A9-5DDB-A880-FF27A41F1C3B"><p>String handling </p> </li> |
19 <li id="GUID-C09DC120-E1B8-5F60-9E90-2078E122C8EF"><p>Object creation and |
18 <li id="GUID-C09DC120-E1B8-5F60-9E90-2078E122C8EF"><p>Object creation |
20 automatic resource management </p> </li> |
19 and automatic resource management </p> </li> |
21 <li id="GUID-D7F1F68F-B9FC-524C-8B3B-D987582AEE76"><p>Memory usage by EUserHL |
20 <li id="GUID-D7F1F68F-B9FC-524C-8B3B-D987582AEE76"><p>Memory usage |
22 classes </p> </li> |
21 by EUserHL classes </p> </li> |
23 </ul> </section> |
22 </ul> </section> |
24 <section id="GUID-4BE93C59-6FBA-5F1B-90AE-1A8D30FB084C"><title>Download</title> <p>Click |
23 <section id="GUID-4BE93C59-6FBA-5F1B-90AE-1A8D30FB084C"><title>Download</title> <p>Click on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.zip" scope="external">EUserHlExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.html" scope="peer">browse</xref> to view the example code. </p> </section> |
25 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.zip" scope="external">EUserHlExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-66d31721-b6a6-4c84-b51d-c92f3927df4c.html" scope="peer">browse</xref> to view the example code. </p> </section> |
24 <section id="GUID-62A4FC58-6832-5282-9E14-DCAB88913E8F"><title>Design |
26 <section id="GUID-62A4FC58-6832-5282-9E14-DCAB88913E8F"><title>Design and |
25 and implementation</title> <p>The example implements three main functions: </p> <ul> |
27 implementation</title> <p>The example implements three main functions: </p> <ul> |
26 <li id="GUID-5B20BDEE-B5A1-5D07-A19A-5CA298D1CEAA"><p> <codeph>WalkthroughStringsL()</codeph> demonstrates string handling. </p> </li> |
28 <li id="GUID-5B20BDEE-B5A1-5D07-A19A-5CA298D1CEAA"><p> <codeph>WalkthroughStringsL()</codeph> demonstrates |
27 <li id="GUID-FC833C89-5A32-52E6-93D3-F45DC0A7E865"><p> <codeph>WalkthroughManagedL()</codeph> demonstrates object creation and resource management. </p> </li> |
29 string handling. </p> </li> |
28 <li id="GUID-7914F607-47BC-557A-B7F4-1432A294F743"><p> <codeph>WalkthroughUsageL()</codeph> demonstrates memory usage by EUserHL library classes. </p> </li> |
30 <li id="GUID-FC833C89-5A32-52E6-93D3-F45DC0A7E865"><p> <codeph>WalkthroughManagedL()</codeph> demonstrates |
29 </ul> <p><b>String handling</b> </p> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is designed to be a self-managing, resizable alternative to some |
31 object creation and resource management. </p> </li> |
30 of the existing descriptor types. </p> <p> <codeph>WalkthroughStringsL()</codeph> demonstrates how <codeph>LString</codeph> can be used in similar |
32 <li id="GUID-7914F607-47BC-557A-B7F4-1432A294F743"><p> <codeph>WalkthroughUsageL()</codeph> demonstrates |
31 ways to the existing <codeph>TDesC</codeph> and <codeph>TDes</codeph> descriptor classes, as well as showing some additional functions, |
33 memory usage by EUserHL library classes. </p> </li> |
32 including: </p> <ul> |
34 </ul> <p><b>String handling</b> </p> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is designed |
|
35 to be a self-managing, resizable alternative to some of the existing descriptor |
|
36 types. </p> <p> <codeph>WalkthroughStringsL()</codeph> demonstrates how <codeph>LString</codeph> can |
|
37 be used in similar ways to the existing <codeph>TDesC</codeph> and <codeph>TDes</codeph> descriptor |
|
38 classes, as well as showing some additional functions, including: </p> <ul> |
|
39 <li id="GUID-DA576055-E813-51DE-8232-9E961596E34D"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-3A7A28FA-6647-3F51-A628-7857898E5090"><apiname>LString::SetMaxlengthL()</apiname></xref> </p> </li> |
33 <li id="GUID-DA576055-E813-51DE-8232-9E961596E34D"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-3A7A28FA-6647-3F51-A628-7857898E5090"><apiname>LString::SetMaxlengthL()</apiname></xref> </p> </li> |
40 <li id="GUID-7A845FEC-A1B6-592F-A4E4-B93F301E3E1A"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-D7071D5E-E3EA-35ED-9A8F-D330162493A7"><apiname>LString::ReserveFreeCapacityL()</apiname></xref> </p> </li> |
34 <li id="GUID-7A845FEC-A1B6-592F-A4E4-B93F301E3E1A"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-D7071D5E-E3EA-35ED-9A8F-D330162493A7"><apiname>LString::ReserveFreeCapacityL()</apiname></xref> </p> </li> |
41 <li id="GUID-3883BD67-A7AA-5E55-8281-D41BC5871815"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-48151B50-C8C4-3011-9A76-8242EB7E1DDC"><apiname>LString::Compress()</apiname></xref> </p> </li> |
35 <li id="GUID-3883BD67-A7AA-5E55-8281-D41BC5871815"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-48151B50-C8C4-3011-9A76-8242EB7E1DDC"><apiname>LString::Compress()</apiname></xref> </p> </li> |
42 <li id="GUID-F7BC1D06-38E9-582A-870F-CE38A6DC4FD5"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-7A5C522F-9B29-3443-A853-EF06BAD08352"><apiname>LString::Reset()</apiname></xref> </p> </li> |
36 <li id="GUID-F7BC1D06-38E9-582A-870F-CE38A6DC4FD5"><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-7A5C522F-9B29-3443-A853-EF06BAD08352"><apiname>LString::Reset()</apiname></xref> </p> </li> |
43 </ul> <p> <codeph>CStringUserTwoPhase</codeph> is used to demonstrate the |
37 </ul> <p> <codeph>CStringUserTwoPhase</codeph> is used to demonstrate |
44 use of <codeph>LString</codeph> s in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is |
38 the use of <codeph>LString</codeph> s in the two-phase construction |
45 used in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref> in the <codeph>NewL()</codeph> function. </p> <p> <codeph>CStringUserSinglePhase</codeph> is |
39 pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is used in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref> in the <codeph>NewL()</codeph> function. </p> <p> <codeph>CStringUserSinglePhase</codeph> is used to demonstrate |
46 used to demonstrate the use of <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> s in the single |
40 the use of <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> s in the single phase construction |
47 phase construction pattern. A macro <codeph>CONSTRUCTORS_MAY_LEAVE</codeph> is |
41 pattern. A macro <codeph>CONSTRUCTORS_MAY_LEAVE</codeph> is declared |
48 declared to ensure cleanup is correctly handled if the constructor leaves. </p> <p><b>Object |
42 to ensure cleanup is correctly handled if the constructor leaves. </p> <p><b>Object creation and automatic resource management</b> </p> <p>The <codeph>LCleanedUpXxx</codeph> classes <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref>, <xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref>, <xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref>, <xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref> and <xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref> classes provide automatic resource management that avoids the need |
49 creation and automatic resource management</b> </p> <p>The <codeph>LCleanedUpXxx</codeph> classes <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref>, <xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref>, <xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref>, <xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref> and <xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref> classes |
43 for the programmer to use the cleanup stack. </p> <p> <codeph>WalkthroughManagedL()</codeph> shows how the various <codeph>LCleanedUpXxx</codeph> classes are |
50 provide automatic resource management that avoids the need for the programmer |
44 used. It shows how objects declared locally to a function (a pointer, |
51 to use the cleanup stack. </p> <p> <codeph>WalkthroughManagedL()</codeph> shows |
45 a resource handle, an array, and an object cleaned up using a <xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref>) are deleted automatically when they go out |
52 how the various <codeph>LCleanedUpXxx</codeph> classes are used. It shows |
46 of scope. </p> <p> <codeph>CManagedUserTwoPhase</codeph> demonstrates |
53 how objects declared locally to a function (a pointer, a resource handle, |
47 the use of the management classes in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is used in the <codeph>NewL()</codeph> function |
54 an array, and an object cleaned up using a <xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref>) |
48 in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref>. <codeph>LManagedXxx</codeph> classes (for example <xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref> and <xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref>) are used to handle cleanup of member data. </p> <p><b>Related APIs</b></p><p><xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref></p><p><xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref></p><p><xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref></p><p><xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref></p><p><xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref></p><p><xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref></p><p><xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref></p><p><xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref></p><p><xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref></p><p><b>Memory usage</b> </p> <p> <codeph>WalkthroughUsageL()</codeph> API demonstrates the memory overhead of using EUserHL. </p> </section> |
55 are deleted automatically when they go out of scope. </p> <p> <codeph>CManagedUserTwoPhase</codeph> demonstrates |
49 <section id="GUID-1BB8D12F-2303-5F46-BF3F-78416EAB2DBE"><title>Building |
56 the use of the management classes in the two-phase construction pattern. <xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref> is |
50 and configuring</title> <p>To build the example: </p> <ul> |
57 used in the <codeph>NewL()</codeph> function in place of the <xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref>. <codeph>LManagedXxx</codeph> classes |
51 <li id="GUID-324858E0-CD22-533E-A291-4CD4C88935BC"><p>You can build |
58 (for example <xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref> and <xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref>) |
52 the example from your IDE or the command line. </p> <p>If you use |
59 are used to handle cleanup of member data. </p> <p><b>Related APIs</b></p><p><xref href="GUID-0DD554D7-B9B1-3FD3-898F-4D855144FCEA.dita"><apiname>CleanupStack</apiname></xref></p><p><xref href="GUID-A7B3BEBB-3805-3149-A9DB-075FFF3DED3F.dita"><apiname>LCleanedupArray</apiname></xref></p><p><xref href="GUID-E6D04730-8064-3846-99E4-FB638C5EAA65.dita"><apiname>LCleanedupGuard</apiname></xref></p><p><xref href="GUID-9ECEAE0C-3D5A-3B1F-88DD-28B37CE9950D.dita"><apiname>LCleanedupHandle</apiname></xref></p><p><xref href="GUID-BD4E0CC4-75A2-306D-A860-06B4138F86EB.dita"><apiname>LCleanedupPtr</apiname></xref></p><p><xref href="GUID-83938A18-23EF-301A-9D40-C89AEDB5DFF0.dita"><apiname>LCleanedupRef</apiname></xref></p><p><xref href="GUID-FCBCB7A9-AF28-3591-A54D-8AF354E01D11.dita"><apiname>LManagedHandle</apiname></xref></p><p><xref href="GUID-166B7262-50A5-3C2E-B7DD-3291F96B31AA.dita"><apiname>LManagedPtr</apiname></xref></p><p><xref href="GUID-CD0A798E-7E42-3689-8E86-F5FD43C758FC.dita"><apiname>TCleanupItem</apiname></xref></p><p><b>Memory |
53 an IDE, import the <filepath>bld.inf</filepath> file of the example |
60 usage</b> </p> <p> <codeph>WalkthroughUsageL()</codeph> API demonstrates the |
54 into your IDE, and use the build command of the IDE. </p> <p>If you |
61 memory overhead of using EUserHL. </p> </section> |
55 use the command line, open a command prompt, and set the current directory |
62 <section id="GUID-1BB8D12F-2303-5F46-BF3F-78416EAB2DBE"><title>Building and |
56 to the source code directory of the example. You can then build the |
63 configuring</title> <p>To build the example: </p> <ul> |
57 example with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake bldfiles</userinput> </p> <p><userinput>abld |
64 <li id="GUID-324858E0-CD22-533E-A291-4CD4C88935BC"><p>You can build the example |
58 build</userinput> </p> </li> |
65 from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file |
59 <li id="GUID-01951689-451E-5B11-8A71-08B263B4CA8A"><p>For the emulator, |
66 of the example into your IDE, and use the build command of the IDE. </p> <p>If |
60 the example builds an executable called <filepath>euserhlexample.exe</filepath> in the <filepath>epoc32\release\winscw\<udeb or |
67 you use the command line, open a command prompt, and set the current directory |
61 urel>\</filepath> folder. </p> </li> |
68 to the source code directory of the example. You can then build the example |
|
69 with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake |
|
70 bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe |
|
71 how to use the SBSv1 build tools. </p> </li> |
|
72 <li id="GUID-01951689-451E-5B11-8A71-08B263B4CA8A"><p>For the emulator, the |
|
73 example builds an executable called <filepath>euserhlexample.exe</filepath> in |
|
74 the <filepath>epoc32\release\winscw\<udeb or urel>\</filepath> folder. </p> </li> |
|
75 </ul> </section> |
62 </ul> </section> |
76 <section id="GUID-B4B61C60-2DAF-5279-A934-DF5B5FCA29E7"><title>Running the |
63 <section id="GUID-B4B61C60-2DAF-5279-A934-DF5B5FCA29E7"><title>Running |
77 example</title> <p>This is a console application. The user presses any key |
64 the example</title> <p>This is a console application. The user presses |
78 to step through it and the emulator closes down on exit. </p> </section> |
65 any key to step through it and the emulator closes down on exit. </p> </section> |
79 <section><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser |
66 <section id="GUID-4D11EB1C-F2C4-4B0F-8DFC-3ECB15141A20"><title>See also:</title><p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser High Level |
80 High Level Library</xref></p></section> |
67 Library</xref></p></section> |
81 </refbody></reference> |
68 </refbody></reference> |