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-6468F3CB-7828-5746-A868-AD525EB7D6BD" xml:lang="en"><title>Introduction

    13 to dynamic buffers</title><shortdesc>Description of flat and segmented buffers in Symbian platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>A buffer is an area of memory which may contain data. Managing data in

    15 buffers can be more or less complex, depending on the requirements:</p>

    16 <ul>

    17 <li id="GUID-2892A824-D918-5998-9730-B780BBDE254C"><p>if the data is of fixed

    18 length, a fixed-length area of memory may be allocated, either on the stack

    19 or the heap; a buffer descriptor (<codeph>TBuf</codeph>) may be used for this.</p> </li>

    20 <li id="GUID-22EC8B3D-2230-597D-935D-37A5DBCF1094"><p>if the data is of varying

    21 length, but the variation is relatively small, it may still be appropriate

    22 to allocate the data within a non-extensible buffer such as <codeph>TBuf</codeph>:

    23 programming is simple, and only a little memory is wasted</p> </li>

    24 <li id="GUID-75E026E3-8C69-575C-A893-1A41192E9073"><p>if the data is of significantly

    25 varying length, the memory can be allocated on the heap, and the allocation

    26 extended when necessary. The <codeph>CBufFlat</codeph> class is provided to

    27 manage this</p> </li>

    28 <li id="GUID-C4B11D3C-A514-56FE-AAB1-24D658CDF921"><p>if the data’s length

    29 varies so much that a single heap cell cannot reasonably be expected to hold

    30 it all, then the data must be held in several heap cells, but these must appear

    31 as one for convenience. The <codeph>CBufSeg</codeph> class is provided to

    32 manage this</p> </li>

    33 </ul>

    34 <p>Symbian platform provides <i>flat buffers</i>, objects of type <codeph>CBufFlat</codeph>,

    35 which are used to allocate and manage storage in a single allocated cell</p>

    36 <p>Symbian platform provides <i>segmented buffers</i>, objects of type <codeph>CBufSeg</codeph>,

    37 which are used to allocate and manage storage in several alloc cells.</p>

    38 <p>Both types of buffer have a common base class, <codeph>CBufBase</codeph>.

    39 This class specifies the main aspects of the programming interface. Having

    40 a common base class allows the decision as to whether to use flat or segmented

    41 buffers to be changed during program development, with minimal impact on code.</p>

    42 </conbody></concept>