Use Cases +for Writing Standard C++ Code

The following topics describe the use cases based on which you can write +Standard C++ code on Symbian platform:

Standard C++ code using STL or Standard C
Standard C++ code calling Symbian C++ functions
Symbian C++ code calling Standard C++ functions

Standard C++ +code using STL or Standard C

You can write a pure Standard C++ +application or library that does not use Symbian C++ directly. When you write +Standard C++ code using STL or Standard C ensure that you adhere to the following +guidelines:

Use the STDCPP keyword +in the .mmp file or you target type must be an STD target +type.
Use only the Standard +C++ semantics of the global operator new.
Your code must not depend +on One Definition Rule (ODR) across DLL boundaries. For more information, +see the Use +of one definition rule section.

Notes:

If these guidelines +are not followed, it can result in problems described in the Possible +Problems section.
Before you write a Standard +C++ library, see the Guidelines +for Writing Standard C++ Libraries section.

Standard C++ +code calling Symbian C++ functions

When you write Standard C++ +code that calls Symbian C++ functions ensure that you adhere to the following +guidelines:

Use the STDCPP keyword +in the .mmp file or have an STD target +type.
Use only the Standard +C++ semantics of the global operator new.
Your code must not depend +on One Definition Rule (ODR) across DLL boundaries. For more information, +see the Use +of one definition rule section.
Use barrier mechanisms while calling leaving functions of Symbian C++. +Here barrier mechanisms are barriers for exception propagation in terms of +TRAPs.

Note: Before you write a Standard C++ library, see the Guidelines for Writing Standard +C++ Libraries section.

Barrier +mechanisms for writing Standard C++ code

Leaving functions of +Symbian C++ that are called from Standard C++ code must be called under a +TRAP as shown in the following code:

TRAPD (err, GetAnotherK1LC());

This enables a leaving function to have the items on the cleanup stack removed +that were added by this function itself (or any of its callees). Otherwise, +this can cause problems illustrated in the Standard +C++ calling Symbian C++ functions section.

Note: For +more information about the leave-idiom on Symbian C++, see the Lifetimes +in Symbian platform topic under the Object +lifetimes and cleanup section.

The error code err can +then be translated to throw a corresponding Standard C++ exception using the TranslateSymErrorToCppException utility +function. This function is declared in stdcpp_support.h.

Alternatively, +you can also use the following utility macro:

TRANSLATE_SYM_CPP_LEAVES (CallSymbianOSCppL());

This macro calls the leaving function under a TRAP and if there is error, +it throws the corresponding Standard C++ exception. The following table illustrates +the mapping between an error and an exception:

+ + + +Error +Exception + + + + +

KErrNoMemory

std::bad_alloc

+ + +

KErrArgument

std::invalid_argument

+ + +

KErrOverflow

std::overflow_error

+ + +

KErrUnderflow

std::underflow_error

+ + +

Other errors

Symbian_error

+ + + +

Symbian C++ +code calling Standard C++ functions

When you write Symbian C++ +code that calls Standard C++ functions ensure that you adhere to the following +guidelines:

Use the Symbian C++ +semantics of the global operator new.
Use barrier mechanisms while calling Standard C++ functions. Here, barrier +mechanisms are barriers for exception propagation in terms of catch handlers +or exception-specification (of a function)

Barrier mechanisms +for writing Symbian C++ code

A Standard C++ function that can +throw must be called using a catch-handler. You can use catch-handlers for +non-leaving functions as illustrated in the following code:

void SymbianCppFunction() + { + try + { + // This is calling a StdC++ function that may throw any exception. + CppCallee(aK1, anotherK1); + } + catch (std::exception aException) + { + // Catch all the standard C++ exceptions and translate them + // to an appropriate Symbian platform error code using the following + //utility function + error = TranslateCppExceptionToSymError(aException); + } + catch (X aX) + { + // The barrier can look for any call site specific exceptions that it + // knows about and wants to treat specially + } + catch (...) + { + // catch all + } + }

You can use catch-handlers for leaving functions as illustrated +in the following code:

void SymbianCppFunctionL() + { + try + { + // This is calling a StdC++ function that may throw any exception. + CppCallee(aK1, anotherK1); + } + catch (std::exception aException) + { + // Catch all the standard C++ exceptions and translate them + // to an appropriate Symbian platform error code using the following + //utility function + TInt error = TranslateCppExceptionToSymError(aException); + User::Leave(error); + } + catch (X aX) + { + // The barrier can look for any call site specific exceptions that it + // knows about and wants to treat specially + TInt error; + //set the error here + User::Leave(error); + } + catch (...) + { + // catch all + TInt error; + //set the error here + User::Leave(error); + } + }