<?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>