工具 API

这里的函数大多不针对某个窗口,而是:读版本、取系统路径、读语言和显示器信息、在数据目录里存配置、清理数据等。

与系统深度集成的接口(URL 协议、文件关联、全局热键、剪贴板、打印等)见 系统集成 API。


版本与系统信息

获取 JadeView 版本(jadeview_version)

拿到当前这份 JadeView 动态库的完整版本号(含构建号),用于关于页、日志头、排查问题时报版本。

C
int32_t jadeview_version(char* buffer, size_t buffer_size);
参数说明
buffer输出缓冲区,写入 UTF-8 字符串,末尾带 \0。
buffer_size缓冲区字节长度,必须够长,否则会失败。
返回值含义
1成功写入版本字符串。
0失败(空指针、缓冲区太小等)。

获取 WebView 版本(get_webview_version)

把本机 WebView2 运行时版本号写入 buffer(UTF-8 + \0)。不是 JadeView DLL 自身版本(那是 jadeview_version)。

C
int32_t get_webview_version(char* buffer, size_t buffer_size);

成功返回 1,失败 0(缓冲不够、指针无效等)。


获取系统语言(getLocale)

读取 Windows 当前用户界面语言(区域设置),得到一个标准语言标签字符串。常见用途:决定主进程或网页用中文还是英文界面、把语言参数传给渲染进程做 i18n。

C
int32_t getLocale(char* buffer, size_t buffer_size);

写入示例:zh-CN、en-US。不是键盘布局,而是系统显示语言/区域那一套。

成功 1,失败 0(缓冲区不够、指针无效等)。


判断是否为 Windows 11(is_windows_11)

C
int32_t is_windows_11(void);

当前系统为 Windows 11 返回 1,否则 0。用于判断是否可用 Mica/部分壳特性等。


显示器

获取显示器信息(get_displays_info)

一次拿到本机所有显示器的布局和清晰度信息,方便你做:多显示器上决定窗口出现在哪块屏、算缩放后的逻辑坐标、判断哪块是主屏、适配高 DPI。

C
int32_t get_displays_info(char* buffer, size_t buffer_size);

成功时 buffer 里是一段 UTF-8 的 JSON 数组,每个元素对应一块屏,常见字段含义:

字段含义
bounds整块屏幕在虚拟桌面坐标系里的位置和尺寸(物理像素)。
work_area工作区(去掉任务栏等占用的区域),适合算「窗口别挡住任务栏」。
scale_factor缩放比例(如 1.0、1.25、1.5),和系统「缩放与布局」一致。
dpi_x / dpi_yDPI,做精细适配时可用。
is_primary是否主显示器。

失败返回 0(缓冲不够、解析失败等)。


清空数据目录(clear_data_directory)

清空当前 JadeView 使用的数据目录里的内容(缓存、本地配置等),相当于「重置本应用在本机的数据」。必须传对确认令牌,防止误触。

C
int32_t clear_data_directory(const char* confirm_token);

confirm_token 必须完全等于字符串 I_UNDERSTAND_CLEAR_DATA(与源码常量一致)。


文本处理

智能文本转码(smart_convert_encoding)

自动检测输入文本编码,转换为目标编码。

C
int32_t smart_convert_encoding(const uint8_t* input_data, int32_t input_len, const char* target_encoding, char* output_buffer, int32_t buffer_size, char* detected_encoding, int32_t detected_encoding_size);

参数:

  • input_data const uint8_t* - 输入字节流
  • input_len int32_t - 输入字节长度
  • target_encoding const char* - 目标编码名称,大小写不敏感,支持 WhatWG 标准名称和别名:
    • UTF-8:utf-8、utf8、unicode-1-1-utf-8
    • GBK:gbk、gb2312、gb18030、chinese、csgb2312
    • Shift_JIS:shift_jis、sjis、shift-jis、ms_kanji
    • Big5:big5、big5-hkscs、cn-big5、csbig5
    • EUC-KR:euc-kr、cseuckr、korean
    • windows-1252:windows-1252、ascii、latin1、iso-8859-1
    • 完整列表见 WhatWG Encoding Standard
  • output_buffer char* - 输出缓冲区(NUL 结尾)
  • buffer_size int32_t - 输出缓冲区大小(字节)
  • detected_encoding char* - [输出] 检测到的来源编码名称(可为 NULL)
  • detected_encoding_size int32_t - detected_encoding 缓冲区大小

返回值:

返回值含义
>0成功,写入输出缓冲区的字节数(不含 NUL)
0失败(参数无效、编码检测失败、目标编码不支持等)
<0缓冲区不足,绝对值为所需缓冲区大小

检测逻辑:

  1. BOM 优先(UTF-8 BOM / UTF-16 LE BOM / UTF-16 BE BOM)
  2. 无 BOM 时使用 chardetng 智能检测
  3. 源编码与目标编码相同时直接复制

文本内存管理(jade_text_create / jade_text_free)

C
char* jade_text_create(const char* text);
void jade_text_free(char* ptr);
  • jade_text_create:把一段 UTF-8 文本拷到堆上,返回指针,供 register_ipc_handler 等返回动态长度应答;库读完应答后会 jade_text_free,与手动 malloc+free 混用易出错,请成对使用本 API。
  • jade_text_free:释放由 jade_text_create 分配的指针;不要对栈内存、malloc 其它路径的指针调用。

若 invoke 只需默认成功、无自定义 JSON,可返回 NULL 或 (const char*)(uintptr_t)1 等占位(不是「阻止」;见 IPC 通信 API)。