/*
 * Copyright (c) 2026 芯祥联科技 (XXL Technology Co., Ltd.)
 * All rights reserved.
 *
 * 平台层适配头文件（精简版，仅保留业务/协议层实际使用接口）
 * ==========================================
 * 重要声明：
 * 1. 本文件仅包含业务功能模块、协议层实际调用的平台接口，未使用接口已全部剔除；
 * 2. 所有接口定义为标准化规范，禁止修改宏名、参数、返回值语义；
 * 3. 如需扩展仅允许在"扩展接口区域"新增，不得修改已有接口；
 * 4. 简化设计原则：仅保留核心能力，降低用户适配工作量。
 * ==========================================
 * 功能说明：
 * 1. 屏蔽底层平台差异，仅暴露业务必需的极简接口；
 * 2. 接口命名简洁，参数精简，适配成本最低；
 *
 * 如需商业合作，请通过以下方式联系：
 * 合作邮箱：hezuo@xxltech.cn
 * 公司官网：www.xxltech.cn
 */
#ifndef PLATFORM_ADAPTER_H
#define PLATFORM_ADAPTER_H

#include <string.h>   // ✅ 跨平台必须加，解决 Windows 报错
#include "type.h"
#include "platform.h"

// ==================== 核心类型适配（仅保留业务使用的） ====================
/**
 * @brief 互斥锁句柄类型别名（业务/协议层数据同步核心）
 * @usage 用于接收ADAPTER_MutexCreate()的返回值，作为互斥锁操作的唯一标识
 * @example AdapterMutexHandle mutex = ADAPTER_MutexCreate();
 */
#define ADAPTER_MutexHandle           PlatformMutex

/**
// * @brief 套接字句柄类型别名（业务/协议层网络通信核心）
// * @usage 用于接收ADAPTER_UdpSocketCreate()的返回值，作为UDP套接字操作的唯一标识
// * @example AdapterSocketHandle sock = ADAPTER_UdpSocketCreate();
// */
//#define ADAPTER_SocketHandle          PlatformSocket

/**
 * @brief 时间戳类型别名（业务/协议层计时/超时判断核心）
 * @usage 用于存储ADAPTER_GetTickMs()返回的毫秒级时间戳，支持超时、重传计时等场景
 * @example AdapterTimeStamp tick = ADAPTER_GetTickMs();
 */
#define ADAPTER_TimeStamp             PlatformTime

// ==================== 核心常量适配（仅保留业务使用的） ====================
/**
 * @brief 无效互斥锁句柄常量
 * @usage 用于判断ADAPTER_MutexCreate()是否创建成功，返回此值表示创建失败
 * @example if (mutex == ADAPTER_MUTEX_INVALID) { /* 创建失败处理 *\/ }
 */
#define ADAPTER_MUTEX_INVALID         PLATFORM_MUTEX_INVALID

/**
 * @brief 无效套接字句柄常量
 * @usage 用于判断ADAPTER_UdpSocketCreate()是否创建成功，返回此值表示创建失败
 * @example if (sock == ADAPTER_SOCKET_INVALID) { /* 创建失败处理 *\/ }
 */
//#define ADAPTER_SOCKET_INVALID        PLATFORM_SOCKET_INVALID

// ==================== 同步接口（仅保留互斥锁，线程/信号量未使用则剔除） ====================
/**
 * @brief 创建互斥锁（业务/协议层核心：数据同步）
 * @return 成功返回有效互斥锁句柄，失败返回ADAPTER_MUTEX_INVALID
 * @usage 多线程访问共享数据前创建，确保数据原子操作
 * @note 每个互斥锁使用完成后必须调用ADAPTER_MutexDestroy()销毁
 * @example AdapterMutexHandle mutex = ADAPTER_MutexCreate();
 */
#define ADAPTER_MutexCreate()                platform_mutex_create()

/**
 * @brief 加互斥锁（阻塞式）
 * @param mutex 有效互斥锁句柄（禁止传入ADAPTER_MUTEX_INVALID）
 * @usage 访问共享数据前加锁，确保同一时间只有一个线程访问
 * @note 加锁后必须配对调用ADAPTER_MutexUnlock()解锁，避免死锁
 * @example ADAPTER_MutexLock(mutex);
 */
#define ADAPTER_MutexLock(mutex)             platform_mutex_lock(mutex)

/**
 * @brief 解互斥锁
 * @param mutex 有效互斥锁句柄（禁止传入ADAPTER_MUTEX_INVALID）
 * @usage 共享数据访问完成后解锁，释放互斥锁供其他线程使用
 * @note 必须与ADAPTER_MutexLock()配对调用
 * @example ADAPTER_MutexUnlock(mutex);
 */
#define ADAPTER_MutexUnlock(mutex)           platform_mutex_unlock(mutex)

