--- a/Symbian3/SDK/Source/GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,48 +1,48 @@
-<?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-074F3499-54FE-58BC-A0F4-D8EA632AF76B"><title>Externalising a Swizzle</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Typically, externalizing a Swizzle is a two stage process which involves:</p> <ul><li id="GUID-EB65444C-7693-53BB-B3B8-D072F80B0CFD"><p>externalizing the in-memory object which the Swizzle represents, to its own stream</p> </li> <li id="GUID-90A275E2-B9C2-5162-ADBA-1035102A93E1"><p>externalizing the resulting stream ID.</p> </li> </ul> <p>For example, given a container type object, <codeph>CClassABC</codeph>, with a data member <codeph>TSwizzle<CClassB> iB</codeph> representing a <codeph>CClassB</codeph> object in memory, the diagram below illustrates the result of storing the container object.</p> <fig id="GUID-E32084CE-13EE-5F32-A62E-A57C30768AE2"><image href="GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e363478_href.png" placement="inline"/></fig> <p>The following code fragments illustrates the process.</p> <p><codeph>iB</codeph> is a <codeph>CClassB</codeph> type component of a class <codeph>CClassABC</codeph>, and is represented by a Swizzle. The data member is defined as:</p> <codeblock id="GUID-9751293C-D5CD-5397-97F3-C0E5F4A877DF" xml:space="preserve">class CCClassABC : public CBase
- {
- ...
- TSwizzle<CClassB> iB;
- ...
- }
-</codeblock> <p>Typically, a <codeph>CClassB</codeph> object is constructed and assigned to <codeph>iB</codeph>; this uses the Swizzle’s assignment operator:</p> <codeblock id="GUID-02F520BA-6A07-5E2B-97A9-191914623592" xml:space="preserve">iB = CClassB::NewL();</codeblock> <p>The Swizzle now represents the <codeph>CClassB</codeph> object by pointer.</p> <p>The <codeph>StoreL()</codeph> member function of <codeph>CClassABC</codeph> constructs a store map, an object of type <codeph>CStoreMap</codeph>, before calling <codeph>StoreComponentsL()</codeph> to externalise the swizzled <codeph>CClassB</codeph> object to its own stream.</p> <codeblock id="GUID-CDF0EC55-46A6-508A-8709-9B7108FCD0FE" xml:space="preserve">TStreamId CClassABC::StoreL() const
- {
- CStoreMap* map=CStoreMap::NewLC(iStore);
- StoreComponentsL(*map);
-
- RStoreWriteStream stream(*map);
- TStreamId id=stream.CreateLC(iStore);
- ExternalizeL(stream);
- stream.CommitL();
-
- map->Reset();
- CleanupStack::PopAndDestroy(2);
- return id;
- }</codeblock> <p>The variable <codeph>iStore</codeph> is a member of <codeph>CClassABC</codeph> containing a reference to the store.</p> <p><codeph>StoreComponentsL()</codeph> externalises the swizzled <codeph>CClassB</codeph> object by calling <codeph>CClassB</codeph> ’s own <codeph>StoreL()</codeph> member function which constructs a stream, externalises itself to the stream and returns the ID of that stream:</p> <codeblock id="GUID-79BAEB04-48E0-5741-AD12-7D7D85728FBE" xml:space="preserve">void CClassABC::StoreComponentsL(CStoreMap& aMap) const
- {
- ...
- TStreamId id;
- if (iB)
- {
- id = iB->StoreL(iStore); // Id of the CClassB stream
- aMap.BindL(iB,id);
- }
- ...
- }</codeblock> <p>The Swizzle must represent the <codeph>CClassB</codeph> type object as a pointer, i.e. the swizzled object must be in memory. The <codeph>operator-></codeph> applied to the Swizzle <codeph>iB</codeph> gives access to the <codeph>StoreL()</codeph> member function of the <codeph>CClassB</codeph> object.</p> <p>The condition <codeph>if (iB)</codeph> is equivalent to <codeph>if
- (iB.IsPtr())</codeph> and returns true only if the Swizzle represents the <codeph>CClassB</codeph> object as a pointer . The act of externalizing the <codeph>CClassB</codeph> object, does not, and need not change the way that the Swizzle represents that object. Here, the <codeph>CClassB</codeph> object remains in memory and the Swizzle maintains its representation of it as a pointer, even after it has been externalised.</p> <p>The Stream ID of the externalised <codeph>CClassB</codeph> object is stored in the store map along with the associated Swizzle using <codeph>CStoreMap</codeph> ’s <codeph>BindL()</codeph> member function .The store map is used again later when the stream ID is externalised as part of <codeph>CClassABC</codeph> ’s data.</p> <p>The <codeph>ExternalizeL()</codeph> member function of <codeph>CClassABC</codeph> externalises <codeph>CClassABC</codeph>'s member data. This includes the stream ID of the externalised <codeph>CClassB</codeph> object which is externalised by applying the templated stream <codeph>operator<<</codeph> to the Swizzle <codeph>iB</codeph>.</p> <codeblock id="GUID-8F144C77-D4CE-58BD-8155-65BCCFA31DA2" xml:space="preserve">void CCompound::ExternalizeL(RWriteStream& aStream) const
- {
- ...
- aStream << iB
- ...
- }
-</codeblock> <p>At this point, the Swizzle still represents the <codeph>CClassB</codeph> object as a pointer, and the object itself is still in memory.</p> <p>The mechanism underlying the implementation of the stream <codeph>operator<<</codeph>, assumes that the stream ID associated with the Swizzle has been placed in the store map. It also assumes that the <codeph>RStoreWriteStream</codeph> object has been constructed, specifying the store map as an externalizer.</p> <p>The end result of the operation <codeph>aStream << iB;</codeph>, is to externalise, to the stream, the stream ID associated with the Swizzle <codeph>iB</codeph>. The following diagram shows this:</p> <fig id="GUID-0958AA91-661B-54EA-B540-067DB933169D"><image href="GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e363662_href.png" placement="inline"/></fig> </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 xml:lang="en" id="GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B"><title>Externalising a Swizzle</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>Typically, externalizing a Swizzle is a two stage process which involves:</p> <ul><li id="GUID-EB65444C-7693-53BB-B3B8-D072F80B0CFD"><p>externalizing the in-memory object which the Swizzle represents, to its own stream</p> </li> <li id="GUID-90A275E2-B9C2-5162-ADBA-1035102A93E1"><p>externalizing the resulting stream ID.</p> </li> </ul> <p>For example, given a container type object, <codeph>CClassABC</codeph>, with a data member <codeph>TSwizzle<CClassB> iB</codeph> representing a <codeph>CClassB</codeph> object in memory, the diagram below illustrates the result of storing the container object.</p> <fig id="GUID-E32084CE-13EE-5F32-A62E-A57C30768AE2"><image href="GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e357398_href.png" placement="inline"/></fig> <p>The following code fragments illustrates the process.</p> <p><codeph>iB</codeph> is a <codeph>CClassB</codeph> type component of a class <codeph>CClassABC</codeph>, and is represented by a Swizzle. The data member is defined as:</p> <codeblock id="GUID-9751293C-D5CD-5397-97F3-C0E5F4A877DF" xml:space="preserve">class CCClassABC : public CBase
+ {
+ ...
+ TSwizzle<CClassB> iB;
+ ...
+ }
+</codeblock> <p>Typically, a <codeph>CClassB</codeph> object is constructed and assigned to <codeph>iB</codeph>; this uses the Swizzle’s assignment operator:</p> <codeblock id="GUID-02F520BA-6A07-5E2B-97A9-191914623592" xml:space="preserve">iB = CClassB::NewL();</codeblock> <p>The Swizzle now represents the <codeph>CClassB</codeph> object by pointer.</p> <p>The <codeph>StoreL()</codeph> member function of <codeph>CClassABC</codeph> constructs a store map, an object of type <codeph>CStoreMap</codeph>, before calling <codeph>StoreComponentsL()</codeph> to externalise the swizzled <codeph>CClassB</codeph> object to its own stream.</p> <codeblock id="GUID-CDF0EC55-46A6-508A-8709-9B7108FCD0FE" xml:space="preserve">TStreamId CClassABC::StoreL() const
+ {
+ CStoreMap* map=CStoreMap::NewLC(iStore);
+ StoreComponentsL(*map);
+
+ RStoreWriteStream stream(*map);
+ TStreamId id=stream.CreateLC(iStore);
+ ExternalizeL(stream);
+ stream.CommitL();
+
+ map->Reset();
+ CleanupStack::PopAndDestroy(2);
+ return id;
+ }</codeblock> <p>The variable <codeph>iStore</codeph> is a member of <codeph>CClassABC</codeph> containing a reference to the store.</p> <p><codeph>StoreComponentsL()</codeph> externalises the swizzled <codeph>CClassB</codeph> object by calling <codeph>CClassB</codeph> ’s own <codeph>StoreL()</codeph> member function which constructs a stream, externalises itself to the stream and returns the ID of that stream:</p> <codeblock id="GUID-79BAEB04-48E0-5741-AD12-7D7D85728FBE" xml:space="preserve">void CClassABC::StoreComponentsL(CStoreMap& aMap) const
+ {
+ ...
+ TStreamId id;
+ if (iB)
+ {
+ id = iB->StoreL(iStore); // Id of the CClassB stream
+ aMap.BindL(iB,id);
+ }
+ ...
+ }</codeblock> <p>The Swizzle must represent the <codeph>CClassB</codeph> type object as a pointer, i.e. the swizzled object must be in memory. The <codeph>operator-></codeph> applied to the Swizzle <codeph>iB</codeph> gives access to the <codeph>StoreL()</codeph> member function of the <codeph>CClassB</codeph> object.</p> <p>The condition <codeph>if (iB)</codeph> is equivalent to <codeph>if
+ (iB.IsPtr())</codeph> and returns true only if the Swizzle represents the <codeph>CClassB</codeph> object as a pointer . The act of externalizing the <codeph>CClassB</codeph> object, does not, and need not change the way that the Swizzle represents that object. Here, the <codeph>CClassB</codeph> object remains in memory and the Swizzle maintains its representation of it as a pointer, even after it has been externalised.</p> <p>The Stream ID of the externalised <codeph>CClassB</codeph> object is stored in the store map along with the associated Swizzle using <codeph>CStoreMap</codeph> ’s <codeph>BindL()</codeph> member function .The store map is used again later when the stream ID is externalised as part of <codeph>CClassABC</codeph> ’s data.</p> <p>The <codeph>ExternalizeL()</codeph> member function of <codeph>CClassABC</codeph> externalises <codeph>CClassABC</codeph>'s member data. This includes the stream ID of the externalised <codeph>CClassB</codeph> object which is externalised by applying the templated stream <codeph>operator<<</codeph> to the Swizzle <codeph>iB</codeph>.</p> <codeblock id="GUID-8F144C77-D4CE-58BD-8155-65BCCFA31DA2" xml:space="preserve">void CCompound::ExternalizeL(RWriteStream& aStream) const
+ {
+ ...
+ aStream << iB
+ ...
+ }
+</codeblock> <p>At this point, the Swizzle still represents the <codeph>CClassB</codeph> object as a pointer, and the object itself is still in memory.</p> <p>The mechanism underlying the implementation of the stream <codeph>operator<<</codeph>, assumes that the stream ID associated with the Swizzle has been placed in the store map. It also assumes that the <codeph>RStoreWriteStream</codeph> object has been constructed, specifying the store map as an externalizer.</p> <p>The end result of the operation <codeph>aStream << iB;</codeph>, is to externalise, to the stream, the stream ID associated with the Swizzle <codeph>iB</codeph>. The following diagram shows this:</p> <fig id="GUID-0958AA91-661B-54EA-B540-067DB933169D"><image href="GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e357582_href.png" placement="inline"/></fig> </conbody></concept>
\ No newline at end of file