Use Cases for Writing Standard C++ Code

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:

1. Use the STDCPP keyword in the .mmp file or you target type must be an STD target type.

2. Use only the Standard C++ semantics of the global operator new.

3. 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:

1. Use the STDCPP keyword in the .mmp file or have an STD target type.

2. Use only the Standard C++ semantics of the global operator new.

3. Your code must not depend on One Definition Rule (ODR) across DLL boundaries. For more information, see the Use of one definition rule section.

4. 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 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:

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:

1. Use the Symbian C++ semantics of the global operator new.

2. 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);
        }
    }