/**
 * @brief 销毁互斥锁
 * @param mutex 有效互斥锁句柄（禁止传入ADAPTER_MUTEX_INVALID）
 * @usage 互斥锁不再使用时销毁，释放底层平台资源
 * @note 销毁前必须确保已解锁，否则会导致资源泄漏
 * @example ADAPTER_MutexDestroy(mutex);
 */
#define ADAPTER_MutexDestroy(mutex)          platform_mutex_destroy(mutex)

// ==================== 网络接口（仅保留UDP通信核心，其他未使用则剔除） ====================
/**
 * @brief 创建UDP套接字（业务/协议层核心：网络收发）
 * @return 成功返回有效套接字句柄，失败返回ADAPTER_SOCKET_INVALID
 * @usage 网络通信前创建UDP套接字，用于数据收发
 * @note 每个套接字使用完成后必须调用ADAPTER_SocketClose()关闭
 * @example AdapterSocketHandle sock = ADAPTER_UdpSocketCreate();
 */
//#define ADAPTER_UdpSocketCreate()            net_udp_socket_create()

/**
 * @brief 关闭套接字
 * @param sock 有效套接字句柄（禁止传入ADAPTER_SOCKET_INVALID）
 * @usage UDP通信完成后关闭套接字，释放底层网络资源
 * @note 关闭后该句柄不可再使用，否则会导致未定义行为
 * @example ADAPTER_SocketClose(sock);
 */
//#define ADAPTER_SocketClose(sock)            net_socket_close(sock)

// ==================== 时间接口（仅保留核心计时，其他未使用则剔除） ====================
/**
 * @brief 获取系统毫秒级Tick（业务/协议层核心：超时判断）
 * @return 32位毫秒数（从系统启动开始计时，溢出自动回绕）
 * @usage 用于超时判断、重传计时、心跳检测等场景
 * @example 
 * AdapterTimeStamp start = ADAPTER_GetTickMs();
 * if (ADAPTER_GetTickMs() - start > 1000) { /* 超时处理 *\/ }
 */
#define ADAPTER_GetTickMs()                  platform_get_tick_ms()

// ==================== 内存接口（仅保留核心分配/释放，其他未使用则剔除） ====================
/**
 * @brief 内存分配（业务/协议层核心：数据缓冲区）
 * @param size 要分配的内存大小（字节，禁止传入0）
 * @return 成功返回内存指针，失败返回NULL
 * @usage 动态创建数据缓冲区，存储网络报文、业务数据等
 * @note 分配的内存必须调用ADAPTER_Free()释放，避免内存泄漏
 * @example uint8* buf = (uint8*)ADAPTER_Malloc(ADAPTER_MAX_MSG_LEN);
 */
#define ADAPTER_Malloc(size)                 platform_malloc(size)

/**
 * @brief 内存释放
 * @param ptr 待释放的内存指针（传入NULL无操作，安全处理）
 * @usage 动态内存使用完成后释放，回收系统资源
 * @note 禁止重复释放同一指针，否则会导致未定义行为
 * @example ADAPTER_Free(buf);
 */
#define ADAPTER_Free(ptr)                    platform_free(ptr)

// ==================== 字符串/内存操作（仅保留安全拷贝，其他未使用则剔除） ====================
/**
 * @brief 安全内存拷贝（业务/协议层核心：避免缓冲区溢出）
 * @param dest 目标缓冲区（禁止传入NULL）
 * @param dest_max_len 目标缓冲区最大长度（字节，必须大于0）
 * @param src 源数据指针（禁止传入NULL）
 * @param src_len 源数据长度（字节，禁止传入0）
 * @return 实际拷贝的字节数（失败返回0）
 * @usage 替代原生memcpy，自动校验缓冲区长度，防止溢出
 * @example 
 * uint8 src[] = {0x01,0x02};
 * uint8 dest[10] = {0};
 * ADAPTER_MemCpyS(dest, 10, src, 2);
 */
#define ADAPTER_MemCpyS(dest, dest_max_len, src, src_len)  platform_memcpy_s(dest, dest_max_len, src, src_len)

/**
 * @brief 字符串长度（业务/协议层核心：参数校验）
 * @param str 字符串指针（传入NULL返回0，安全处理）
 * @return 字符串长度（不含终止符'\0'）
 * @usage 字符串参数校验、缓冲区长度判断
 * @example if (ADAPTER_StrLen(ip) >= ADAPTER_IP_LEN) { /* 参数非法处理 *\/ }
 */
#define ADAPTER_StrLen(str)                  platform_strlen(str)

/**
 * @brief 字符串比较（业务/协议层核心：主题匹配、参数校验）
 * @param str1 第一个字符串指针（禁止传入NULL）
 * @param str2 第二个字符串指针（禁止传入NULL）
 * @return 0=相等，<0=str1<str2，>0=str1>str2
 * @usage MQTT主题匹配、客户端ID对比、配置项校验等场景
 * @example if (ADAPTER_StrCmp(topic, "test/topic") == 0) { /* 主题匹配处理 *\/ }
 */
