<?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-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6" xml:lang="en"><title>Use

Cases for Writing Standard C++ Code</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The following topics describe the use cases based on which you can write

Standard C++ code on the Symbian platform: </p>

<ul>

<li id="GUID-FE4675CC-A3B2-5487-8318-996810CED805"><p><xref href="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita#GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6/GUID-20DCAC0E-D335-55A7-ADDE-17245D591970">Standard C++ code using STL or Standard C</xref>  </p> </li>

<li id="GUID-6AE48560-9481-511F-9165-FA9F15E36D2F"><p><xref href="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita#GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6/GUID-4024FCCD-7A54-50EE-BCDD-72BC23A34CD8">Standard C++ code calling Symbian C++ functions</xref>  </p> </li>

<li id="GUID-84E464CC-B1D3-51FD-85B3-2984F042204E"><p><xref href="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita#GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6/GUID-B6F7FA56-D3DD-5638-A1E9-676B7C4354BD">Symbian C++ code calling Standard C++ functions</xref>  </p> </li>

</ul>

<section id="GUID-20DCAC0E-D335-55A7-ADDE-17245D591970"><title> Standard C++

code using STL or Standard C</title> <p>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: </p> <ol id="GUID-19F8A9FD-550E-5CEE-A481-24A82BC70DD0">

<li id="GUID-5107C1FB-E3B8-5680-8295-FD6860A76710"><p>Use the <codeph>STDCPP</codeph> keyword

in the <filepath>.mmp</filepath> file or you target type must be an <codeph>STD</codeph> target

type. </p> </li>

<li id="GUID-1E1A166A-F7A9-5B6A-A7BC-F143FCDCACED"><p>Use only the Standard

C++ semantics of the global <codeph>operator                 new</codeph>. </p> </li>

<li id="GUID-32B3C42A-9291-57C5-8030-F3966FC64AF4"><p>Your code must not depend

on One Definition Rule (ODR) across DLL boundaries. For more information,

see the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-A85386B3-3E37-5303-8FBF-211551D5CB71">Use

of one definition rule</xref> section. </p> </li>

</ol> <p> <b>Notes:</b>  </p> <ul>

<li id="GUID-32BC5E8B-3C8C-59C5-A361-6184B0123563"><p>If these guidelines

are not followed, it can result in problems described in the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita">Possible

Problems</xref> section. </p> </li>

<li id="GUID-F75F3E1A-195B-5326-8A7D-4667D43BEF0A"><p>Before you write a Standard

C++ library, see the <xref href="GUID-C9D4D586-58BF-5676-A53F-9C3A51101430.dita">Guidelines

for Writing Standard C++ Libraries</xref> section. </p> </li>

</ul> </section>

<section id="GUID-4024FCCD-7A54-50EE-BCDD-72BC23A34CD8"><title>Standard C++

code calling Symbian C++ functions</title> <p>When you write Standard C++

code that calls Symbian C++ functions ensure that you adhere to the following

guidelines: </p> <ol id="GUID-FABDAF1D-3BBE-55CA-9F8B-9AE140A4B556">

<li id="GUID-6CC66050-575D-50FD-BF22-68BE09721B9D"><p>Use the <codeph>STDCPP</codeph> keyword

in the <filepath>.mmp</filepath> file or have an <codeph>STD</codeph> target

type. </p> </li>

<li id="GUID-2C217279-A018-5F11-A4D9-F69CDBD84EEA"><p>Use only the Standard

C++ semantics of the global <codeph>operator                 new</codeph>. </p> </li>

<li id="GUID-13155A1C-7E78-5036-AFD8-C0458DCEBE9D"><p>Your code must not depend

on One Definition Rule (ODR) across DLL boundaries. For more information,

see the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-A85386B3-3E37-5303-8FBF-211551D5CB71">Use

of one definition rule</xref> section. </p> </li>

<li id="GUID-9A449F22-6905-54AF-B7AA-F07737368126"><p>Use <xref href="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita#GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6/GUID-A37EF5D8-67AD-5DC3-983C-A9E37A3E9D3C">barrier mechanisms</xref> while calling leaving functions of Symbian C++.

Here barrier mechanisms are barriers for exception propagation in terms of

TRAPs. </p> </li>

</ol> <p> <b>Note:</b> Before you write a Standard C++ library, see the <xref href="GUID-C9D4D586-58BF-5676-A53F-9C3A51101430.dita">Guidelines for Writing Standard

C++ Libraries</xref> section. </p> <p id="GUID-A37EF5D8-67AD-5DC3-983C-A9E37A3E9D3C"><b> Barrier

mechanisms for writing Standard C++ code</b> </p> <p>Leaving functions of

Symbian C++ that are called from Standard C++ code must be called under a

