# API参考|API Reference

## Web服务器API

### 创建服务器

```c
NL_API nl_web_server_t* nl_web_create(int port);
NL_API void nl_web_destroy(nl_web_server_t* server);
NL_API int nl_web_start(nl_web_server_t* server);
NL_API void nl_web_stop(nl_web_server_t* server);
```

### 编码设置

```c
// 设置响应编码（默认UTF-8）
NL_API void nl_web_set_encoding(nl_web_server_t* server, const char* encoding);
```

### 基础页面

```c
// 添加HTML页面
NL_API void nl_web_add_html(nl_web_server_t* server, const char* path, const char* html);

// 添加Vue页面
NL_API void nl_web_add_vue(nl_web_server_t* server, const char* path, const char* vue_code);

// 添加JSON响应
NL_API void nl_web_add_json(nl_web_server_t* server, const char* path, const char* json);
```

### 文件热加载（v2.2.2新增）

支持从外部文件加载内容，每次请求时重新读取文件，实现实时更新。

```c
// 从文件加载HTML（热更新）
NL_API int nl_web_add_html_file(nl_web_server_t* server, const char* path, const char* file_path);

// 从文件加载Vue（热更新）
NL_API int nl_web_add_vue_file(nl_web_server_t* server, const char* path, const char* file_path);

// 从文件加载JSON（热更新）
NL_API int nl_web_add_json_file(nl_web_server_t* server, const char* path, const char* file_path);
```

**返回值**：
- `NL_OK (0)` - 成功
- `NL_EINVAL (-1)` - 参数无效
- `NL_EFILE (-2)` - 文件不存在
- `NL_ENOMEM (-3)` - 内存分配失败

**使用示例**：
```c
nl_web_server_t* server = nl_web_create(8080);
nl_web_add_html_file(server, "/", "index.html");  // 修改index.html后刷新页面立即生效
nl_web_add_vue_file(server, "/app", "app.vue");
nl_web_add_json_file(server, "/data", "data.json");
```

### HTTP重定向（v2.2.2新增）

支持配置临时重定向（302）和永久重定向（301），可在运行时切换。

```c
// 添加重定向（默认使用服务器当前设置的重定向类型）
NL_API void nl_web_add_redirect(nl_web_server_t* server, const char* path, const char* target_url);

// 添加重定向（显式函数名）
NL_API void nl_web_add_redirect_302(nl_web_server_t* server, const char* path, const char* target_url);

// 设置重定向类型（运行时切换301/302）
typedef enum {
    NL_REDIRECT_TEMPORARY = 302,   // 302 Found (临时重定向)
    NL_REDIRECT_PERMANENT = 301    // 301 Moved Permanently (永久重定向)
} nl_redirect_type_t;

NL_API void nl_web_set_redirect_type(nl_web_server_t* server, nl_redirect_type_t type);
NL_API nl_redirect_type_t nl_web_get_redirect_type(nl_web_server_t* server);
```

**使用示例**：
```c
nl_web_server_t* server = nl_web_create(8080);

// 默认302临时重定向
nl_web_add_redirect(server, "/old", "/new");
nl_web_add_redirect(server, "/google", "https://google.com");

// 运行时切换为301永久重定向
nl_web_set_redirect_type(server, NL_REDIRECT_PERMANENT);
nl_web_add_redirect(server, "/moved", "/new-location");

// 查询当前重定向类型
nl_redirect_type_t current = nl_web_get_redirect_type(server);
```

### 智能检测（v2.2.2新增）

`nl_web_add_html`、`nl_web_add_vue`、`nl_web_add_json` 函数会自动检测内容类型：
1. **URL** (`http://`/`https://`) → 自动创建重定向路由
2. **文件路径** → 自动创建热更新路由
3. **静态内容** → 直接作为内联内容处理

无需额外调用，原有API即可实现智能路由。

### 变量替换页面（新增）

```c
// 添加带变量的HTML页面
// 变量格式: {{<var>变量名</var>}}
NL_API void nl_web_add_html_with_vars(
    nl_web_server_t* server, 
    const char* path, 
    const char* html, 
    const char** vars, 
    const char** values, 
    int count
);

// 添加带变量的Vue页面
NL_API void nl_web_add_vue_with_vars(
    nl_web_server_t* server, 
    const char* path, 
    const char* vue_code, 
    const char** vars, 
    const char** values, 
    int count
);
```

