|
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-3AD20E0C-F364-533F-9FBC-227478CA9982" xml:lang="en"><title>How |
|
13 to use TRAP</title><shortdesc>Provides code snippets to show you how to use <codeph>TRAP</codeph>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-0CE805F2-226D-4A8C-8CDF-51BF63281B10"><title>Execute leaving functions under a trap harness</title> <p>Functions |
|
15 that leave, including functions that call other functions that can leave, |
|
16 must be executed under a trap harness. </p> <p>If a call to <codeph>User::Leave()</codeph> occurs |
|
17 within the function, control will immediately be returned to the most recent <codeph>TRAP</codeph>. |
|
18 A variable is used with every trap to receive the error code specified in |
|
19 a leave. </p> <p>If no leave occurs, then when the called function ends, execution |
|
20 returns to the <codeph>TRAP</codeph>, and the leave variable has the value <codeph>KErrNone</codeph>. </p> <p>Typically |
|
21 after a <codeph>TRAP</codeph>, a function checks the leave variable to test |
|
22 whether processing returned normally or by leaving, and acts appropriately. |
|
23 Special mechanisms discussed later are provided to handle cleanup after the |
|
24 exception. </p> <codeblock id="GUID-AE3B0F19-F632-5E4C-A14A-5AD804472BA3" xml:space="preserve">TInt E32Main() |
|
25 { |
|
26 testConsole.Title(); // write out title |
|
27 testConsole.Start(_LIT("Example")); // start a new "test" |
|
28 |
|
29 // The leave variable |
|
30 TInt r; |
|
31 // Perform example function. If it leaves, |
|
32 // the leave code is put in r |
|
33 TRAP(r,doExampleL()); |
|
34 // Test the leave variable |
|
35 if (r) |
|
36 testConsole.Printf(_LIT("Failed: leave code=%d"), r); |
|
37 |
|
38 testConsole.End(); // finish |
|
39 testConsole.Close(); // close it |
|
40 return KErrNone; // and return |
|
41 }</codeblock> <p><b>Notes</b> </p> <ul> |
|
42 <li id="GUID-DD570EB3-15DA-5615-930C-3CD7FD3A65F2"><p>It is not necessary |
|
43 that all L functions be <i>directly</i> invoked by a trap harness. In most |
|
44 cases, functions that can leave are called normally by other functions. It |
|
45 is only necessary that somewhere above the function in the call chain is a |
|
46 trap harness. </p> </li> |
|
47 <li id="GUID-E7231292-D852-5DF7-830D-7B2B92F8C3D3"><p>It is not recommended |
|
48 to call a function with an <codeph>LC</codeph> suffix from inside a trap harness. |
|
49 This is because if the function does not leave, the object that the function |
|
50 created and pushed onto the cleanup stack will remain on the cleanup stack |
|
51 on exiting from the trap harness. This causes a <codeph>E32USER-CBase 71</codeph> panic, |
|
52 unless the object is popped by the caller from within the trap harness, for |
|
53 example: </p> <codeblock id="GUID-933B5F12-B729-5B0F-A021-FF999EFF6A79" xml:space="preserve">TRAPD(error, pointer = SomeClass::SomeFunctionLC(); CleanupStack::Pop(pointer));</codeblock> <p>In this code, if <codeph>SomeClass::SomeFunctionLC()</codeph> leaves, |
|
54 then <codeph>pointer</codeph> is destroyed as part of leave processing. If |
|
55 it does not leave then <codeph>CleanupStack::Pop(pointer)</codeph> is called, |
|
56 avoiding the panic. </p> </li> |
|
57 </ul> </section> |
|
58 <section id="GUID-E21C113D-9931-5E85-9ED5-6F14BD28E042"><title>Using TRAPD</title> <p>For |
|
59 convenience, there is a <codeph>TRAPD</codeph> form of the macro which defines |
|
60 the variable to be used as the leave code. This saves a line of source code |
|
61 in the majority of situations. </p> <codeblock id="GUID-EBC2B054-A961-54A5-BBB8-3C194F208C25" xml:space="preserve">TRAPD(leaveCode,SomeFunctionL()); // call a function |
|
62 if (leaveCode!=KErrNone) // check for error leave code |
|
63 { |
|
64 // some cleanup |
|
65 }</codeblock> </section> |
|
66 <section id="GUID-BB8DEAE9-D247-5AAE-80AD-A5FB193786BB"><title>Trap harnesses |
|
67 and function return values</title> <p>Trap harnesses can be used when the |
|
68 function being called returns a result. </p> <codeblock id="GUID-3848F9FA-72A1-569D-B603-AB6FB4DA042B" xml:space="preserve">TRAPD(leaveCode,value=GetSomethingL()); // get a value |
|
69 if (leaveCode!=KErrNone) // check for error leave code |
|
70 { |
|
71 // some cleanup |
|
72 } |
|
73 else { // didn’t leave: value valid |
|
74 }</codeblock> </section> |
|
75 </conbody></concept> |