/**
 * @file qdx_port.h
 * @brief Hardware/OS Abstraction Layer (HAL) for QDX Network Stack
 *
 * Provides platform-independent interfaces for network socket operations,
 * timing, mutexes, and threading. Users must implement these functions
 * based on their specific MCU OS (e.g., FreeRTOS, LwIP, RT-Thread).
 */

#ifndef QDX_PORT_H
#define QDX_PORT_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================
 * Time & Delay
 * ============================================================ */

/**
 * @brief Get absolute system uptime/ticks in milliseconds.
 * @return Milliseconds since system boot.
 */
uint32_t qdx_port_get_tick_ms(void);

/**
 * @brief Blocking delay in milliseconds.
 * @param ms Delay time
 */
void qdx_port_delay_ms(uint32_t ms);

/* ============================================================
 * Network (TCP Socket)
 * ============================================================ */

/* Opaque handle for sockets dependent on underlying IP stack */
typedef void *qdx_socket_t;

/**
 * @brief Create and connect a TCP socket to a remote host.
 * @param ip Str IP address of the server (e.g., "192.168.1.10")
 * @param port Remote port
 * @return Valid socket handle on success, or NULL on failure.
 */
qdx_socket_t qdx_port_tcp_connect(const char *ip, uint16_t port);

/**
 * @brief Close a TCP socket.
 * @param sock Socket handle
 */
void qdx_port_tcp_close(qdx_socket_t sock);

/**
 * @brief Send data over TCP socket.
 * @param sock Socket handle
 * @param data Data buffer to send
 * @param len Length of data in bytes
 * @return Number of bytes sent, or < 0 for error.
 */
int32_t qdx_port_tcp_send(qdx_socket_t sock, const uint8_t *data, uint32_t len);

/**
 * @brief Receive data from TCP socket (Non-blocking or specific timeout).
 * @param sock Socket handle
 * @param buf Buffer to store received data
 * @param max_len Maximum buffer size
 * @return Number of bytes received. Return 0 if timeout/empty. Return < 0 for
 * connection closed/error.
 */
int32_t qdx_port_tcp_recv(qdx_socket_t sock, uint8_t *buf, uint32_t max_len);

/* ============================================================
 * Mutex & Threading
 * ============================================================ */

/* Opaque handle for mutex */
typedef void *qdx_mutex_t;

/**
 * @brief Create a recursive or standard mutex.
 * @return Mutex handle, or NULL on failure.
 */
qdx_mutex_t qdx_port_mutex_create(void);

/**
 * @brief Lock a mutex.
 * @param mutex Mutex handle
 */
void qdx_port_mutex_lock(qdx_mutex_t mutex);

/**
 * @brief Unlock a mutex.
 * @param mutex Mutex handle
 */
void qdx_port_mutex_unlock(qdx_mutex_t mutex);

/**
 * @brief Delete a mutex.
 * @param mutex Mutex handle
 */
void qdx_port_mutex_delete(qdx_mutex_t mutex);

/* Thread entry callback definition */
typedef void (*qdx_thread_entry_t)(void *arg);

/**
 * @brief Create a background thread/task.
 * @param name Task name
 * @param entry Task entry function
 * @param arg Task argument
 * @param stack_size Requested stack size in bytes
 * @param priority Task priority
 * @return 0 on success, < 0 on failure.
 */
int8_t qdx_port_thread_create(const char *name, qdx_thread_entry_t entry,
                              void *arg, uint32_t stack_size, uint8_t priority);

#ifdef __cplusplus
}
#endif

#endif /* QDX_PORT_H */