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

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-0DEDC917-05C9-5D43-B839-73C043624BE9" xml:lang="en"><title> circularbuffer:

Circular Buffer Example</title><shortdesc>This example demonstrates the how to use the circular buffer classes <codeph>CCirBuf</codeph> and <codeph>CCirBuffer</codeph>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>

<section id="GUID-4AF25C42-D4E3-54AC-A493-F17995CF27A0"><title>Purpose</title> <p>This

example application shows how to construct and make use of circular buffers

containing integers, objects of user defined classes and objects of an R class. </p> </section>

<section id="GUID-DC849488-96A4-41A7-A088-4F4CC406F68B"><title>Download</title> <p>Click on the following link to download

the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-07c0d4d4-3e5e-4329-a0c5-e569e89d3a9e.zip" scope="external">circularbuffer .zip</xref></p><p>Click <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-07c0d4d4-3e5e-4329-a0c5-e569e89d3a9e.html" scope="peer"> browse </xref> to view the example code.</p> </section>

<section id="GUID-014CB2CC-94DC-4DF5-AA93-9157B756C915"><title>class summary</title><p><xref href="GUID-620EC30F-933F-3073-9E5F-CAC9F2BA4623.dita"><apiname>CCirBuffer </apiname></xref> <xref href="GUID-1D73835F-4361-3216-8EFC-669364E3F5E7.dita"><apiname>CCirBuf</apiname></xref> </p></section>

<section id="GUID-2B02964A-812A-5838-9A6F-64E4C8D069EF"><title>Design and

implementation</title> <p>Class diagram: </p> <fig id="GUID-1424998B-6CBC-5CEF-9A2D-4DBB286F409B">

<title>              Circular buffers example class diagram            </title>

<image href="GUID-1BDBFC07-A8E8-5150-953D-CA9CFE1CBF16_d0e351375_href.jpg" placement="inline"/>

</fig> <p>The example creates a circular buffer of integers using <xref href="GUID-620EC30F-933F-3073-9E5F-CAC9F2BA4623.dita#GUID-620EC30F-933F-3073-9E5F-CAC9F2BA4623/GUID-600BE94B-72FF-3A44-92EC-3806B7F5E4E5"><apiname>CCirBuffer::Put()</apiname></xref> to

add elements and <xref href="GUID-620EC30F-933F-3073-9E5F-CAC9F2BA4623.dita#GUID-620EC30F-933F-3073-9E5F-CAC9F2BA4623/GUID-112CD6F9-DAB4-30E5-9E5C-B636F8AEEC08"><apiname>CCirBuffer::Get()</apiname></xref> to remove an element.

To demonstrate the circular nature of the buffer, the example: </p> <ul>

<li id="GUID-950580F8-9810-5172-95AD-7B3C2B933818"><p>adds four elements until

the buffer is full, </p> </li>

<li id="GUID-28BD6FC5-80AC-5567-94E6-4592A0BD2751"><p>tries to adds another

element to the buffer, which fails with a buffer full error message, </p> </li>

<li id="GUID-AAB4C513-DB1C-5BEF-9C2E-9CED284A2C58"><p>removes elements 1 and

2 from the buffer, leaving elements 3 and 4, </p> </li>

<li id="GUID-3DE3EB5E-5080-527B-8C69-92535A6CB6CC"><p>adds two new elements

(5 and 6) to the buffer, </p> </li>

<li id="GUID-A7CDA10E-DF03-5460-BA7A-1E85B3FC66D8"><p>removes all elements

(3, 4, 5 and 6) from the buffer. </p> </li>

</ul> <p>Similar steps are performed using <xref href="GUID-1D73835F-4361-3216-8EFC-669364E3F5E7.dita"><apiname>CCirBuf</apiname></xref> to add

(<xref href="GUID-1D73835F-4361-3216-8EFC-669364E3F5E7.dita#GUID-1D73835F-4361-3216-8EFC-669364E3F5E7/GUID-1EE35B7E-6E95-3B6A-9EE4-B5CCFA4F772D"><apiname>CCirBuf::Add()</apiname></xref>) and remove (<xref href="GUID-1D73835F-4361-3216-8EFC-669364E3F5E7.dita#GUID-1D73835F-4361-3216-8EFC-669364E3F5E7/GUID-FFCCB7E3-B69F-3CC8-B38C-0179915C1E20"><apiname>CCirBuf::Remove()</apiname></xref>)

user-defined objects, and objects of an <codeph>R</codeph> class to and from

the buffer. </p> <p>After removing R class objects from the circular buffer,

they must be closed in order to release the resource held by the R Class objects. </p> </section>

<section id="GUID-6CB8757B-66CF-577C-A490-99CBBC10E2B5"><title>Building and

configuring</title> <p>To build the example: </p> <ul>

<li id="GUID-48DC5748-F246-57CB-9568-4B49E09A2CAA"><p>You can build the example

from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file

of the example into your IDE, and use the build command of the IDE. </p> <p>If

you use the command line, open a command prompt, and set the current directory

to the source code directory of the example. You can then build the example

with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake

bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe

how to use the SBSv1 build tools. </p> </li>

<li id="GUID-DEEF2C1B-2D81-5DA7-BE70-EAD7496B16FA"><p>For the emulator, the

example builds an executable called <filepath>circularbuffer.exe</filepath> in

the <filepath>epoc32\release\winscw\&lt;udeb or                 urel&gt;\</filepath> folder. </p> </li>

</ul> </section>

<section id="GUID-BC504F56-2676-5CBB-8DC1-57B3D9DD3950"><title>Running the

example</title> <p>The user is prompted to press a key in order to progress

from one function to the next. </p> </section>