/**
 * @ Author: luoqi
 * @ Create Time: 2024-11-02 10:16
 * @ Modified by: luoqi
 * @ Modified time: 2025-03-21 14:37
 * @ Description:
 */

#ifndef _QFSM_H
#define _QFSM_H

#include <stdint.h>

typedef struct _fsm_list {
    struct _fsm_list *prev;
    struct _fsm_list *next;
} QFsmList;

typedef enum {
    QFSM_KEEP = 0x00,  // Keep the current state
    QFSM_NEXT = 0xcc,  // Move to the next state
    QFSM_ERR = 0xee,   // Error occurred
} QFsmResult;

typedef struct _qfsm_state {
    const char *name;          // Name of the state
    uint32_t id;               // Unique identifier for the state
    QFsmResult (*handle)(uint32_t *param);  // Function to handle the state
    const char *next_state_name;
    uint32_t next_state_id;    // Identifier of the next state
    struct _qfsm_state *next_state;  // Pointer to the next state
    QFsmList state_node;       // Node for state list
} QFsmState;

typedef struct {
    uint32_t *param;                     // Parameters for the FSM
    QFsmState *current_state;            // Current state of the FSM
    int (*state_change_hook)(uint32_t *param);  // Hook function for state change
    int (*state_keep_hook)(uint32_t *param);     // Hook function for state keep
    int (*state_error_hook)(uint32_t *param);    // Hook function for state error
    QFsmList state_list;                 // List of states
} QFsm;

#ifndef QNULL
#define QNULL ((void*)0)  // Define NULL pointer
#endif

/**
 * @brief Initialize the FSM.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param param Pointer to the parameters for the FSM.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_init(QFsm *fsm, uint32_t *param);

/**
 * @brief Prepare the FSM with a start state.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param start_state_name Name of the start state.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_prepare(QFsm *fsm, const char *start_state_name);

/**
 * @brief Set the state change hook.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param hook Pointer to the hook function.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_change_hook_set(QFsm *fsm, int (*hook)(uint32_t *param));

/**
 * @brief Set the state error hook.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param hook Pointer to the hook function.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_error_hook_set(QFsm *fsm, int (*hook)(uint32_t *param));

/**
 * @brief Set the state keep hook.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param hook Pointer to the hook function.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_keep_hook_set(QFsm *fsm, int (*hook)(uint32_t *param));

/**
 * @brief Execute the FSM.
 * 
 * @param fsm Pointer to the FSM structure.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_exec(QFsm *fsm);

/**
 * @brief Attach a state to the FSM.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param state Pointer to the state to be attached.
 * @param name Name of the state.
 * @param next_state_name Name of the next state.
 * @param handle Pointer to the state handling function.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_attach(QFsm *fsm, QFsmState *state, const char *name, const char *next_state_name, QFsmResult (*handle)(uint32_t *param));

/**
 * @brief Detach a state from the FSM.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param state Pointer to the state to be detached.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_detach(QFsm *fsm, QFsmState *state);

/**
 * @brief Change the current state of the FSM.
 * 
 * @param fsm Pointer to the FSM structure.
 * @param state_name Name of the new state.
 * @return 0 on success, non-zero on failure.
 */
int qfsm_state_change(QFsm *fsm, const char *state_name);

#endif