/**
 * @file    myTask.h
 * @brief   Task framework: timers + events + message queues (C interface)
 * @details Based on SPEC §8 analysis. Uses C++ internally.
 */

#ifndef _MY_TASK_H_
#define _MY_TASK_H_
#include <stdint.h>

#ifdef __cplusplus
extern "C"
{
#endif

/* ================================================================
 * Opaque handles
 * ================================================================ */

typedef struct stru_task_timer     *stru_task_timer_t;
typedef struct stru_task_event     *stru_task_event_t;
typedef struct stru_task_msg_queue *stru_task_msg_queue_t;

/* ================================================================
 * Timer callback — returns 0 to continue, non-zero to stop
 * ================================================================ */

typedef int (*timer_func_cb)(void *arg);

/* Timer flags */
#define TIMER_ONCE    0   /* one-shot */
#define TIMER_PERIOD  1   /* periodic */

/* ================================================================
 * Timer API (SPEC T01-T07)
 * ================================================================ */

/**
 * @brief  Create a timer (does not start automatically)
 * @param  name       timer name for debugging
 * @param  cb         callback function
 * @param  arg        user argument passed to callback
 * @param  timeout_ms interval in milliseconds
 * @param  flags      TIMER_ONCE or TIMER_PERIOD
 * @return timer handle, NULL on failure
 */
stru_task_timer_t task_timer_create(const char *name, timer_func_cb cb,
                                    void *arg, uint32_t timeout_ms, int flags);

/** Start the timer */
int task_timer_start(stru_task_timer_t pt);

/** Stop the timer */
int task_timer_stop(stru_task_timer_t pt);

/** Restart with new interval */
int task_timer_restart(stru_task_timer_t pt, uint32_t timeout_ms);

/** Destroy and free the timer */
int task_timer_destroy(stru_task_timer_t pt);

/** Check if timer is currently active */
int task_timer_is_active(stru_task_timer_t pt);

/* ================================================================
 * Event API (SPEC T08-T13)
 * ================================================================ */

#define EVENT_OPT_AND  0   /* wait for ALL bits set */
#define EVENT_OPT_OR   1   /* wait for ANY bit set */

/**
 * @brief  Create an event object
 * @param  name  event name for debugging
 * @return event handle, NULL on failure
 */
stru_task_event_t task_event_create(const char *name);

/** Destroy event object */
int task_event_destroy(stru_task_event_t pe);

/** Set (send) event bits */
int task_event_send(stru_task_event_t pe, uint32_t bits);

/**
 * @brief  Wait for event bits
 * @param  pe         event handle
 * @param  set        bits to wait for
 * @param  opt        EVENT_OPT_AND or EVENT_OPT_OR
 * @param  timeout_ms timeout in ms (0 = forever)
 * @param  recved     [out] bits actually received
 * @return 0 on success, -1 on timeout
 */
int task_event_recv(stru_task_event_t pe, uint32_t set, uint32_t opt,
                    uint32_t timeout_ms, uint32_t *recved);

/** Clear specific event bits */
int task_event_clear(stru_task_event_t pe, uint32_t bits);

/** Query current event bits (non-blocking) */
uint32_t task_event_query(stru_task_event_t pe);

/* ================================================================
 * Message Queue API (SPEC T14-T21)
 * ================================================================ */

/**
 * @brief  Create a fixed-size message queue
 * @param  name      queue name
 * @param  msg_size  max size of each message (bytes)
 * @param  msg_num   max number of messages
 * @return queue handle, NULL on failure
 */
stru_task_msg_queue_t task_msg_queue_create(const char *name,
                                            uint32_t msg_size, uint32_t msg_num);

/** Destroy message queue */
int task_msg_queue_destroy(stru_task_msg_queue_t pq);

/** Send message (blocking if queue full) */
int task_msg_queue_send(stru_task_msg_queue_t pq, const void *msg, uint32_t size);

/** Send message with timeout (ms), returns -1 on timeout */
int task_msg_queue_send_timeout(stru_task_msg_queue_t pq, const void *msg,
                                uint32_t size, uint32_t timeout_ms);

/** Receive message with timeout (ms), returns -1 on timeout */
int task_msg_queue_recv(stru_task_msg_queue_t pq, void *msg, uint32_t size,
                        uint32_t timeout_ms);

/** Try receive (non-blocking), returns 0 on success, -1 if empty */
int task_msg_queue_try_recv(stru_task_msg_queue_t pq, void *msg, uint32_t size);

/** Get number of messages currently in queue */
uint32_t task_msg_queue_get_count(stru_task_msg_queue_t pq);

/** Get free space in queue */
uint32_t task_msg_queue_space(stru_task_msg_queue_t pq);

#ifdef __cplusplus
}
#endif
#endif