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-C8C2645A-F5A4-53F0-8F43-485FC0B472DC" xml:lang="en"><title>External

    13 and internal representations</title><shortdesc>Describes the <codeph>Internalize()</codeph> and <codeph>Externalize()</codeph> functions

    14 for representing objects.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>Since packages may be used to describe an object of any type, and may be

    16 conveniently written to a file and sent over communications links, it is tempting

    17 to use them to transmit all application data types.</p>

    18 <p><note>This is strongly discouraged in Symbian platform programming.</note> </p>

    19 <p>Packages directly package the <i>internal</i> representation of an object.

    20 They should only be used when the internal representation is expected by all

    21 recipients of the package. This would be the case, say, with inter thread

    22 data transfer or certain rare types of file.</p>

    23 <p>When an object is stored on file, or sent over a link, it is usually desirable

    24 to define an <i>external</i> representation which may be safely read by <i>any</i> Symbian

    25 platform implementation, even on a machine with different endianness, different

    26 compiler options, and different machine word size.</p>

    27 <p>In such a case, writing a struct directly is inappropriate. Instead, the <codeph>InternalizeL()</codeph> and <codeph>ExternalizeL()</codeph> functions

    28 should be implemented for the object and should encapsulate all internalisation

    29 and externalisation. The stream interface should be used, which may refer

    30 to file, communications, clipboard and a number of other possibilities.</p>

    31 </conbody></concept>