### 预设组件

::: warning 已废弃
以下预设UI组件函数已从库中移除（v2.5.0）。建议使用外部HTML文件或 `nl_web_add_html()` / `nl_web_add_vue()` API 自行实现。
:::

```c
// 已从库中移除，请参考 wiki/Vue.md 使用 nl_vue_generate_sysinfo() 替代
```

### 运行时动态路由管理（v2.2.2新增）

在服务器运行期间动态添加、移除、查询和更新路由。

```c
// 添加静态内容路由（运行时动态添加）
NL_API int nl_web_add_route(nl_web_server_t* server, const char* path, const char* content, const char* content_type);

// 移除指定路径的路由
NL_API int nl_web_remove_route(nl_web_server_t* server, const char* path);

// 获取当前路由数量
NL_API int nl_web_get_route_count(nl_web_server_t* server);

// 列出所有路由路径
// paths: 预分配的字符串数组，每个元素至少 256 字节
// max_paths: 最大路径数
NL_API int nl_web_list_routes(nl_web_server_t* server, char** paths, int max_paths);

// 更新路由内容（仅支持静态内容类型路由）
NL_API int nl_web_update_route(nl_web_server_t* server, const char* path, const char* content, const char* content_type);
```

**返回值：**
- `NL_OK (0)` - 成功
- `NL_EINVAL (-1)` - 参数无效
- `NL_ENOENT (-2)` - 路由未找到
- `NL_ENOMEM (-3)` - 内存分配失败
- `NL_ERROR (-4)` - 内部错误

**使用示例：**
```c
nl_web_server_t* server = nl_web_create(8080);

// 运行时添加路由
nl_web_add_route(server, "/api/status", "{\"status\":\"ok\"}", "application/json");

// 查询路由数量
int count = nl_web_get_route_count(server);

// 列出所有路由
char* paths[32];
for (int i = 0; i < 32; i++) paths[i] = (char*)calloc(256, 1);
int n = nl_web_list_routes(server, paths, 32);

// 更新路由内容
nl_web_update_route(server, "/api/status", "{\"status\":\"maintenance\"}", "application/json");

// 移除路由
nl_web_remove_route(server, "/old-path");
```

### 快捷函数

```c
NL_API int nl_serve_html(int port, const char* html);
NL_API int nl_serve_vue(int port, const char* vue_code);
```

## 日志API

```c
// 设置日志级别
NL_API void nl_log_set_level(nl_log_level_t level);

// 设置自定义日志回调
NL_API void nl_log_set_callback(nl_log_callback callback, void* user_data);

// 输出日志
NL_API void nl_log(nl_log_level_t level, const char* format, ...);
NL_API void nl_log_debug(const char* format, ...);
NL_API void nl_log_info(const char* format, ...);
NL_API void nl_log_warn(const char* format, ...);
NL_API void nl_log_error(const char* format, ...);
```

## Debug模式

```c
// 启用/禁用调试模式
NL_API void nl_debug_enable(int enable);

// 检查调试模式状态
NL_API int nl_debug_is_enabled(void);
```

## 日志级别

```c
typedef enum {
    NL_LOG_DEBUG,  // 调试信息
    NL_LOG_INFO,   // 一般信息
    NL_LOG_WARN,   // 警告信息
    NL_LOG_ERROR   // 错误信息
} nl_log_level_t;
```

## 系统信息API

```c
// 获取操作系统名称
NL_API const char* nl_sys_info_get_os_name(void);

// 获取系统架构
NL_API const char* nl_sys_info_get_architecture(void);

// 获取CPU型号
NL_API const char* nl_sys_info_get_cpu_model(void);

// 获取总内存（字节）
NL_API int64_t nl_sys_info_get_total_ram(void);

// 获取运行库版本
NL_API const char* nl_sys_info_get_runtime_version(void);

// 设置RAM进制
// unit: NL_RAM_UNIT_DECIMAL(1000) 或 NL_RAM_UNIT_BINARY(1024)
NL_API void nl_sys_info_set_ram_unit(int unit);

// 清除缓存
NL_API void nl_sys_info_clear_cache(void);
```

**RAM进制常量:**
- `NL_RAM_UNIT_DECIMAL`: 1000进制（Linux默认）
- `NL_RAM_UNIT_BINARY`: 1024进制（Windows默认）

