跳到主要内容

工具 API

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

与系统深度集成、偏扩展能力的接口（如 URL 协议、文件关联、全局热键）已迁移到插件分类下的 系统集成 API。

获取 JadeView 版本（jadeview_version）​

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

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

获取系统路径（getPath）​

用途：用固定的英文关键字查询一类目录的绝对路径，避免自己在 C 里拼环境变量、处理中文用户名路径。例如要放日志、读「我的文档」、找 exe 所在目录，都可以问这个接口。

int32_t getPath(const char* name, char* buffer, size_t buffer_size);
name大致对应（Windows 常见情况）
home当前用户主目录（类似资源管理器里的「用户」文件夹上层里的个人目录）。
appData按用户区分的应用数据目录（常接近 %LOCALAPPDATA%）。
sessionData与 WebView 会话/缓存相关的目录（在 JadeView 配置的数据目录下的子路径）。
temp系统临时目录。
exe当前宿主进程 exe 的完整路径（谁加载了 DLL 就是谁）。
desktop / documents / downloads / music / pictures / videos桌面、文档、下载、音乐、图片、视频等用户文件夹。
logs应用日志目录（在数据目录下，不存在时可能会创建）。
appexe 所在目录（安装目录），适合读同目录资源。

成功时把路径写入 buffer（UTF-8 + \0）。失败返回 0。

获取系统语言（getLocale）​

用途：读取 Windows 当前用户界面语言（区域设置），得到一个标准语言标签字符串。常见用途：决定宿主或网页用中文还是英文界面、把语言参数传给前端做 i18n。

int32_t getLocale(char* buffer, size_t buffer_size);

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

成功 1，失败 0（缓冲区不够、指针无效等）。

获取显示器信息（get_displays_info）​

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

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（缓冲不够、解析失败等）。

YAML 配置读写​

对应 API：yaml_set、yaml_get。用途：在 JadeView 为应用准备的数据目录里，用一个小 YAML 文件存配置（主题、上次打开的路径、开关等），不需要经过网页。适合宿主进程自己要持久化一点键值结构。

int32_t yaml_set(const char* file_name, const char* key_path, const char* value);
int32_t yaml_get(const char* file_name, const char* key_path, char* buffer, size_t buffer_size);
  • file_name 只能是文件名（如 config.yaml），不能带 .. 或路径分隔符，实际文件在 {数据目录}\{file_name}。
  • key_path 用点分层级，如 ui.theme 表示嵌套字段。
  • yaml_set 写入时，value 会按规则尝试解析成 JSON / YAML 片段，否则当普通字符串存。
  • yaml_get 读出的值会统一转成 JSON 文本写进 buffer（带 \0），方便再用 JSON 库解析。

清空数据目录（clear_data_directory）​

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

int32_t clear_data_directory(const char* confirm_token);

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

其它工具函数​

获取窗口数量（get_window_count）​

uint32_t get_window_count(void);

返回当前由 JadeView 管理、尚未关闭的窗口数量。

获取 WebView 版本（get_webview_version）​

int32_t get_webview_version(char* buffer, size_t buffer_size);

把本机 WebView2 运行时版本号写入 buffer（UTF-8 + \0）。成功返回 1，失败 0（缓冲不够、指针无效等）。不是 JadeView DLL 自身版本（那是 jadeview_version）。

判断是否为 Windows 11（is_windows_11）​

int32_t is_windows_11(void);

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

文本内存管理（jade_text_create / jade_text_free）​

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）。