|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-1ACD01D1-2055-581A-9478-2C0D7D1CF9E6" xml:lang="en"><title>Use |
|
13 Cases for Writing Standard C++ Code</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The following topics describe the use cases based on which you can write |
|
15 Standard C++ code on the Symbian platform: </p> |
|
16 <ul> |
|
17 <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> |
|
18 <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> |
|
19 <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> |
|
20 </ul> |
|
21 <section id="GUID-20DCAC0E-D335-55A7-ADDE-17245D591970"><title> Standard C++ |
|
22 code using STL or Standard C</title> <p>You can write a pure Standard C++ |
|
23 application or library that does not use Symbian C++ directly. When you write |
|
24 Standard C++ code using STL or Standard C ensure that you adhere to the following |
|
25 guidelines: </p> <ol id="GUID-19F8A9FD-550E-5CEE-A481-24A82BC70DD0"> |
|
26 <li id="GUID-5107C1FB-E3B8-5680-8295-FD6860A76710"><p>Use the <codeph>STDCPP</codeph> keyword |
|
27 in the <filepath>.mmp</filepath> file or you target type must be an <codeph>STD</codeph> target |
|
28 type. </p> </li> |
|
29 <li id="GUID-1E1A166A-F7A9-5B6A-A7BC-F143FCDCACED"><p>Use only the Standard |
|
30 C++ semantics of the global <codeph>operator new</codeph>. </p> </li> |
|
31 <li id="GUID-32B3C42A-9291-57C5-8030-F3966FC64AF4"><p>Your code must not depend |
|
32 on One Definition Rule (ODR) across DLL boundaries. For more information, |
|
33 see the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-A85386B3-3E37-5303-8FBF-211551D5CB71">Use |
|
34 of one definition rule</xref> section. </p> </li> |
|
35 </ol> <p> <b>Notes:</b> </p> <ul> |
|
36 <li id="GUID-32BC5E8B-3C8C-59C5-A361-6184B0123563"><p>If these guidelines |
|
37 are not followed, it can result in problems described in the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita">Possible |
|
38 Problems</xref> section. </p> </li> |
|
39 <li id="GUID-F75F3E1A-195B-5326-8A7D-4667D43BEF0A"><p>Before you write a Standard |
|
40 C++ library, see the <xref href="GUID-C9D4D586-58BF-5676-A53F-9C3A51101430.dita">Guidelines |
|
41 for Writing Standard C++ Libraries</xref> section. </p> </li> |
|
42 </ul> </section> |
|
43 <section id="GUID-4024FCCD-7A54-50EE-BCDD-72BC23A34CD8"><title>Standard C++ |
|
44 code calling Symbian C++ functions</title> <p>When you write Standard C++ |
|
45 code that calls Symbian C++ functions ensure that you adhere to the following |
|
46 guidelines: </p> <ol id="GUID-FABDAF1D-3BBE-55CA-9F8B-9AE140A4B556"> |
|
47 <li id="GUID-6CC66050-575D-50FD-BF22-68BE09721B9D"><p>Use the <codeph>STDCPP</codeph> keyword |
|
48 in the <filepath>.mmp</filepath> file or have an <codeph>STD</codeph> target |
|
49 type. </p> </li> |
|
50 <li id="GUID-2C217279-A018-5F11-A4D9-F69CDBD84EEA"><p>Use only the Standard |
|
51 C++ semantics of the global <codeph>operator new</codeph>. </p> </li> |
|
52 <li id="GUID-13155A1C-7E78-5036-AFD8-C0458DCEBE9D"><p>Your code must not depend |
|
53 on One Definition Rule (ODR) across DLL boundaries. For more information, |
|
54 see the <xref href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita#GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46/GUID-A85386B3-3E37-5303-8FBF-211551D5CB71">Use |
|
55 of one definition rule</xref> section. </p> </li> |
|
56 <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++. |
|
57 Here barrier mechanisms are barriers for exception propagation in terms of |
|
58 TRAPs. </p> </li> |
|
59 </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 |
|
60 C++ Libraries</xref> section. </p> <p id="GUID-A37EF5D8-67AD-5DC3-983C-A9E37A3E9D3C"><b> Barrier |
|
61 mechanisms for writing Standard C++ code</b> </p> <p>Leaving functions of |
|
62 Symbian C++ that are called from Standard C++ code must be called under a |
|
63 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 |
|
64 that were added by this function itself (or any of its callees). Otherwise, |
|
65 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 |
|
66 C++ calling Symbian C++ functions</xref> section. </p> <p> <b>Note:</b> For |
|
67 more information about the leave-idiom on Symbian C++, see the <b>Lifetimes |
|
68 in Symbian</b> topic under the <xref href="GUID-1FFE4ED5-7B2E-58A0-9D08-A096F53F37AB.dita">Object |
|
69 lifetimes and cleanup</xref> section. </p> <p>The error code <codeph>err</codeph> can |
|
70 then be translated to throw a corresponding Standard C++ exception using the <codeph>TranslateSymErrorToCppException</codeph> utility |
|
71 function. This function is declared in <filepath>stdcpp_support.h</filepath>. </p> <p>Alternatively, |
|
72 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, |
|
73 it throws the corresponding Standard C++ exception. The following table illustrates |
|
74 the mapping between an error and an exception: </p> <table id="GUID-A037AA99-8D1B-595E-B36E-E6BCEB7C8E25"> |
|
75 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
76 <thead> |
|
77 <row> |
|
78 <entry>Error</entry> |
|
79 <entry>Exception</entry> |
|
80 </row> |
|
81 </thead> |
|
82 <tbody> |
|
83 <row> |
|
84 <entry><p> <codeph>KErrNoMemory</codeph> </p> </entry> |
|
85 <entry><p> <codeph>std::bad_alloc</codeph> </p> </entry> |
|
86 </row> |
|
87 <row> |
|
88 <entry><p> <codeph>KErrArgument</codeph> </p> </entry> |
|
89 <entry><p> <codeph>std::invalid_argument</codeph> </p> </entry> |
|
90 </row> |
|
91 <row> |
|
92 <entry><p> <codeph>KErrOverflow</codeph> </p> </entry> |
|
93 <entry><p> <codeph>std::overflow_error</codeph> </p> </entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><p> <codeph>KErrUnderflow</codeph> </p> </entry> |
|
97 <entry><p> <codeph>std::underflow_error</codeph> </p> </entry> |
|
98 </row> |
|
99 <row> |
|
100 <entry><p>Other errors </p> </entry> |
|
101 <entry><p> <codeph>Symbian_error</codeph> </p> </entry> |
|
102 </row> |
|
103 </tbody> |
|
104 </tgroup> |
|
105 </table> </section> |
|
106 <section id="GUID-B6F7FA56-D3DD-5638-A1E9-676B7C4354BD"><title>Symbian C++ |
|
107 code calling Standard C++ functions</title> <p>When you write Symbian C++ |
|
108 code that calls Standard C++ functions ensure that you adhere to the following |
|
109 guidelines: </p> <ol id="GUID-B2C94D28-6AF6-565B-A575-0B950B9B46B1"> |
|
110 <li id="GUID-C0B7A2DE-9FF2-55E0-AB15-C90AAA76B997"><p>Use the Symbian C++ |
|
111 semantics of the global <codeph>operator new</codeph>. </p> </li> |
|
112 <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 |
|
113 mechanisms are barriers for exception propagation in terms of catch handlers |
|
114 or exception-specification (of a function) </p> </li> |
|
115 </ol> <p id="GUID-0D05436A-6B25-5D48-A13F-D959762860D3"><b> Barrier mechanisms |
|
116 for writing Symbian C++ code</b> </p> <p>A Standard C++ function that can |
|
117 throw must be called using a catch-handler. You can use catch-handlers for |
|
118 non-leaving functions as illustrated in the following code: </p> <codeblock id="GUID-75C0497D-2E80-5440-B3A4-CD9A9D0465D0" xml:space="preserve">void SymbianCppFunction() |
|
119 { |
|
120 try |
|
121 { |
|
122 // This is calling a StdC++ function that may throw any exception. |
|
123 CppCallee(aK1, anotherK1); |
|
124 } |
|
125 catch (std::exception aException) |
|
126 { |
|
127 // Catch all the standard C++ exceptions and translate them |
|
128 // to an appropriate Symbian platform error code using the following |
|
129 //utility function |
|
130 error = TranslateCppExceptionToSymError(aException); |
|
131 } |
|
132 catch (X aX) |
|
133 { |
|
134 // The barrier can look for any call site specific exceptions that it |
|
135 // knows about and wants to treat specially |
|
136 } |
|
137 catch (...) |
|
138 { |
|
139 // catch all |
|
140 } |
|
141 }</codeblock> <p>You can use catch-handlers for leaving functions as illustrated |
|
142 in the following code: </p> <codeblock id="GUID-770BA39D-C188-512C-9285-E93E2BCA3D2E" xml:space="preserve">void SymbianCppFunctionL() |
|
143 { |
|
144 try |
|
145 { |
|
146 // This is calling a StdC++ function that may throw any exception. |
|
147 CppCallee(aK1, anotherK1); |
|
148 } |
|
149 catch (std::exception aException) |
|
150 { |
|
151 // Catch all the standard C++ exceptions and translate them |
|
152 // to an appropriate Symbian platform error code using the following |
|
153 //utility function |
|
154 TInt error = TranslateCppExceptionToSymError(aException); |
|
155 User::Leave(error); |
|
156 } |
|
157 catch (X aX) |
|
158 { |
|
159 // The barrier can look for any call site specific exceptions that it |
|
160 // knows about and wants to treat specially |
|
161 TInt error; |
|
162 //set the error here |
|
163 User::Leave(error); |
|
164 } |
|
165 catch (...) |
|
166 { |
|
167 // catch all |
|
168 TInt error; |
|
169 //set the error here |
|
170 User::Leave(error); |
|
171 } |
|
172 }</codeblock> </section> |
|
173 </conbody><related-links> |
|
174 <link href="GUID-D6BEAF0D-844D-51F4-8DB7-FB1D60E17FE3.dita"><linktext>Copyright |
|
175 Acknowledgments for Standard C++ (STLport)</linktext></link> |
|
176 <link href="GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita"><linktext>Standard |
|
177 C++ Library Overview</linktext></link> |
|
178 <link href="GUID-2CCD1748-9EDE-5383-9941-A3051E06F3E2.dita"><linktext> Standard |
|
179 C++ Support on the Symbian Platform</linktext></link> |
|
180 <link href="GUID-E331B72B-84AF-558A-9B8F-73E5E50B58C7.dita"><linktext>Building |
|
181 a Standard C++ Application or Library</linktext></link> |
|
182 <link href="GUID-AF2CE612-F12E-5A18-81A5-C303992D2D46.dita"><linktext>Possible |
|
183 Problems</linktext></link> |
|
184 <link href="GUID-D32E52C9-F05C-5F1E-8B49-243D555C353C.dita"><linktext>Known Issues</linktext> |
|
185 </link> |
|
186 <link href="GUID-5B3F5296-D6D0-5D25-8362-141DF5927E52.dita"><linktext>Troubleshooting</linktext> |
|
187 </link> |
|
188 </related-links></concept> |