## 懒加载API

```c
// 全局启用/禁用懒加载
NL_API void nl_lazy_enable(int enable);

// 预加载指定模块
NL_API void nl_lazy_preload_module(int module);

// 停止指定模块并释放资源
NL_API void nl_lazy_stop_module(int module);

// 检查模块是否已加载
NL_API int nl_lazy_is_module_loaded(int module);

// 设置线程池大小（1-256）
NL_API void nl_lazy_set_thread_count(int count);

// 获取当前线程池大小
NL_API int nl_lazy_get_thread_count(void);

// 清除所有模块的缓存
NL_API void nl_lazy_clear_all_cache(void);
```

**模块常量:**
- `NL_LAZY_MODULE_HTTP` - HTTP服务器
- `NL_LAZY_MODULE_WEBSOCKET` - WebSocket
- `NL_LAZY_MODULE_TCP` - TCP通信
- `NL_LAZY_MODULE_UDP` - UDP通信
- `NL_LAZY_MODULE_TOML` - TOML解析
- `NL_LAZY_MODULE_JSON` - JSON解析
- `NL_LAZY_MODULE_SYSINFO` - 系统信息

**模块状态:**
- `NL_LAZY_STATUS_UNLOADED` - 未加载
- `NL_LAZY_STATUS_LOADING` - 加载中
- `NL_LAZY_STATUS_LOADED` - 已加载
- `NL_LAZY_STATUS_STOPPING` - 停止中
- `NL_LAZY_STATUS_STOPPED` - 已停止

## 编码动态适配API（v2.1.6新增）

```c
// 启用/禁用自动编码协商
NL_API void nl_web_enable_auto_encoding(nl_web_server_t* server, int enable);

// 检查是否启用自动编码
NL_API int nl_web_is_auto_encoding_enabled(nl_web_server_t* server);

// 设置回退编码（客户端未指定时使用）
NL_API void nl_web_set_fallback_encoding(nl_web_server_t* server, const char* encoding);

// 获取协商后的编码
NL_API const char* nl_web_get_negotiated_encoding(nl_web_server_t* server);

// 编码转换（双向转换）
// 返回分配的缓冲区，调用者需要free
NL_API char* nl_encoding_convert(const char* input, size_t input_len, 
                                 const char* source_encoding, const char* target_encoding);

// 自动检测字符串编码
NL_API const char* nl_encoding_detect(const char* input, size_t input_len);

// 获取系统默认编码
NL_API const char* nl_encoding_get_system_default(void);
```

**支持的编码常量:**
- `NL_ENCODING_UTF8` - UTF-8
- `NL_ENCODING_GBK` - GBK
- `NL_ENCODING_GB2312` - GB2312
- `NL_ENCODING_GB18030` - GB18030
- `NL_ENCODING_ISO8859_1` - ISO-8859-1
- `NL_ENCODING_US_ASCII` - US-ASCII
- `NL_ENCODING_UTF16` - UTF-16
- `NL_ENCODING_BIG5` - Big5

**全场景支持:**
- ✅ 控制台输出
- ✅ Web响应
- ✅ HTML页面
- ✅ Vue组件
- ✅ JSON响应
- ✅ TOML响应

**性能优化特性:**
- ✅ 懒加载机制：功能拉起使用后自动下线，减少内存占用
- ✅ 智能优化：仅对非ASCII字符进行转码，减少性能开销

## TLS/SSL API (v2.4.0新增)

```c
// 模块信息
nl_module_info_t* nl_tls_get_module_info(void);
int nl_tls_init(void);
const char* nl_tls_version(void);
int nl_tls_is_available(void);

// 上下文管理
nl_tls_ctx_t* nl_tls_create(void);
void nl_tls_destroy(nl_tls_ctx_t* ctx);

// 配置
int nl_tls_configure(nl_tls_ctx_t* ctx, const nl_tls_config_t* cfg);
int nl_tls_set_verify(nl_tls_ctx_t* ctx, int verify_peer);

// SSL握手
int nl_tls_handshake(nl_tls_ctx_t* ctx, int sock);

// 数据传输
int nl_tls_send(nl_tls_ctx_t* ctx, const void* buf, size_t len);
int nl_tls_recv(nl_tls_ctx_t* ctx, void* buf, size_t len);
int nl_tls_close(nl_tls_ctx_t* ctx);

// 状态查询
int nl_tls_is_active(const nl_tls_ctx_t* ctx);
const char* nl_tls_get_peer_cert(nl_tls_ctx_t* ctx);
const char* nl_tls_strerror(int err);
```

