1/*---------------------------------------------------------------------------*
2 *  CircularBuffer.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef CIRCULARBUFFER_H
21#define CIRCULARBUFFER_H
22
23
24
25/*
26 * This is implemented as a set of macros rather than functions with proper
27 * checking.  The reasons for doing so is that this is a non-public API that is
28 * used in the audio delivery component and we want it to be as fast as
29 * possible.
30 */
31
32#include "ESR_SharedPrefix.h"
33#include "ptypes.h"
34
35/**
36 * @addtogroup CircularBufferModule CircularBuffer API functions
37 * Generic Circular Buffer implementation.
38 *
39 * @{
40 */
41
42/**
43 * A circular buffer.
44 *
45 * @see list of functions used to operate on @ref CircularBufferModule "CircularBuffer" objects
46 */
47typedef struct CircularBuffer_t
48{
49  /**
50   * Total buffer capacity.
51   */
52  size_t capacity;
53
54  /**
55   * Amount of data in buffer.
56   */
57  size_t size;
58
59  /**
60   * Write index.
61   */
62  size_t writeIdx;
63
64  /**
65   * Read index.
66   */
67  size_t readIdx;
68
69}
70CircularBuffer;
71
72/**
73 * Creates a circular buffer of the specified capacity.
74 *
75 * @param capacity the capacity in number of bytes of the data buffer.
76 * @param mtag MALLOC allocation tag
77 * @param buffer The circular buffer to initialize.
78 */
79ESR_SHARED_API ESR_ReturnCode CircularBufferCreate(size_t capacity, const LCHAR* mtag, CircularBuffer** buffer);
80
81/**
82 * Returns the capacity of the buffer.
83 */
84#define CircularBufferGetCapacity(buffer) ((buffer)->capacity + 0)
85
86/**
87 * Returns the current size (number of bytes) in the buffer.
88 */
89#define CircularBufferGetSize(buffer) ((buffer)->size + 0)
90
91/**
92 * Returns whether buffer is empty or not.
93 */
94#define CircularBufferIsEmpty(buffer) ((buffer)->size == 0)
95
96/**
97 * Returns whether buffer is full or not.
98 **/
99#define CircularBufferIsFull(buffer) ((buffer)->size == (buffer)->capacity)
100
101/**
102 * Resets the buffer to the empty state.
103 */
104#define CircularBufferReset(buffer) ((buffer)->size = \
105                                     (buffer)->readIdx = \
106                                                         (buffer)->writeIdx = 0)
107
108/**
109 * Determines the residual capacity of the circular buffer.
110 */
111#define CircularBufferGetAvailable(buffer) ((buffer)->capacity - (buffer)->size)
112
113/**
114 * Reads requested number of bytes from the circular buffer.
115 *
116 * @param buffer The circular buffer to read from.
117 * @param data  Pointer to where to store read bytes.
118 * @param bufSize The number of bytes to read from the circular buffer.
119 *
120 * @return the number of bytes that were read.  A negative value indicates an
121 * error, while a value less than bufSize indicates that end-of-buffer is
122 * reached.
123 */
124ESR_SHARED_API int CircularBufferRead(CircularBuffer* buffer, void* data, size_t bufSize);
125
126/**
127 * Skips requested number of bytes from the circular buffer.
128 *
129 * @param buffer The circular buffer to skip from.
130 * @param bufSize The number of bytes to skip from the circular buffer.
131 *
132 * @return the number of bytes that were skipped.  A negative value indicates an
133 * error, while a value less than bufSize indicates that end-of-buffer is
134 * reached.
135 **/
136ESR_SHARED_API int CircularBufferSkip(CircularBuffer* buffer, size_t bufSize);
137
138/**
139 * Writes requested number of bytes from the circular buffer.
140 *
141 * @param buffer The circular buffer to write to
142 * @param data  Pointer to data to write.
143 * @param bufSize The number of bytes to write into the circular buffer.
144 *
145 * @return the number of bytes that were written.  A negative value indicates
146 * an error, while a value less than bufSize indicates that buffer capacity is
147 * reached.
148 */
149ESR_SHARED_API int CircularBufferWrite(CircularBuffer* buffer, const void* data, size_t bufSize);
150
151/**
152 * Removes the requested number of bytes from the end of the circular buffer.
153 *
154 * @param buffer The circular buffer to write to
155 * @param amoun tThe number of bytes to remove from end of circular buffer.
156 *
157 * @return the number of bytes that were unwritten. A negative value indicates
158 *         an error.
159 */
160ESR_SHARED_API int CircularBufferUnwrite(CircularBuffer* buffer, size_t amount);
161
162/**
163 * @}
164 */
165
166
167#endif
168