CircularFIFO_Interface.h

/**
 * @file       CircularFIFO_Interface.h
 * @brief      Public interface for the Circular FIFO Library.
 * @details    This file declares the public data types and APIs used to work with
 *             a generic static circular FIFO buffer in Embedded C applications.
 * @version    1.0.0
 * @author     Hesham Ahmed (Hisham4Ahmed@gmail.com)
 * @date       2026-04-13
 * @copyright  Copyright (c) 2026 , Gestell Company
 * 
 */

#ifndef CIRCULARFIFO_INTERFACE_H
#define CIRCULARFIFO_INTERFACE_H

/**
 * @addtogroup CircularFIFO_Library
 * @{
 */

/**
 * @defgroup File_Inclusion
 * @brief    File Inclusion Section
 * @{
 */
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "../../Common/Macros.h"
#include "CircularFIFO_Config.h"
/**
 * @}
 */

/**
 * @defgroup CircularFIFO_DataTypes
 * @brief    Data types used by the Circular FIFO Library.
 * @{
 */

/**
 * @typedef   CircularFIFO_Hook_t
 * @brief     Function pointer type used for optional lock and unlock hooks.
 */
typedef void (*CircularFIFO_Hook_t)(void);

/**
 * @enum      CircularFIFO_Mode_t
 * @brief     Full-buffer behavior mode for the FIFO.
 */
typedef enum
{
    CircularFIFO_Mode_Reject = 0,
    CircularFIFO_Mode_Overwrite
} CircularFIFO_Mode_t;

/**
 * @enum      CircularFIFO_Status_t
 * @brief     Return status values used by Circular FIFO APIs.
 */
typedef enum
{
    CircularFIFO_Status_Ok = 0,
    CircularFIFO_Status_NullPointer,
    CircularFIFO_Status_InvalidArgument,
    CircularFIFO_Status_Empty,
    CircularFIFO_Status_Full
} CircularFIFO_Status_t;

/**
 * @struct    CircularFIFO_t
 * @brief     Circular FIFO runtime object.
 */
typedef struct
{
    uint8_t * Buffer;
    size_t ElementSize;
    size_t Capacity;
    size_t Head;
    size_t Tail;
    size_t Count;
    CircularFIFO_Mode_t Mode;
    CircularFIFO_Hook_t LockHook;
    CircularFIFO_Hook_t UnlockHook;
} CircularFIFO_t;

/**
 * @}
 */

/**
 * @defgroup CircularFIFO_APIs
 * @brief    Public APIs used to control the Circular FIFO instance.
 * @{
 */

/**
 * @fn      Lib_CircularFIFO_Init
 * @brief   Initializes a Circular FIFO instance using caller-provided memory.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pBuffer       Pointer to the storage buffer.
 * @param   ElementSize   Size of one element in bytes.
 * @param   Capacity      Number of elements in the storage buffer.
 * @param   Mode          Behavior used when the FIFO becomes full.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_Init(CircularFIFO_t * pFifo,
                                            void * pBuffer,
                                            size_t ElementSize,
                                            size_t Capacity,
                                            CircularFIFO_Mode_t Mode);

/**
 * @fn      Lib_CircularFIFO_RegisterHooks
 * @brief   Registers optional lock and unlock hooks for thread-safe access.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   LockHook      Pointer to the lock function.
 * @param   UnlockHook    Pointer to the unlock function.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_RegisterHooks(CircularFIFO_t * pFifo,
                                                     CircularFIFO_Hook_t LockHook,
                                                     CircularFIFO_Hook_t UnlockHook);

/**
 * @fn      Lib_CircularFIFO_Push
 * @brief   Pushes one element into the FIFO.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pItem         Pointer to the source element.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_Push(CircularFIFO_t * pFifo, const void * pItem);

/**
 * @fn      Lib_CircularFIFO_Pop
 * @brief   Pops one element from the FIFO.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pItem         Pointer to the destination element.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_Pop(CircularFIFO_t * pFifo, void * pItem);

/**
 * @fn      Lib_CircularFIFO_Peek
 * @brief   Reads the oldest element without removing it from the FIFO.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pItem         Pointer to the destination element.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_Peek(const CircularFIFO_t * pFifo, void * pItem);

/**
 * @fn      Lib_CircularFIFO_Reset
 * @brief   Clears the FIFO content and resets all indices.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_Reset(CircularFIFO_t * pFifo);

/**
 * @fn      Lib_CircularFIFO_IsEmpty
 * @brief   Returns the FIFO empty state through an output parameter.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pIsEmpty      Pointer to the empty state result.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_IsEmpty(const CircularFIFO_t * pFifo, bool * pIsEmpty);

/**
 * @fn      Lib_CircularFIFO_IsFull
 * @brief   Returns the FIFO full state through an output parameter.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pIsFull       Pointer to the full state result.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_IsFull(const CircularFIFO_t * pFifo, bool * pIsFull);

/**
 * @fn      Lib_CircularFIFO_GetCount
 * @brief   Returns the current number of stored elements.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pCount        Pointer to the returned element count.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_GetCount(const CircularFIFO_t * pFifo, size_t * pCount);

/**
 * @fn      Lib_CircularFIFO_GetCapacity
 * @brief   Returns the configured FIFO capacity.
 * @param   pFifo         Pointer to the FIFO runtime object.
 * @param   pCapacity     Pointer to the returned capacity value.
 * @return  CircularFIFO_Status_t
 */
CircularFIFO_Status_t Lib_CircularFIFO_GetCapacity(const CircularFIFO_t * pFifo, size_t * pCapacity);

/**
 * @}
 * @}
 */

#endif /* CIRCULARFIFO_INTERFACE_H */