<?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&lt;CClassB&gt; 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_d0e584031_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&amp; 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-&gt;</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&lt;&lt;</codeph> to the Swizzle <codeph>iB</codeph>.</p> <codeblock id="GUID-8F144C77-D4CE-58BD-8155-65BCCFA31DA2" xml:space="preserve">void CCompound::ExternalizeL(RWriteStream&amp; 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&lt;&lt;</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 &lt;&lt; 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_d0e584215_href.png" placement="inline"/></fig> </conbody></concept>