#define ADAPTER_StrCmp(str1, str2)           platform_strcmp(str1, str2)
// 新增：补充ADAPTER_StrChr，直接映射到标准库strchr（无需底层平台实现）
#define ADAPTER_StrChr(str, ch)              strchr((const char_xxl*)(str), (int)(ch))
// ==================== 字符串/内存操作 扩展 ====================
/**
 * @brief 安全内存清零（业务层核心：敏感数据防泄露）
 * @param dest 目标缓冲区
 * @param dest_len 缓冲区长度
 * @return 实际清零字节数
 */
#define ADAPTER_MemSetS(dest, dest_len, value)  platform_memset_s(dest, dest_len, value, dest_len)

// 清零专用宏（更简洁）
#define ADAPTER_MemZero(dest, dest_len)         ADAPTER_MemSetS(dest, dest_len, 0)

// ==================== 大小端转换（仅保留网络通信必需的） ====================
/**
 * @brief 主机序转大端32位（协议层核心：网络字节序）
 * @param out 输出缓冲区（必须指向4字节连续内存，禁止传入NULL）
 * @param value 主机序32位无符号整数
 * @usage 协议层将主机序数据转换为网络大端序，用于UDP/TCP传输
 * @example 
 * uint8 be_buf[4] = {0};
 * uint32 val = 0x12345678;
 * ADAPTER_CpuToBe32(be_buf, val);
 */
#define ADAPTER_CpuToBe32(out, value)        platform_cpu_to_be32(out, value)

/**
 * @brief 大端32位转主机序（协议层核心：网络字节序解析）
 * @param in 大端32位字节数组（必须指向4字节连续内存，禁止传入NULL）
 * @return 主机序32位无符号整数
 * @usage 协议层解析网络传输的大端序数据，转换为本地主机序
 * @example 
 * uint8 be_buf[4] = {0x12,0x34,0x56,0x78};
 * uint32 val = ADAPTER_Be32ToCpu(be_buf);
 */
#define ADAPTER_Be32ToCpu(in)                platform_be32_to_cpu(in)

/**
 * @brief 生成加密级随机数（协议层安全通信核心）
 * @param buf 输出缓冲区（禁止传入NULL）
 * @param len 随机数长度（字节，禁止传入0）
 * @return 成功返回1，失败返回0
 * @usage 协议层生成安全随机数，用于加密、校验、会话ID等场景
 * @note 生成的随机数具备密码学安全性，适配不同平台的加密随机数接口
 * @example 
 * uint8 rand_buf[16] = {0};
 * if (ADAPTER_GenerateCryptoRand(rand_buf, 16) != 1) { /* 生成失败处理 *\/ }
 */
//#define ADAPTER_GenerateCryptoRand(buf, len) platform_rand_generate_crypto(buf, len)

// ==================== 扩展接口区域（仅允许新增，禁止修改已有内容） ====================


/**
 * @brief 线程句柄类型别名（扩展接口）
 */
//#define ADAPTER_ThreadHandle          PlatformThread

/**
 * @brief 无效线程句柄常量（扩展接口）
 */
//#define ADAPTER_THREAD_INVALID        PLATFORM_THREAD_INVALID

/**
 * @brief 创建线程（扩展接口）
 * @param func 线程入口函数
 * @param arg 线程参数
 * @return 成功返回线程句柄，失败返回ADAPTER_THREAD_INVALID
 */
//#define ADAPTER_ThreadCreate(func, arg)  platform_thread_create(func, arg)

/**
 * @brief 等待线程退出（扩展接口）
 * @param thread 有效线程句柄
 */
//#define ADAPTER_ThreadJoin(thread)   platform_thread_join(thread)

/**
 * @brief 毫秒级休眠（扩展接口）
 * @param ms 休眠时长（毫秒）
 */
#define ADAPTER_DelayMs(ms)           platform_delay_ms(ms)
// 兼容SDK内部调用，纯映射已有接口，无新增实现

#define ADAPTER_MemCpy(dst, src, len)    ADAPTER_MemCpyS(dst, len, src, len)
#define ADAPTER_MemCmp(buf1, buf2, len)  platform_memcmp(buf1, buf2, len)
// 极简方案：直接映射到标准库snprintf，无需修改platform.h
#define ADAPTER_Snprintf(buf, buf_size, format, ...)  snprintf((char*)(buf), (size_t)(buf_size), (const char*)(format), ##__VA_ARGS__)
#define ADAPTER_StrStr(str, substr)          platform_strstr((const char_xxl*)(str), (const char_xxl*)(substr))

#endif  // PLATFORM_ADAPTER_H