**TLS配置结构:**
```c
typedef struct nl_tls_config {
    const char*          ca_file;       // CA证书文件路径
    const char*          ca_path;       // CA证书目录路径
    const char*          cert_file;     // 客户端证书文件
    const char*          key_file;      // 客户端私钥文件
    const char*          key_pass;      // 私钥密码
    int                  verify_peer;   // 验证对端证书(0或1)
    int                  client_auth;   // 要求客户端认证(0或1)
    nl_tls_protocol_t    min_proto;     // 最低协议版本
    nl_tls_protocol_t    max_proto;     // 最高协议版本
} nl_tls_config_t;
```

详细 API 请参考 [TLS 模块文档](TLS.md)。

## MQTT API (v2.4.0新增)

```c
// 客户端管理
nl_mqtt_client_t* nl_mqtt_create(void);
void nl_mqtt_destroy(nl_mqtt_client_t* client);

// 连接
int nl_mqtt_connect(nl_mqtt_client_t* client,
                    const char* host, uint16_t port,
                    const nl_mqtt_connect_opts_t* opts,
                    nl_mqtt_connect_callback_t on_connect);
int nl_mqtt_disconnect(nl_mqtt_client_t* client);
nl_mqtt_status_t nl_mqtt_get_status(const nl_mqtt_client_t* client);

// 发布/订阅
int nl_mqtt_publish(nl_mqtt_client_t* client,
                    const char* topic,
                    const void* payload, size_t payload_len,
                    const nl_mqtt_pub_opts_t* opts);
int nl_mqtt_subscribe(nl_mqtt_client_t* client,
                      const char* topic,
                      const nl_mqtt_sub_opts_t* opts,
                      nl_mqtt_message_callback_t on_message,
                      void* user_data);
int nl_mqtt_unsubscribe(nl_mqtt_client_t* client, const char* topic);

// QoS 2 辅助
int nl_mqtt_send_pubrec(nl_mqtt_client_t* client, uint16_t packet_id);
int nl_mqtt_send_pubrel(nl_mqtt_client_t* client, uint16_t packet_id);
int nl_mqtt_send_pubcomp(nl_mqtt_client_t* client, uint16_t packet_id);

// Keep-alive
int nl_mqtt_ping(nl_mqtt_client_t* client);
int nl_mqtt_handle_pingresp(nl_mqtt_client_t* client);

// TLS 支持
int nl_mqtt_set_tls(nl_mqtt_client_t* client, int enabled);
int nl_mqtt_set_tls_cert(nl_mqtt_client_t* client,
                         const char* ca_file,
                         const char* cert_file,
                         const char* key_file);
int nl_mqtt_set_tls_insecure(nl_mqtt_client_t* client, int insecure);

// 事件循环
int nl_mqtt_handle_incoming(nl_mqtt_client_t* client);
int nl_mqtt_handle_outgoing(nl_mqtt_client_t* client);
int nl_mqtt_maintain(nl_mqtt_client_t* client, long timeout_ms);

// 工具函数
const char* nl_mqtt_rc_string(int return_code);
const char* nl_mqtt_msg_type_string(nl_mqtt_msg_type_t type);
int nl_mqtt_validate_topic(const char* topic);
int nl_mqtt_topic_matches(const char* pattern, const char* topic);
size_t nl_mqtt_encoded_len(size_t length);

// MQTT 5.0 属性管理
nl_mqtt_property_t* nl_mqtt_property_create(int type, int int_val, const char* str_val);
void nl_mqtt_property_destroy(nl_mqtt_property_t* prop);
int nl_mqtt_property_add_int(nl_mqtt_property_t** head, int type, int val);
int nl_mqtt_property_add_str(nl_mqtt_property_t** head, int type, const char* val, size_t len);

// 模块信息
nl_module_info_t* nl_mqtt_get_module_info(void);
const char* nl_mqtt_version(void);
int nl_mqtt_init(void);
```

详细 API 请参考 [MQTT 模块文档](MQTT.md)。