/*
 * Copyright (c) 2026 芯祥联科技 (XXL Technology Co., Ltd.)
 * All rights reserved.
 *
 * 本文件为网络适配层核心头文件，是业务模块与底层网络之间的统一接口层，
 * 该接口层定义不可修改，以保证业务模块的兼容性；
 * 开源用户可修改适配层的具体实现（net_adapter.c）及各类网络功能实现，
 * 以适配不同的网络连接（如WiFi、蓝牙、卫星、UDP/TCP等），为业务模块提供统一的网络通信能力。
 *
 * 如需商业合作，请通过以下方式联系：
 * 合作邮箱：hezuo@xxltech.cn
 * 公司官网：www.xxltech.cn
 */
#ifndef NET_ADAPTER_H
#define NET_ADAPTER_H

#include "type.h"


#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    NET_ADAPTER_SUCCESS = 0,  // 操作成功
    NET_ADAPTER_FAILED  = -1, // 操作失败
    NET_ADAPTER_TIMEOUT = -2  // 接收超时
} NetAdapterStatus;

// 实例ID = 数组下标，无效实例ID定义，用户只需判断该值即可
#define NET_ADAPTER_INVALID_INDEX        0xFFU

/**
 * @brief 打开网络通道，分配实例ID(index)
 * @param target 目标地址(IP/MAC/卫星ID等)
 * @param port 目标端口/通道号
 * @return 成功=实例index(0~3)，失败=NET_ADAPTER_INVALID_INDEX
 */
uint8_xxl net_adapter_open(const char* target, uint16_xxl port);

/**
 * @brief 发送数据：传入实例index，直接使用
 * @param index 实例ID(open返回的数组下标)
 * @param data 待发送数据缓冲区
 * @param len 数据长度(字节)
 * @return 操作状态码
 */
NetAdapterStatus net_adapter_send(uint8_xxl index, const uint8_xxl* data, uint32_xxl len);

/**
 * @brief 接收数据：传入实例index，直接使用
 * @param index 实例ID(open返回的数组下标)
 * @param buf 接收数据缓冲区
 * @param buf_len 缓冲区最大长度
 * @param actual_len 输出：实际接收字节数
 * @param timeout_ms 超时时间(ms)
 * @return 操作状态码
 */
NetAdapterStatus net_adapter_recv(uint8_xxl index, uint8_xxl* buf, uint32_xxl buf_len, uint32_xxl* actual_len, uint32_xxl timeout_ms);

/**
 * @brief 关闭实例：传入实例index，释放对应资源
 * @param index 实例ID(open返回的数组下标)
 */
void net_adapter_close(uint8_xxl index);

/**
 * @brief 全局资源释放，程序退出时调用一次即可
 */
void net_adapter_global_deinit(void);

void net_adapter_loop(void);

#ifdef __cplusplus
}
#endif

#endif // NET_ADAPTER_H
