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

变量替换页面（新增）

// 添加带变量的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
);

预设组件

NL_API void nl_web_add_counter(nl_web_server_t* server, const char* path, const char* title);
NL_API void nl_web_add_dashboard(nl_web_server_t* server, const char* path, const char* title);
NL_API void nl_web_add_form(nl_web_server_t* server, const char* path, const char* title, const char** fields, int field_count);
NL_API void nl_web_add_todo(nl_web_server_t* server, const char* path, const char* title);
NL_API void nl_web_add_chat(nl_web_server_t* server, const char* path, const char* title);
NL_API void nl_web_add_gallery(nl_web_server_t* server, const char* path, const char* title, const char** image_urls, int count);

快捷函数

NL_API int nl_serve_html(int port, const char* html);
NL_API int nl_serve_vue(int port, const char* vue_code);
NL_API int nl_serve_dashboard(int port, const char* title);
NL_API int nl_serve_todo(int port, const char* title);
NL_API int nl_serve_chat(int port, const char* title);

日志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字符进行转码，减少性能开销