TRAP as shown in the following code: </p> <codeblock id="GUID-D1A75E6A-4BFC-51EC-8E50-4C1C2D09175F" xml:space="preserve">TRAPD (err, GetAnotherK1LC());</codeblock> <p>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 <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-6CE49D59-46BB-5145-B346-6FD3EA8BC011">Standard

C++ calling Symbian C++ functions</xref> section. </p> <p> <b>Note:</b> For

more information about the leave-idiom on Symbian C++, see the <b>Lifetimes

in Symbian</b> topic under the <xref href="GUID-1FFE4ED5-7B2E-58A0-9D08-A096F53F37AB.dita">Object

lifetimes and cleanup</xref> section. </p> <p>The error code <codeph>err</codeph> can

then be translated to throw a corresponding Standard C++ exception using the <codeph>TranslateSymErrorToCppException</codeph> utility

function. This function is declared in <filepath>stdcpp_support.h</filepath>. </p> <p>Alternatively,

you can also use the following utility macro: </p> <codeblock id="GUID-0216AF20-BB11-561E-8F2A-C9F2E17EF23B" xml:space="preserve">TRANSLATE_SYM_CPP_LEAVES (CallSymbianOSCppL());</codeblock> <p>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: </p> <table id="GUID-A037AA99-8D1B-595E-B36E-E6BCEB7C8E25">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Error</entry>

<entry>Exception</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>KErrNoMemory</codeph>  </p> </entry>

<entry><p> <codeph>std::bad_alloc</codeph>  </p> </entry>

</row>

<row>

<entry><p> <codeph>KErrArgument</codeph>  </p> </entry>

<entry><p> <codeph>std::invalid_argument</codeph>  </p> </entry>

</row>

<row>

<entry><p> <codeph>KErrOverflow</codeph>  </p> </entry>

<entry><p> <codeph>std::overflow_error</codeph>  </p> </entry>

</row>

<row>

<entry><p> <codeph>KErrUnderflow</codeph>  </p> </entry>

<entry><p> <codeph>std::underflow_error</codeph>  </p> </entry>

</row>

<row>

<entry><p>Other errors </p> </entry>

<entry><p> <codeph>Symbian_error</codeph>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section id="GUID-B6F7FA56-D3DD-5638-A1E9-676B7C4354BD"><title>Symbian C++

code calling Standard C++ functions</title> <p>When you write Symbian C++

code that calls Standard C++ functions ensure that you adhere to the following

guidelines: </p> <ol id="GUID-B2C94D28-6AF6-565B-A575-0B950B9B46B1">

<li id="GUID-C0B7A2DE-9FF2-55E0-AB15-C90AAA76B997"><p>Use the Symbian C++

semantics of the global <codeph>operator                 new</codeph>. </p> </li>

<li id="GUID-A89D2A48-2885-5E7C-81AB-DEA4E75A8034"><p>Use <xref href="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita#GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6/GUID-0D05436A-6B25-5D48-A13F-D959762860D3">barrier mechanisms</xref> while calling Standard C++ functions. Here, barrier

mechanisms are barriers for exception propagation in terms of catch handlers

or exception-specification (of a function) </p> </li>

</ol> <p id="GUID-0D05436A-6B25-5D48-A13F-D959762860D3"><b> Barrier mechanisms

for writing Symbian C++ code</b> </p> <p>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: </p> <codeblock id="GUID-75C0497D-2E80-5440-B3A4-CD9A9D0465D0" xml:space="preserve">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 

        }

    }</codeblock> <p>You can use catch-handlers for leaving functions as illustrated

in the following code: </p> <codeblock id="GUID-770BA39D-C188-512C-9285-E93E2BCA3D2E" xml:space="preserve">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);

        }

    }</codeblock> </section>

</conbody><related-links>

<link href="GUID-D6BEAF0D-844D-51F4-8DB7-FB1D60E17FE3.dita"><linktext>Copyright

Acknowledgments for Standard C++ (STLport)</linktext></link>

<link href="GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita"><linktext>Standard

C++ Library Overview</linktext></link>

<link href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita"><linktext> Standard

C++ Support on the Symbian Platform</linktext></link>

<link href="GUID-E331B72B-84AF-558A-9B8F-73E5E50B58C7.dita"><linktext>Building

a Standard C++ Application or Library</linktext></link>

<link href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita"><linktext>Possible

Problems</linktext></link>

<link href="GUID-D32E52C9-F05C-5F1E-8B49-243D555C353C.dita"><linktext>Known Issues</linktext>

</link>

<link href="GUID-5B3F5296-D6D0-5D25-8362-141DF5927E52.dita"><linktext>Troubleshooting</linktext>

</link>