|
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-A049B0C2-5C30-5B07-AC4F-32A75046B60B" xml:lang="en"><title>Buffer |
|
13 descriptors</title><shortdesc>Describes modifiable and non-modifiable buffer descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A buffer descriptor provides a fixed length buffer to contain and access |
|
15 data. The data is part of the descriptor object.</p> |
|
16 <p>A buffer descriptor object is an instance of a templated class, where the |
|
17 template parameter is an integer value that defines the size of the descriptor's |
|
18 data area.</p> |
|
19 <p>A buffer descriptor comes in two forms:</p> |
|
20 <ul> |
|
21 <li id="GUID-9F038469-EA34-5086-84AC-DEA306CC63FD"><p>a non-modifiable buffer |
|
22 descriptor.</p> </li> |
|
23 <li id="GUID-B4A065D3-31DE-5F2D-863F-C91B7A7200FF"><p>a modifiable buffer |
|
24 descriptor.</p> </li> |
|
25 </ul> |
|
26 <section id="GUID-96A5D9DD-7754-4AD7-9C8F-1F664DB4719D"><title>Non-modifiable buffer descriptor</title> <p>The data contained |
|
27 in a non-modifiable buffer descriptor can be accessed, but not changed, through |
|
28 this descriptor. The data can, however, be completely replaced using the assignment |
|
29 operators.</p> <p>Data is accessed through functions provided by the base |
|
30 class.</p> <p>A non-modifiable buffer descriptor is supplied in two variants:</p> <ul> |
|
31 <li id="GUID-30B702C6-238F-573A-8604-8CE126432723"><p>the 16 bit variant, |
|
32 a <codeph>TBufC16<TInt></codeph>, to contain Unicode strings.</p> </li> |
|
33 <li id="GUID-EC2B5476-257C-5DDC-B8AE-4F7F2AF8723E"><p>the 8 bit variant, a <codeph>TBufC8<TInt></codeph>, |
|
34 to contain non-Unicode strings and binary data.</p> </li> |
|
35 </ul> <p>There is also a build independent type, <codeph>TBufC<TInt></codeph>. |
|
36 This is the type which is most commonly used in program code; the appropriate |
|
37 variant is selected at build time.</p> <p>An explicit 8 bit variant is chosen |
|
38 for binary data. The explicit 16 bit variant is rarely used.</p> <p>The base |
|
39 class, <codeph>TDesC</codeph>, contains a data member which holds the length |
|
40 of the data. The following drawing shows the layout of a <codeph>TBufC<5></codeph> object |
|
41 initialised with the string of five characters representing the English word |
|
42 "Hello".</p> <fig id="GUID-12064B13-BA8E-5552-9907-AD4F28329A24"> |
|
43 <image href="GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e224367_href.png" placement="inline"/> |
|
44 </fig> </section> |
|
45 <section id="GUID-4FE409A2-F70B-4755-8C0F-E86799728550"><title>Modifiable buffer descriptor</title> <p>The data contained |
|
46 in a modifiable buffer descriptor can be both accessed and changed through |
|
47 this descriptor.</p> <p>The template parameter, as well as determining the |
|
48 size of the data area created as part of the descriptor object, also defines |
|
49 the maximum length of the descriptor.</p> <p>The length of the data can vary |
|
50 between zero and the maximum length. When the length of the data is less than |
|
51 the maximum, a portion of the data area within the descriptor is unused.</p> <p>Data |
|
52 is accessed and modified through functions provided by the base classes.</p> <p>A |
|
53 modifiable buffer descriptor is supplied in two variants:</p> <ul> |
|
54 <li id="GUID-6FA9F924-4EBF-5AAE-B2E8-DD67CE15C8EE"><p>the 16 bit variant, |
|
55 a <codeph>TBuf16<TInt></codeph>, to contain Unicode strings.</p> </li> |
|
56 <li id="GUID-F0C6A0B2-2ADF-5457-A910-6038816D95FD"><p>the 8 bit variant, a <codeph>TBuf8<TInt></codeph>, |
|
57 to contain non-Unicode strings and binary data.</p> </li> |
|
58 </ul> <p>There is also a build independent type, <codeph>TBuf<TInt></codeph>. |
|
59 This is the type which is most commonly used in program code; the appropriate |
|
60 variant is selected at build time.</p> <p>An explicit 8 bit variant is chosen |
|
61 for binary data. The explicit 16 bit variant is rarely used.</p> <p>The base |
|
62 class <codeph>TDesC</codeph>, contains a data member that holds the length |
|
63 of the data. The base class <codeph>TDes</codeph>, contains a data member |
|
64 that holds the maximum length of the data. The following drawing shows the |
|
65 layout of a <codeph>TBuf<12></codeph> object initialised with the string |
|
66 of five characters representing the English word "Hello".</p> <fig id="GUID-1988349D-C4DF-5CA4-A913-D6E0AF4DB104"> |
|
67 <image href="GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e224433_href.png" placement="inline"/> |
|
68 </fig> </section> |
|
69 </conbody></concept> |