<?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 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 platform</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 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>
</related-links></concept>