--- a/Symbian3/PDK/Source/GUID-5829247E-2E8E-502F-9051-A59DA8EE71B0.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-5829247E-2E8E-502F-9051-A59DA8EE71B0.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,12 +1,53 @@
-<?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 xml:lang="en" id="GUID-5829247E-2E8E-502F-9051-A59DA8EE71B0"><title>CBase-derived classes and two-phase construction</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>When the construction of an object cannot leave (except for out-of-memory for the allocation of the object itself), then it is appropriate to use the conventional C++ constructor, which is automatically invoked by <codeph>new</codeph>. </p> <p>When the construction of an object may leave, then the object must be pushed to the clean-up stack, or a pointer to the object must be stored in an object that would be cleaned up if a leave occurred, <i>before</i> any part of the construction function is invoked that may leave. To allow this to happen, construction steps that can leave, are performed not in the C++ constructor, but in another initialisation functions, referred to as a second phase constructor.</p> <p>Thus, the general sequence for two-phase construction is:</p> <ol id="GUID-4EA8A66C-A0FA-58D4-BD86-7FD72029AA17"><li id="GUID-38D6D313-2348-5E1A-95BB-205AF451CC5D"><p>allocate memory for the object (and leave if out of memory) using <codeph>new</codeph> </p> </li> <li id="GUID-1BC50131-75C9-5EFF-9439-030FB35750F9"><p>optionally define a C++ constructor to perform any construction that cannot leave</p> </li> <li id="GUID-DA1E047E-40E6-5B71-BB02-C42C7B3609C8"><p>push a pointer to the object, or store a pointer to it in a class with cleanup support</p> </li> <li id="GUID-6FDA6D4A-9ECD-509D-9D0D-3E7234961657"><p>use the second phase constructor to perform any part of the construction that might leave</p> </li> </ol> <p>Note that:</p> <ul><li id="GUID-C67CA4EB-480A-5A5B-A4F5-B7206DBD3CFE"><p>The whole sequence is usually encapsulated in static member functions called <codeph>NewL()</codeph>, and <codeph>NewLC()</codeph> (which additionally leaves the created object on the clean-up stack).</p> </li> <li id="GUID-B0AC323F-EDF5-5BEE-B843-A46E5611B1F3"><p>Abstract classes are not intended to be instantiated, and so have no <codeph>NewLC()</codeph> or <codeph>NewL()</codeph>, only a second phase constructor.</p> </li> <li id="GUID-557838D0-10D0-55B3-9848-254065EFDFF4"><p>Step 2 is optional, because all such construction can be performed by the second phase constructor. The C++ constructor is only necessary when the class is immediately derived from a base class whose default C++ constructor cannot be used. In this case, the derived class must call the base class’s constructor with appropriate parameters.</p> </li> <li id="GUID-93707F75-0BB3-563F-B00C-35683DEE007C"><p>It is conventional for the second phase constructor to be called <codeph>ConstructL()</codeph>. </p> </li> </ul> </conbody></concept>
\ No newline at end of file
+<?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-5829247E-2E8E-502F-9051-A59DA8EE71B0" xml:lang="en"><title>CBase-derived
+classes and two-phase construction</title><shortdesc>This document describes the need for two-phase construction and
+how to use second phase constructors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>When the construction of an object cannot leave (except for out-of-memory
+for the allocation of the object itself), then it is appropriate to use the
+conventional C++ constructor, which is automatically invoked by <codeph>new</codeph>. </p>
+<p>When the construction of an object may leave, then the object must be pushed
+to the clean-up stack, or a pointer to the object must be stored in an object
+that would be cleaned up if a leave occurred, <i>before</i> any part of the
+construction function is invoked that may leave. To allow this to happen,
+construction steps that can leave, are performed not in the C++ constructor,
+but in another initialization functions, referred to as a second phase constructor.</p>
+<p>Thus, the general sequence for two-phase construction is:</p>
+<ol id="GUID-4EA8A66C-A0FA-58D4-BD86-7FD72029AA17">
+<li id="GUID-38D6D313-2348-5E1A-95BB-205AF451CC5D"><p>allocate memory for
+the object (and leave if out of memory) using <codeph>new</codeph> </p> </li>
+<li id="GUID-1BC50131-75C9-5EFF-9439-030FB35750F9"><p>optionally define a
+C++ constructor to perform any construction that cannot leave</p> </li>
+<li id="GUID-DA1E047E-40E6-5B71-BB02-C42C7B3609C8"><p>push a pointer to the
+object, or store a pointer to it in a class with cleanup support</p> </li>
+<li id="GUID-6FDA6D4A-9ECD-509D-9D0D-3E7234961657"><p>use the second phase
+constructor to perform any part of the construction that might leave</p> </li>
+</ol>
+<p>Note that:</p>
+<ul>
+<li id="GUID-C67CA4EB-480A-5A5B-A4F5-B7206DBD3CFE"><p>The whole sequence is
+usually encapsulated in static member functions called <codeph>NewL()</codeph>,
+and <codeph>NewLC()</codeph> (which additionally leaves the created object
+on the clean-up stack).</p> </li>
+<li id="GUID-B0AC323F-EDF5-5BEE-B843-A46E5611B1F3"><p>Abstract classes are
+not intended to be instantiated, and so have no <codeph>NewLC()</codeph> or <codeph>NewL()</codeph>,
+only a second phase constructor.</p> </li>
+<li id="GUID-557838D0-10D0-55B3-9848-254065EFDFF4"><p>Step 2 is optional,
+because all such construction can be performed by the second phase constructor.
+The C++ constructor is only necessary when the class is immediately derived
+from a base class whose default C++ constructor cannot be used. In this case,
+the derived class must call the base class’s constructor with appropriate
+parameters.</p> </li>
+<li id="GUID-93707F75-0BB3-563F-B00C-35683DEE007C"><p>It is conventional for
+the second phase constructor to be called <codeph>ConstructL()</codeph>. </p> </li>
+</ul>
+</conbody></concept>
\ No newline at end of file