/**
 * @file imp_msg_queue.h
 * @author Alvin Young (impressionyang@outlook.com)
 * @brief 
 * @version 0.1
 * @date 2024-12-03
 * 
 *      _                            _                              
 *     (_)_ _  ___  _______ ___ ___ (_)__  ___  __ _____ ____  ___ _
 *    / /  ' \/ _ \/ __/ -_|_-<(_-</ / _ \/ _ \/ // / _ `/ _ \/ _ `/
 *   /_/_/_/_/ .__/_/  \__/___/___/_/\___/_//_/\_, /\_,_/_//_/\_, / 
 *          /_/                               /___/          /___/  
 * @copyright Copyright (c) 2024 impressionyang
 * 
 * @par 修改日志:
 * <table>
 * <tr><th>Date           <th>Version  <th>Author         <th>Description
 * <tr><td>2024-12-03     <td>v1.0     <td>Alvin Young     <td>首次创建
 * </table>
 * 
 */
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __IMP_MSG_QUEUE_H__
#define __IMP_MSG_QUEUE_H__

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/

#include <stdint.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"

/* define --------------------------------------------------------------------*/

#define IMP_MSG_QUEUE_MAX_ITEM_COUNT (20)

/// @brief 一个消息最多阻塞在头部多少次，避免消息队列被持续阻塞
#define IMP_MSG_QUEUE_MAX_PEEK_CNT (20)
/* typedef -------------------------------------------------------------------*/

/// @brief 消息队列的消息内容
typedef struct __imp_msg_item_t__
{
    uint16_t send_id;
    uint16_t recv_id;
    uint16_t msg_type;
    union {
        uint32_t msg_data;
        void*    msg_data_ptr;
    };
    union {
        uint32_t msg_reserve;
        uint32_t msg_data_len;
    };
} imp_msg_item_t;

/// @brief 消息队列的句柄
typedef struct __imp_msg_queue_t__
{
    uint8_t is_init;
    /// @brief 唯一的值代表不同的Task
    uint16_t task_id;
    char*    task_name;
    /// @brief 通过create 获取消息队列句柄
    QueueHandle_t msg_queue_handle;
} imp_msg_queue_t;

/* variables -----------------------------------------------------------------*/
/* Private function(only *.c)  -----------------------------------------------*/
/* Exported functions --------------------------------------------------------*/

/**
 * 
 * @brief 初始化消息队列
 * @return uint8_t 
 * @date 2024-12-04
 * @author Alvin Young (impressionyang@outlook.com)
 * 
 * @details 
 * @note 
 * @par 修改日志:
 * <table>
 * <tr><th>Date             <th>Author         <th>Description
 * <tr><td>2024-12-04      <td>Alvin Young     <td>新建
 * </table>
 */
uint8_t imp_msg_queue_init();

/**
 * 
 * @brief 获取一个消息队列控制句柄
 * @param [in] task_id 
 * @return imp_msg_queue_t* 
 * @date 2024-12-04
 * @author Alvin Young (impressionyang@outlook.com)
 * 
 * @details 
 * @note 
 * @par 修改日志:
 * <table>
 * <tr><th>Date             <th>Author         <th>Description
 * <tr><td>2024-12-04      <td>Alvin Young     <td>新建
 * </table>
 */
imp_msg_queue_t* imp_msg_queue_create_handle(uint16_t task_id);

/**
 * 
 * @brief 接收消息
 * @param [in] handle 
 * @param [in] msg 
 * @return uint8_t 
 * @date 2024-12-04
 * @author Alvin Young (impressionyang@outlook.com)
 * 
 * @details 
 * @note 
 * @par 修改日志:
 * <table>
 * <tr><th>Date             <th>Author         <th>Description
 * <tr><td>2024-12-04      <td>Alvin Young     <td>新建
 * </table>
 */
uint8_t imp_msg_queue_recv_msg(imp_msg_queue_t* handle, imp_msg_item_t* msg,
                               uint16_t timeout);

/**
 * 
 * @brief 发送消息
 * @param [in] handle 
 * @param [in] recv_id 
 * @param [in] msg 
 * @return uint8_t 
 * @date 2024-12-04
 * @author Alvin Young (impressionyang@outlook.com)
 * 
 * @details 
 * @note 
 * @par 修改日志:
 * <table>
 * <tr><th>Date             <th>Author         <th>Description
 * <tr><td>2024-12-04      <td>Alvin Young     <td>新建
 * </table>
 */
uint8_t imp_msg_queue_send_msg(imp_msg_queue_t* handle, uint16_t recv_id,
                               imp_msg_item_t* msg);

/**
 * 
 * @brief 销毁一个消息队列控制句柄
 * @param [in] handle 
 * @return uint8_t 
 * @date 2024-12-04
 * @author Alvin Young (impressionyang@outlook.com)
 * 
 * @details 
 * @note 
 * @par 修改日志:
 * <table>
 * <tr><th>Date             <th>Author         <th>Description
 * <tr><td>2024-12-04      <td>Alvin Young     <td>新建
 * </table>
 */
uint8_t imp_msg_queue_destroy_handle(imp_msg_queue_t* handle);

#ifdef __cplusplus
}
#endif
#endif  //__IMP_MSG_QUEUE_H__

/*
 * EOF
 */