<?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-3AD20E0C-F364-533F-9FBC-227478CA9982" xml:lang="en"><title>How
to use TRAP</title><shortdesc>Provides code snippets to show you how to use <codeph>TRAP</codeph>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-0CE805F2-226D-4A8C-8CDF-51BF63281B10"><title>Execute leaving functions under a trap harness</title> <p>Functions
that leave, including functions that call other functions that can leave,
must be executed under a trap harness. </p> <p>If a call to <codeph>User::Leave()</codeph> occurs
within the function, control will immediately be returned to the most recent <codeph>TRAP</codeph>.
A variable is used with every trap to receive the error code specified in
a leave. </p> <p>If no leave occurs, then when the called function ends, execution
returns to the <codeph>TRAP</codeph>, and the leave variable has the value <codeph>KErrNone</codeph>. </p> <p>Typically
after a <codeph>TRAP</codeph>, a function checks the leave variable to test
whether processing returned normally or by leaving, and acts appropriately.
Special mechanisms discussed later are provided to handle cleanup after the
exception. </p> <codeblock id="GUID-AE3B0F19-F632-5E4C-A14A-5AD804472BA3" xml:space="preserve">TInt E32Main() 
 {  
 testConsole.Title(); // write out title
 testConsole.Start(_LIT("Example")); // start a new "test"

 // The leave variable
 TInt r;
 // Perform example function. If it leaves,
 // the leave code is put in r
 TRAP(r,doExampleL()); 
 // Test the leave variable
 if (r) 
  testConsole.Printf(_LIT("Failed: leave code=%d"), r);

 testConsole.End(); // finish
 testConsole.Close(); // close it
 return KErrNone; // and return
 }</codeblock> <p><b>Notes</b> </p> <ul>
<li id="GUID-DD570EB3-15DA-5615-930C-3CD7FD3A65F2"><p>It is not necessary
that all L functions be <i>directly</i> invoked by a trap harness. In most
cases, functions that can leave are called normally by other functions. It
is only necessary that somewhere above the function in the call chain is a
trap harness. </p> </li>
<li id="GUID-E7231292-D852-5DF7-830D-7B2B92F8C3D3"><p>It is not recommended
to call a function with an <codeph>LC</codeph> suffix from inside a trap harness.
This is because if the function does not leave, the object that the function
created and pushed onto the cleanup stack will remain on the cleanup stack
on exiting from the trap harness. This causes a <codeph>E32USER-CBase 71</codeph> panic,
unless the object is popped by the caller from within the trap harness, for
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,
then <codeph>pointer</codeph> is destroyed as part of leave processing. If
it does not leave then <codeph>CleanupStack::Pop(pointer)</codeph> is called,
avoiding the panic. </p> </li>
</ul> </section>
<section id="GUID-E21C113D-9931-5E85-9ED5-6F14BD28E042"><title>Using TRAPD</title> <p>For
convenience, there is a <codeph>TRAPD</codeph> form of the macro which defines
the variable to be used as the leave code. This saves a line of source code
in the majority of situations. </p> <codeblock id="GUID-EBC2B054-A961-54A5-BBB8-3C194F208C25" xml:space="preserve">TRAPD(leaveCode,SomeFunctionL()); // call a function
if (leaveCode!=KErrNone)          // check for error leave code
 {
 // some cleanup
 }</codeblock> </section>
<section id="GUID-BB8DEAE9-D247-5AAE-80AD-A5FB193786BB"><title>Trap harnesses
and function return values</title> <p>Trap harnesses can be used when the
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
if (leaveCode!=KErrNone) // check for error leave code
 {
 // some cleanup
 }
else { // didn’t leave: value valid
 }</codeblock> </section>
</conbody></concept>