API Reference

API参考|API Reference

Web服务器API

创建服务器

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);

编码设置

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

基础页面

// 添加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新增）

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

// 从文件加载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) - 内存分配失败

使用示例：

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），可在运行时切换。

// 添加重定向（默认使用服务器当前设置的重定向类型）
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);

使用示例：

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即可实现智能路由。

变量替换页面（新增）

// 添加带变量的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 自行实现。 :::

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

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

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

// 添加静态内容路由（运行时动态添加）
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) - 内部错误

使用示例：

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");

快捷函数

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

日志API

// 设置日志级别
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模式

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

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

日志级别

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

系统信息API

// 获取操作系统名称
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

// 全局启用/禁用懒加载
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新增）

// 启用/禁用自动编码协商
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新增)

// 模块信息
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配置结构:

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 模块文档。

MQTT API (v2.4.0新增)

// 客户端管理
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 模块文档。