<?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-744ACF2C-963B-5E2F-A6B3-220AB899FD23"><title>Streaming Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>Streams abstract the external storage of data (typically objects).</p> </section> <section><title>Architectural relationships</title> <p>The Streaming API is abstract. It defines interfaces for reading and writing data to and from storage, but not what that storage is. Derived classes in other APIs provide particular implementations of streams: </p> <ul><li id="GUID-3D731714-A0B4-5A19-99AA-94BAB5A00322"><p>file streams, as defined in the File Stores API</p> </li> <li id="GUID-77BB88A4-429E-5708-9425-067CEDC7AA50"><p>streams used as part of a network of related streams, called a store, as defined in the Stores API </p> </li> <li id="GUID-D8977D11-3617-52C9-83D4-6EB222521A01"><p>memory-based streams, as defined in the Memory Streams API</p> </li> <li id="GUID-45D95878-018F-5697-B31D-E2F06AA1D988"><p>encrypted streams, as defined in the Encrypted Streams And Stores API</p> </li> </ul> </section> <section><title>Description</title> <p>The API has two key concepts: stream, and stream operators. </p> <p><b>Stream</b> </p> <p>A stream is a representation of an object as a sequence of bytes. Streams are accessed by means of write streams, which allow data to be written to them, and read streams, which allow data to be read. </p> <p>Data written to a stream should be in an external format: i.e. not depend on machine-specific properties such as endianness and padding. C++ classes designed to work with streams implement a function to externalise their state, and similarly an internalise function to set their state from a stream. The convention is to call these functions <codeph>ExternalizeL()</codeph> and <codeph>InternalizeL()</codeph> respectively.</p> <p>Write streams are represented by the abstract class <xref href="GUID-ADAC48A2-3D24-306B-9473-70201F4D351D.dita"><apiname>RWriteStream</apiname></xref>, and read streams by the abstract class <xref href="GUID-81056EAD-722C-373F-A8CF-4CC67A5B4468.dita"><apiname>RReadStream</apiname></xref>.</p> <p><b>Stream operators</b> </p> <p>The stream operators define (using templates) &lt;&lt; and &gt;&gt; so that objects can be written to streams using the format <codeph>astream &lt;&lt; anobject</codeph> astream &lt;&lt; anobject, and internalised using <codeph>astream &gt;&gt; anobject</codeph>. These translate into calls to the object's <codeph>ExternalizeL()</codeph> and <codeph>InternalizeL()</codeph> functions respectively. The operators are also defined so that they can be used with basic types such as <xref href="GUID-F2669E84-D47E-3C83-A549-D77A883787CC.dita"><apiname>TInt8</apiname></xref>, <xref href="GUID-58CA4B68-0A0F-31E2-A624-0F78F47EE458.dita"><apiname>TReal32</apiname></xref>, etc.</p> </section> <section><title>See also</title> <p><xref href="GUID-21CF1D5F-44C5-5407-B3C9-8BC103C97079.dita">File Stores Overview</xref> </p> <p><xref href="GUID-5EAED550-5FFC-54A6-BB4A-720975B127B8.dita">Stores Overview</xref> </p> </section> </conbody></concept>