<?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 id="GUID-A049B0C2-5C30-5B07-AC4F-32A75046B60B" xml:lang="en"><title>Buffer

descriptors</title><shortdesc>Describes modifiable and non-modifiable buffer descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A buffer descriptor provides a fixed length buffer to contain and access

data. The data is part of the descriptor object.</p>

<p>A buffer descriptor object is an instance of a templated class, where the

template parameter is an integer value that defines the size of the descriptor's

data area.</p>

<p>A buffer descriptor comes in two forms:</p>

<ul>

<li id="GUID-9F038469-EA34-5086-84AC-DEA306CC63FD"><p>a non-modifiable buffer

descriptor.</p> </li>

<li id="GUID-B4A065D3-31DE-5F2D-863F-C91B7A7200FF"><p>a modifiable buffer

descriptor.</p> </li>

</ul>

<section id="GUID-96A5D9DD-7754-4AD7-9C8F-1F664DB4719D"><title>Non-modifiable buffer descriptor</title> <p>The data contained

in a non-modifiable buffer descriptor can be accessed, but not changed, through

this descriptor. The data can, however, be completely replaced using the assignment

operators.</p> <p>Data is accessed through functions provided by the base

class.</p> <p>A non-modifiable buffer descriptor is supplied in two variants:</p> <ul>

<li id="GUID-30B702C6-238F-573A-8604-8CE126432723"><p>the 16 bit variant,

a <codeph>TBufC16&lt;TInt&gt;</codeph>, to contain Unicode strings.</p> </li>

<li id="GUID-EC2B5476-257C-5DDC-B8AE-4F7F2AF8723E"><p>the 8 bit variant, a <codeph>TBufC8&lt;TInt&gt;</codeph>,

to contain non-Unicode strings and binary data.</p> </li>

</ul> <p>There is also a build independent type, <codeph>TBufC&lt;TInt&gt;</codeph>.

This is the type which is most commonly used in program code; the appropriate

variant is selected at build time.</p> <p>An explicit 8 bit variant is chosen

for binary data. The explicit 16 bit variant is rarely used.</p> <p>The base

class, <codeph>TDesC</codeph>, contains a data member which holds the length

of the data. The following drawing shows the layout of a <codeph>TBufC&lt;5&gt;</codeph> object

initialised with the string of five characters representing the English word

"Hello".</p> <fig id="GUID-12064B13-BA8E-5552-9907-AD4F28329A24">

<image href="GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e220630_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-4FE409A2-F70B-4755-8C0F-E86799728550"><title>Modifiable buffer descriptor</title> <p>The data contained

in a modifiable buffer descriptor can be both accessed and changed through

this descriptor.</p> <p>The template parameter, as well as determining the

size of the data area created as part of the descriptor object, also defines

the maximum length of the descriptor.</p> <p>The length of the data can vary

between zero and the maximum length. When the length of the data is less than

the maximum, a portion of the data area within the descriptor is unused.</p> <p>Data

is accessed and modified through functions provided by the base classes.</p> <p>A

modifiable buffer descriptor is supplied in two variants:</p> <ul>

<li id="GUID-6FA9F924-4EBF-5AAE-B2E8-DD67CE15C8EE"><p>the 16 bit variant,

a <codeph>TBuf16&lt;TInt&gt;</codeph>, to contain Unicode strings.</p> </li>

<li id="GUID-F0C6A0B2-2ADF-5457-A910-6038816D95FD"><p>the 8 bit variant, a <codeph>TBuf8&lt;TInt&gt;</codeph>,

to contain non-Unicode strings and binary data.</p> </li>

</ul> <p>There is also a build independent type, <codeph>TBuf&lt;TInt&gt;</codeph>.

This is the type which is most commonly used in program code; the appropriate

variant is selected at build time.</p> <p>An explicit 8 bit variant is chosen

for binary data. The explicit 16 bit variant is rarely used.</p> <p>The base

class <codeph>TDesC</codeph>, contains a data member that holds the length

of the data. The base class <codeph>TDes</codeph>, contains a data member

that holds the maximum length of the data. The following drawing shows the

layout of a <codeph>TBuf&lt;12&gt;</codeph> object initialised with the string

of five characters representing the English word "Hello".</p> <fig id="GUID-1988349D-C4DF-5CA4-A913-D6E0AF4DB104">

<image href="GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e220696_href.png" placement="inline"/>

</fig> </section>

</conbody></concept>