/******************************************************************************

                  版权所有 (C), 2018-2099, Radkil

 ******************************************************************************
  文 件 名   : msg_center.h
  版 本 号   : 初稿
  作    者   : radkil
  生成日期   : 2026年7月13日
  最近修改   :
  功能描述   : 模块间消息分发中心（跨线程通信）
  
  修改历史   :
  1.日    期   : 2026年7月13日
    作    者   : radkil
    修改内容   : 创建文件

 ******************************************************************************/

#ifndef __MSG_CENTER_H__
#define __MSG_CENTER_H__

#ifdef __cplusplus
#if __cplusplus
extern "C"{
#endif
#endif /* __cplusplus */

/*==============================================*
 *      include header files                    *
 *----------------------------------------------*/
#include "common.h"

/*==============================================*
 *      constants or macros define              *
 *----------------------------------------------*/

#define MSG_CENTER_MAX_MODULES      16      // 最大模块数
#define MSG_CENTER_MAX_NAME_LEN     16      // 模块名称最大长度
#define MSG_CENTER_QUEUE_SIZE       64      // 消息队列大小
#define MSG_CENTER_MAX_DATA_SIZE    64      // 消息数据最大大小

/*==============================================*
 *      data structures                         *
 *----------------------------------------------*/

// 消息结构
typedef struct {
    uint32_t    m_uiSrcModule;                          // 源模块ID
    uint32_t    m_uiDstModule;                          // 目标模块ID
    uint32_t    m_uiMsgID;                              // 消息ID（命令字）
    uint32_t    m_uiDataLen;                            // 数据长度
    uint8_t     m_aucData[MSG_CENTER_MAX_DATA_SIZE];    // 消息数据
} Msg_t;

// 消息处理回调函数类型
typedef void (*MsgHandler_t)(const Msg_t *pstMsg);

// 模块注册信息
typedef struct {
    char        m_szName[MSG_CENTER_MAX_NAME_LEN];  // 模块名称
    uint32_t    m_uiModuleID;                        // 模块ID
    MsgHandler_t m_pfHandler;                        // 消息处理回调
} MsgModule_t;

/*==============================================*
 *      project-wide global variables           *
 *----------------------------------------------*/

/*==============================================*
 *      routines' or functions' implementations *
 *----------------------------------------------*/

/**
 * @brief 初始化消息中心
 */
void MsgCenter_Init(void);

/**
 * @brief 注册模块到消息中心
 * @param pszName 模块名称
 * @param pfHandler 消息处理回调
 * @return 模块ID，失败返回0
 */
uint32_t MsgCenter_Register(const char *pszName, MsgHandler_t pfHandler);

/**
 * @brief 通过名称查找模块ID
 * @param pszName 模块名称
 * @return 模块ID，未找到返回0
 */
uint32_t MsgCenter_FindModule(const char *pszName);

/**
 * @brief 发送消息（异步，跨线程安全）
 * @param pstMsg 消息指针
 * @return 0成功，非0失败
 */
int MsgCenter_Send(const Msg_t *pstMsg);

/**
 * @brief 发送消息给指定模块（便捷函数）
 * @param pszDstName 目标模块名称
 * @param uiMsgID 消息ID
 * @param pData 数据指针（可为NULL）
 * @param uiDataLen 数据长度
 * @return 0成功，非0失败
 */
int MsgCenter_SendTo(const char *pszDstName, uint32_t uiMsgID, const void *pData, uint32_t uiDataLen);

/**
 * @brief 处理当前模块的消息（在模块线程中调用）
 * @param uiModuleID 模块ID
 * @return 处理的消息数量
 */
int MsgCenter_Process(uint32_t uiModuleID);

/**
 * @brief 处理当前模块的消息（带超时等待）
 * @param uiModuleID 模块ID
 * @param uiTimeoutMs 超时时间（毫秒），0表示不等待
 * @return 处理的消息数量，-1表示超时
 */
int MsgCenter_ProcessWait(uint32_t uiModuleID, uint32_t uiTimeoutMs);

#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */

#endif /* __MSG_CENTER_H__ */