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-5107ABD8-6408-5501-8073-ACAF3719247B" xml:lang="en"><title>Resizable

    13 buffer descriptors</title><shortdesc>Describes descriptor behaviour and resizable buffer descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>A resizable buffer descriptor provides a buffer, allocated on the heap,

    15 to contain and access data. The data is not part of the descriptor object. </p>

    16 <p>The data represented by this descriptor can be both accessed and changed

    17 through the descriptor itself. Data is accessed through functions provided

    18 by the base class. The size of the buffer used by this descriptor can also

    19 be changed. Note that unlike dynamic buffers, reallocation is not done automatically;

    20 the descriptor provides an API that allows you to do reallocation. </p>

    21 <p>The descriptor has similarities to the standard heap descriptor,<xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>,

    22 but is <i>easier to use</i>. The standard heap descriptor is recommended for

    23 use when the data it represents rarely changes. The resizable buffer descriptor

    24 is recommended for use when the data changes frequently. </p>

    25 <p>This descriptor also has the following additional useful behaviour: </p>

    26 <ul>

    27 <li id="GUID-A40D7342-C864-51A3-B53B-DA73988501C2"><p>ownership of an existing

    28 heap descriptor can be transferred to a resizable buffer descriptor. </p> </li>

    29 <li id="GUID-63EA50EE-1DD4-5ABE-9676-0347E95F07CA"><p>ownership of memory

    30 that has already been allocated elsewhere can be transferred to a resizable

    31 buffer descriptor; this memory becomes the buffer used by the descriptor. </p> </li>

    32 <li id="GUID-D16CAA95-26A4-5B45-AEA2-58DDB28F16CB"><p>ownership of memory

    33 owned by a resizable buffer descriptor can be transferred to another resizable

    34 buffer descriptor. </p> </li>

    35 </ul>

    36 <p>The important point is that the user of the class need not be concerned

    37 about the 'origins' of the memory. </p>

    38 <p>A resizable buffer descriptor is supplied in two variants: </p>

    39 <ul>

    40 <li id="GUID-017A1851-A5FE-5179-87BC-0F0BF748761A"><p>a 16-bit variant, a <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref>,

    41 to contain wide strings, and 16-bit wide data. </p> </li>

    42 <li id="GUID-55A2D978-C16A-58E7-BE55-9CB681484473"><p>an 8-bit variant, a <xref href="GUID-955061A8-A83E-39E5-8745-8FAC7DEA7BCC.dita"><apiname>RBuf8</apiname></xref>,

    43 to contain narrow strings and binary data. </p> </li>

    44 </ul>

    45 <p>There is also a build independent type, <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>. This is

    46 the type that is most commonly used in program code; this is set (i.e. typedef)

    47 to the appropriate 'real' variant at build time, and by default equates to <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref>. </p>

    48 <p>You would use an explicit 8-bit variant for binary data. An explicit 16-bit

    49 variant is rarely used. </p>

    50 <p>When discussing a resizable buffer descriptor, we normally refer to <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>,

    51 rather than <xref href="GUID-955061A8-A83E-39E5-8745-8FAC7DEA7BCC.dita"><apiname>RBuf8</apiname></xref> or <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita"><apiname>RBuf16</apiname></xref>. We only

    52 refer to <codeph>RBuf8</codeph> or <codeph>RBuf16</codeph> when they explicitly

    53 need to be used. </p>

    54 <p>The following drawing shows how an <codeph>RBuf</codeph> type is constructed.

    55 It is derived from <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> and <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref>; the

    56 member data of these base classes hold the length and maximum length for the

    57 descriptor data. <codeph>RBuf</codeph> itself only contains a single pointer.

    58 The pointer is interpreted in one of two ways, depending on how its buffer

    59 has been set up: </p>

    60 <ul>

    61 <li id="GUID-8EB79399-9FAF-5CFE-9542-C015215B0D8D"><p>as a simple pointer

    62 to memory on the heap. </p> </li>

    63 <li id="GUID-645528B9-2786-59E1-9F6F-7DD875AE1B1E"><p>as a pointer to a previously

    64 created <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> heap descriptor; ownership of the <codeph>HBufC</codeph> descriptor

    65 buffer will have been transferred to the <codeph>RBuf</codeph>. </p> </li>

    66 </ul>

    67 <p>The way descriptors in Symbian OS are implemented allows <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> to

    68 distinguish between the two. </p>

    69 <p>The following drawing shows the internal representation of an <codeph>RBuf</codeph> object

    70 initialised with a string of five characters representing the English word

    71 "Hello". There are two possibilities: </p>

    72 <ul>

    73 <li id="GUID-3934910A-431A-582A-A117-3B1C497CE880"><p>the case where the buffer

    74 consists of simple memory, either allocated directly by the object itself,

    75 or assigned to it after having been allocated elsewhere. </p> </li>

    76 <li id="GUID-5AD86C97-66DF-5B88-95D7-2169D4CFD8A2"><p>the case where the buffer

    77 was originally allocated as a standard heap descriptor, a <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> type,

    78 and whose ownership has been transferred. </p> </li>

    79 </ul>

    80 <p>Remember that <codeph>RBuf</codeph> is derived from both <codeph>TDes</codeph> and <codeph>TDesC</codeph>,

    81 and these classes provide the data members the contain the maximum length

    82 and the current length of the data. </p>

    83 <fig id="GUID-50810FFC-9A97-5EC1-B6A6-7E371AEC9FF6">

    84 <image href="GUID-2F0008EB-715C-50EC-87AD-C78619F44858_d0e196257_href.png" placement="inline"/>

    85 </fig>

    86 <p>While an <codeph>RBuf</codeph> descriptor has similarities to a heap descriptor,

    87 it behaves more like a standard 'R' type resource class, i.e. as a handle

    88 to a real resource maintained elsewhere. </p>

    89 </conbody></concept>