/**
 * @file hal_websocket.h
 * @brief WebSocket 客户端 HAL 接口
 */

#ifndef HAL_WEBSOCKET_H
#define HAL_WEBSOCKET_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/** WebSocket 句柄 */
typedef void *hal_ws_handle_t;

/** WebSocket 事件类型 */
typedef enum {
    HAL_WS_EVENT_CONNECTED = 0,      /* 连接建立 */
    HAL_WS_EVENT_DISCONNECTED,       /* 连接断开 */
    HAL_WS_EVENT_TEXT_RECEIVED,      /* 收到文本帧 */
    HAL_WS_EVENT_BINARY_RECEIVED,    /* 收到二进制帧 */
    HAL_WS_EVENT_ERROR,              /* 错误 */
} hal_ws_event_t;

/**
 * @brief WebSocket 事件回调
 * @param event    事件类型
 * @param data     接收数据（CONNECTED/DISCONNECTED 时为 NULL）
 * @param len      数据字节数
 * @param user_ctx 用户上下文
 */
typedef void (*hal_ws_callback_t)(hal_ws_event_t event, const void *data, size_t len, void *user_ctx);

/** WebSocket 配置 */
typedef struct {
    const char       *url;            /* WebSocket URL（ws:// 或 wss://）*/
    hal_ws_callback_t callback;       /* 事件回调 */
    void             *user_ctx;       /* 回调用户上下文 */
    size_t            recv_buf_size;  /* 接收缓冲区大小（字节）*/
    bool              use_overseas_dns; /* 使用海外 DNS 解析域名 */
} hal_ws_config_t;

/**
 * @brief 创建 WebSocket 客户端
 * @return 句柄，失败返回 NULL
 */
hal_ws_handle_t hal_ws_create(const hal_ws_config_t *config);

/**
 * @brief 发起连接（异步，结果通过回调通知）
 * @return 0 成功，负值失败
 */
int hal_ws_connect(hal_ws_handle_t handle);

/** @brief 发送文本帧 */
int hal_ws_send_text(hal_ws_handle_t handle, const char *text);

/**
 * @brief 发送二进制帧
 * @return 0 成功，负值失败
 */
int hal_ws_send_binary(hal_ws_handle_t handle, const void *data, size_t len);

/** @brief 断开连接 */
int hal_ws_disconnect(hal_ws_handle_t handle);

/** @brief 销毁 WebSocket 客户端 */
void hal_ws_destroy(hal_ws_handle_t handle);

/** @brief 查询是否已连接 */
bool hal_ws_is_connected(hal_ws_handle_t handle);

#ifdef __cplusplus
}
#endif

#endif /* HAL_WEBSOCKET_H */
