--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,188 @@
+<?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>
\ No newline at end of file