/******************************************************************************
Copyright (c) 2007 Analog Devices, Inc.  All Rights Reserved.  This software is
proprietary and confidential to Analog Devices, Inc. and its licensors.
*******************************************************************************

$Revision: 1.1 $
$Date: 2008/03/27 03:03:19 $
$LastChangedBy: sto $

Project:    Common Components
Title:      Circular Buffer Utility Module
Author:     DWP

Description:
            This module provides utility functions to manage circular byte buffers

References:
            none

******************************************************************************/
#ifndef CIRCULAR_BUFFER_H
#define CIRCULAR_BUFFER_H

#include <stdio.h>

/******************************************************************************
**          #defines
******************************************************************************/
#define CBUFFER_PTR(cbuf) (&((cbuf).base[(cbuf).data_offset]))



/******************************************************************************
**          Typedefs/Enumerations
******************************************************************************/


/******************************************************************************
**      Structure Declarations
******************************************************************************/
typedef struct {
    unsigned char *base;
    unsigned int   length;
    unsigned int   data_offset;
    unsigned int   data_length;
} cbuffer_t;



/******************************************************************************
**      Function Declarations
******************************************************************************/

/*
**
** Function:            fread_cbuffer
**
** Description:         reads n bytes from a file and stores in a circular buffer
**                      (does not read more than what is required to fill the 
**                      buffer, if it does not have enough empty space for n bytes)
**
** Arguments:
**
**  cbuf                Structure representing the destination circular buffer
**  num_bytes           The number of bytes to be read in from the file
**  src                 The file pointer of the source file 
**                      (should have been opened in binary mode)
**
** Outputs:             none
**
** Return value:        The number of bytes read from the file and added to the 
**                      circular buffer.
**
**
*/
int fread_cbuffer(cbuffer_t *cbuf, unsigned int num_bytes, FILE *src);

/*
**
** Function:            fill_cbuffer
**
** Description:         this function tries to fill the circular buffer with data
**                      read from a file 
**
** Arguments:
**
**  cbuf                Structure representing the destination circular buffer
**  src                 The file pointer of the source file 
**                      (should have been opened in binary mode)
**
** Outputs:             none
**
** Return value:        The number of bytes read from the file and added to the 
**                      circular buffer.
**
**
*/
int fill_cbuffer(cbuffer_t *cbuf, FILE *src);

/*
**
** Function:            advance_cbuffer
**
** Description:         removes n bytes from a circular buffer
**                      (at most removes what is available in the buffer)
**
** Arguments:
**
**  cbuf                Structure representing the circular buffer
**  num_bytes           The number of bytes to be removed
**
** Outputs:             none
**
** Return value:        The number of bytes actually removed from the 
**                      circular buffer.
**
**
*/
int advance_cbuffer(cbuffer_t *cbuf, unsigned int num_bytes);

/*
**
** Function:            flush_cbuffer
**
** Description:         flushes all remaining bytes from a circular buffer
**
** Arguments:
**
**  cbuf                Structure representing the circular buffer
**
** Outputs:             none
**
** Return value:        none
**
**
*/
void flush_cbuffer(cbuffer_t *cbuf);

/*
**
** Function:            initialise_cbuffer
**
** Description:         initialises the structure representing a circular buffer
**
** Arguments:
**
**  cbuf                Structure representing the circular buffer
**  buffer              Pointer to the actual circular buffer itself
**  buf_len             The length of the buffer in number of bytes
**
** Outputs:             none
**
** Return value:        none
**
**
*/
void initialise_cbuffer(cbuffer_t *cbuf, unsigned char *buffer, unsigned int buf_len);


#endif /* CIRCULAR_BUFFER_H */

/*
**
** EOF: $HeadURL: svn://dingofiles.spd.analog.com/audio/trunk/common/demo/framework/Include/Audio_Player/circular_buffer.h $
**
*/