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-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832" xml:lang="en"><title>rbufexample:

    13 Using resizable buffer descriptors</title><shortdesc>This example application demonstrates how to use the <codeph>RBuf</codeph> class. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> is a resizable buffer descriptor. It is part of

    15 the user library. It is used to contain strings and binary data when the maximum

    16 size of the data is not known until run time. </p>

    17 <p>This overview contains the following sections: </p>

    18 <ul>

    19 <li id="GUID-6A429EA8-8396-5A67-BF08-5CC81426D99A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-7605348A-0F8B-56A4-A48C-C83CB1CD546D">Download</xref> </p> </li>

    20 <li id="GUID-9BBBEFB0-D463-5A81-9AF8-8FE0FB781D5A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-BC0B8F0D-94A8-51D1-9BC2-85E4F76C482A">Description</xref>  </p> </li>

    21 <li id="GUID-4946F730-6E6A-5EC2-8A73-F0E29EBB09D9"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-69043124-f5fc-499b-8550-0c5b6ed66fe5">Class summary</xref>  </p> </li>

    22 <li id="GUID-4D0A67AF-FAC5-51F5-8C4F-5E9FBF1C2981"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-111B7B66-A3C4-5A15-8CF2-C6A227483651">Build</xref>  </p> </li>

    23 <li id="GUID-F01C5F43-391A-562A-A6E2-B7C34A2FB01A"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-E30CC1D4-B854-5080-8F37-950CA4D86DD0">See also</xref>  </p> </li>

    24 </ul>

    25 <section id="GUID-7605348A-0F8B-56A4-A48C-C83CB1CD546D"><title>Download</title> <p>Click

    26 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-7520d937-647a-495a-9196-edca52b98e89.zip" scope="external">rbufexample.zip</xref>.</p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-7520d937-647a-495a-9196-edca52b98e89.html" scope="peer">browse</xref> to view the example code.</p> </section>

    27 <section id="GUID-BC0B8F0D-94A8-51D1-9BC2-85E4F76C482A"><title>Description</title> <ul>

    28 <li id="GUID-87468748-0221-5005-9A98-EE03F5280421"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-B2AF4A97-A93B-5437-A31D-85C98AFC7DBB"> Creating an RBuf</xref>  </p> </li>

    29 <li id="GUID-6A66563D-F504-5D7E-8274-78126F2877F8"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-88B88124-BB7D-58DC-9F8A-61C32BDD58C4">Swapping two RBufs</xref>  </p> </li>

    30 <li id="GUID-6F41B457-6A2B-5895-8404-DCE5F971B59B"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-893B2BF3-AD9F-587D-95D5-165014C932B4">Copying data to an RBuf using the assignment operator</xref>  </p> </li>

    31 <li id="GUID-0B584C6E-A740-5CD6-A8F7-E2DA4327D2B9"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-2B6B8519-6306-5F0C-8A79-4094A3037901">Reallocating an RBuf</xref>  </p> </li>

    32 <li id="GUID-D96AC20C-5F22-52F7-B299-F178B90AE214"><p> <xref href="GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita#GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832/GUID-DE5A5DC0-07C6-50B9-AFDA-E69A92A02980"> Replacing and modifying the data in an RBuf</xref>  </p> </li>

    33 </ul> <p id="GUID-B2AF4A97-A93B-5437-A31D-85C98AFC7DBB"><b>Creating an RBuf</b> </p> <p>The

    34 example demonstrates creating an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> in the following

    35 ways: </p> <ol id="GUID-B4E38F9F-B275-5364-B59C-71087CDDAF1C">

    36 <li id="GUID-0482EE2B-165C-5B55-B819-741026C38F02"><p> <b>Using RBuf::Create()

    37 or RBuf::CreateL():</b> These functions create either an empty descriptor,

    38 or one with data copied from another descriptor. </p> </li>

    39 <li id="GUID-00E1680C-CB9C-5CC8-BC4A-C7337E0B9B9D"><p> <b>Using RBuf::CreateMax()

    40 or RBuf::CreateMaxL():</b> These functions set the buffer's current length

    41 to be the same as its maximum length. </p> </li>

    42 <li id="GUID-A0E4C908-5542-53D3-8452-BDA3BFB8887D"><p> <b>By assigning from

    43 an HBufC:</b> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref> transfers ownership of the

    44 heap descriptor. It is not possible to access the original heap descriptor

    45 once ownership has been transferred. </p> </li>

    46 <li id="GUID-B8812B95-CE27-5850-B866-F6DBC18ADF8C"><p> <b>By assigning some

    47 previously allocated memory:</b> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref> transfers

    48 ownership of allocated memory. It is then not possible to access the original

    49 memory. </p> </li>

    50 <li id="GUID-9FCBF30F-815B-5CA9-B0B6-1698DA0C4F0E"><p> <b>Using RReadStream:</b> The

    51 example writes some text to a file stream (<codeph>RFileWriteStream</codeph>).

    52 Then it creates the buffer by passing the open stream object to <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-7CACD30A-D6FC-38CB-A754-CB4B5C3728FF"><apiname>RBuf::CreateL()</apiname></xref>. </p> </li>

    53 </ol><p><b>Related APIs</b></p><ul>

    54 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> - Defines a build-independent resizable buffer

    55 descriptor.</p></li>

    56 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref></p></li>

    57 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref></p></li>

    58 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-7CACD30A-D6FC-38CB-A754-CB4B5C3728FF"><apiname>RBuf::CreateL()</apiname></xref></p></li>

    59 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-7F4E287B-F06C-33CF-9F17-E0E69244860A"><apiname>RBuf::CreateMax()</apiname></xref></p></li>

    60 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-792C0C3B-203E-37FF-9BCF-8C9AEDB1CECE"><apiname>RBuf::CreateMaxL()</apiname></xref></p></li>

    61 </ul> <p id="GUID-88B88124-BB7D-58DC-9F8A-61C32BDD58C4"><b>Swapping two RBufs</b> </p> <p>The

    62 example creates two resizable buffers using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref>.

    63 Then it swaps the contents of them using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D3EA0EA9-EC2C-3555-8D39-7AF1EF6C7E8B"><apiname>RBuf::Swap()</apiname></xref>. </p> <p> <b>Note:</b> When

    64 you swap data between two <codeph>RBuf</codeph> s ensure that the maximum

    65 length of the target <codeph>RBuf</codeph> is sufficient to hold the data,

    66 otherwise a panic (<codeph>User 11</codeph>) occurs. </p><p><b>Related APIs</b></p><ul>

    67 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref></p></li>

    68 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D3EA0EA9-EC2C-3555-8D39-7AF1EF6C7E8B"><apiname>RBuf::Swap()</apiname></xref></p></li>

    69 </ul> <p id="GUID-893B2BF3-AD9F-587D-95D5-165014C932B4"><b>Copying data to

    70 an RBuf using the assignment operator</b> </p> <p>The example creates two

    71 resizable buffers and allocates memory using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref>.

    72 It then copies data to these buffers. It also copies data from the first buffer

    73 to the second buffer using the assignment operator. </p> <p> <b> Notes:</b>  </p> <ul>

    74 <li id="GUID-9B2835F9-BD3E-56DD-9CFD-F71677FFC71C"><p>When you use <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref>,

    75 ownership of the buffer is transferred. <codeph>Assign()</codeph> neither

    76 checks nor frees any pre-existing owned allocated memory. If this descriptor

    77 already owns some allocated memory, <xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-32EB41B6-A1C8-326C-9D52-095B05D4D20B"><apiname>RBuf16::Close()</apiname></xref> should

    78 be invoked on it before calling <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref>, otherwise

    79 a memory leak will occur. </p> </li>

    80 <li id="GUID-41218102-1810-5E83-BAEE-5683D378F75F"><p>When you use the assignment

    81 operator, you must make sure the target descriptor's maximum length is equal

    82 to or greater than the length of the source descriptor, otherwise a <codeph>User

    83 11</codeph> panic (descriptor overflow) occurs. Any existing data in the target

    84 descriptor is replaced. </p> </li>

    85 </ul> <p><b>Related APIs</b></p><ul>

    86 <li><p><xref href="GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74.dita#GUID-BEFF9C91-DA64-3032-96E8-F5054405DC74/GUID-32EB41B6-A1C8-326C-9D52-095B05D4D20B"><apiname>RBuf16::Close()</apiname></xref></p></li>

    87 <li><p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-74F343A0-4ABB-378E-99D0-CAA13581AA4E"><apiname>RBuf::Assign()</apiname></xref></p></li>

    88 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-938BB912-4B66-3FF0-B830-CC4F778B23A9"><apiname>RBuf::Create()</apiname></xref></p></li>

    89 </ul><p id="GUID-2B6B8519-6306-5F0C-8A79-4094A3037901"><b>Reallocating an

    90 RBuf</b> </p> <p>The example creates a resizable buffer descriptor, then it

    91 resizes it using <codeph>RBuf::ReAlloc()</codeph>. The old and new lengths

    92 are printed to the console to show how <codeph>ReAlloc()</codeph> does not

    93 change the length of the descriptor, but only its maximum length. Calling <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D07FA48B-6FD0-3683-AEC9-ABC672AB2D80"><apiname>RBuf::ReAlloc()</apiname></xref> with

    94 a value of zero frees the memory and sets the length and maximum length to

    95 zero. </p><p><b>Related APIs</b></p><ul>

    96 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-D07FA48B-6FD0-3683-AEC9-ABC672AB2D80"><apiname>RBuf::ReAlloc()</apiname></xref></p></li>

    97 </ul> <p id="GUID-DE5A5DC0-07C6-50B9-AFDA-E69A92A02980"><b> Replacing and

    98 modifying the data in an RBuf</b> </p> <p>The example creates a resizable

    99 buffer descriptor and replaces a portion of the data in it using <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-0958525F-DB10-3D9A-AE99-B8113CA15810"><apiname>RBuf::Replace()</apiname></xref>.

   100 The start position and length of the data to be replaced, and the replacement

   101 text are passed as parameters. <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-019690E0-EFD2-3A9D-9332-11FB5A16D407"><apiname>RBuf::Delete()</apiname></xref> is then used

   102 to delete the replacement text, by specifying the position and length of the

   103 data to be deleted. </p><p><b>Related APIs</b></p><ul>

   104 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-019690E0-EFD2-3A9D-9332-11FB5A16D407"><apiname>RBuf::Delete()</apiname></xref></p></li>

   105 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita#GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8/GUID-0958525F-DB10-3D9A-AE99-B8113CA15810"><apiname>RBuf::Replace()</apiname></xref></p></li>

   106 </ul> </section>

   107 <section id="GUID-69043124-F5FC-499B-8550-0C5B6ED66FE5"><title>Class summary</title><ul>

   108 <li><p><xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> - Defines a build-independent resizable buffer

   109 descriptor.</p></li>

   110 <li><p> <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref> - Defines a build-independent heap descriptor.</p></li>

   111 <li><p><xref href="GUID-EFFA9A71-4CA4-3227-879D-17EFEB8B07D6.dita"><apiname>RFileWriteStream</apiname></xref> - Supports the writing of a stream

   112 to a file.</p></li>

   113 <li><p><xref href="GUID-90A3AE1D-DCB2-3E98-8BE9-C48C15964E7D.dita"><apiname>RFileReadStream</apiname></xref> - Supports the reading of a stream

   114 from a file.</p></li>

   115 <li><p><xref href="GUID-E263C747-946F-35AA-9F1D-41833BD350FC.dita"><apiname>RFs</apiname></xref></p></li>

   116 </ul></section>

   117 <section id="GUID-111B7B66-A3C4-5A15-8CF2-C6A227483651"><title>Build</title> <p>The <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">Symbian build process</xref> describes

   118 how to build this example application. The example builds an executable file

   119 called <filepath>rbufexample.exe</filepath> in the standard location (<filepath>\epoc32\release\winscw\&lt;build_variant&gt;</filepath> for

   120 the emulator). After launching the executable, depending on the emulator you

   121 are using, you may need to navigate away from the application launcher/shell

   122 screen to view the console. </p> </section>

   123 <section id="GUID-E30CC1D4-B854-5080-8F37-950CA4D86DD0"><title>See also</title> <p> <xref href="GUID-4AC3CC42-6E8D-584A-AA39-84B5E0F3C16A.dita">How to use the resizable

   124 buffer descriptor - RBuf</xref>  </p> </section>

   125 </conbody></concept>