Chapter 1

successfully). This means you have to check errors explicitly using
User::LeaveIfError(), which does nothing if its argument is KErrNone or a positive
number, but leaves with the value of its argument if the argument is negative.
A few low-level Symbian OS APIs operate this way; their areas of application are a few
important circumstances in which it would be inappropriate to leave.
� Many file or communications functions are called speculatively to test whether a file is
there or a link is up. It is information, not an error, if these functions return with 'not
found' or a similar result.
� Symbian's implementation of the C Standard Library provides a thin layer over the
native RFile and communications APIs that returns standard C-type error codes. It's
much easier to handle errors directly than by trapping them. In any case, standard
library programs don't have a cleanup stack.
Granted, leaves could have been trapped. But that was judged undesirably expensive.
Instead, when you want a leave, you have to call User::LeaveIfError(). That's a little
bit costly too, but not as expensive as trapping leaves.
Note
Some truly ancient code in Symbian OS was written assuming that there
might not be a cleanup stack at all. But this isn't a sensible assumption these
days, and is certainly no justification for designing APIs that don't use L
functions. All native Symbian OS code should ensure it has a cleanup stack,
and design its APIs accordingly. The GUI application framework, and the
server framework, provide you with a cleanup stack, so you only have to
construct your own when you're writing a text console program.
Important
If you are using components with TInt error codes, don't forget to use
User::LeaveIfError(), where you need it.
6.5.3 R Classes on the Cleanup Stack
Sometimes, you need to create and use an R class object as an automatic variable rather
than as a member of a C class. In this case, you need to be able to push to the cleanup
stack. There are two options available to you:
� Use CleanupClosePushL()
� Do it directly : make a TCleanupItem consisting of a pointer to the R object, and a
static function that will close it.
If you have an item with a Close() function, then CleanupClose-PushL() (a global
nonmember function) will ensure that Close() is called when the item is popped and
destroyed by the cleanup stack. C++ templates are used for this, so Close() does not have
to be virtual.
The code below, taken from memorymagic, demonstrates how to use
CleanupClosePushL():
case EMagicCmdDeleteFile:
{
RFs fs;
CleanupClosePushL(fs);
User::LeaveIfError(fs.Connect());
User::LeaveIfError(fs.Delete(KTextFileName));