Traps and Leaves

A function usually leaves if an error occurs (similar to throwing exception), and the error code can be catched using a trap (similar to the except part).

You leave a from a function using User::Leave with the error number as its parameter, like this:


int InsertL()
{
//... other codes ...
if (!myObject) User::Leave(KErrNoMemory);
//... more codes...
}


When User::Leave is called, it will return (or you migh say jump) to the instruction after the one that traps the leave.

By convention, the name of the function that leaves ends with an L. This will make it easier for you decide whether to trap a leave or not.

Trapping a leave is simple:


TInt errcode;
TRAP(errcode, InsertL());


or


TRAPD(errcode, InsertL());


The TRAPD macro saves you a line by defining the error code variable, it also means that you can not use TRAPD more than once in a code block using same variable (errcode will be redefined), use TRAP() for next trap code if you use the same variable.


TRAPD(err, TestLeaveL(0));
TRAPD(err, TestLeaveL(1)); //error, redefinition of err
TRAPD(err2, TestLeaveL(1)); //OK
TRAP(err, TestLeaveL(1)); //OK


The TRAP macro will trap any statement on the second parameter that leaves. If the function leaves, the error code will be filled with a value, if the function does not leave (returning without error), the error code would be KErrNone a constant with a value of 0 (zero).

If your function name ends with an L (for example when you are implementing an interface), and you call a function with the name also ends with an L, you don't have to trap the leave:


void MyLeaveL()
{
//.. code ..
//if TestL() leaves, it will also leaves from this function
//with the error code from the TestL()
TestL();
//..code..
}


But if your function name doesn't end with an L, you must trap the leave:


void TestFunction()
{
//..code..
TRAPD(err, TestL());
//..code..
}


This following code might give you a better understanding of how traps and leaves work (this is a modification from the console based hello world):


#include "CommonFramework.h"
//test function that leaves
void TestLeaveL(int leave)
{
console->Printf(_L("Test Leave\n"));
if (leave) {
console->Printf(_L("Leaving\n"));
User::Leave(1);
}
console->Printf(_L("Not Leaving\n"));
}
//calling a function that leaves
void CallingLeaveL()
{
TestLeaveL(1);
//the following code will never be executed
//because the above line will leave
console->Printf(_L("Not Printed\n"));
}
// do the example
LOCAL_C void doExampleL()
{
TRAPD(err, TestLeaveL(0));
console->Printf(_L("Leave code is: %d\n"), err);
TRAP(err, TestLeaveL(1));
console->Printf(_L("Leave code is: %d\n"), err);
TRAP(err, CallingLeaveL());
console->Printf(_L("Leave code is: %d\n"), err);
}


The output will be:


Test Leave
Not Leaving
Leave code is: 0
Test Leave
Leaving
Leave code is: 1
Test Leave
Leaving
Leave code is: 1
ok [press any key]


I'll talk more about traps an leaves when discussing about the C-type Class.