|
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> |