RGF_CJ 的 rgf.win_def 注册表值结构体 pvalueW:定义、字段语义与 Win32 查询机制解析

原创2026-10-14 13:43:051,979 阅读
文章标签:图形学桌面应用

RGF_CJ 的 rgf.win_def 注册表值结构体 pvalueW:定义、字段语义与 Win32 查询机制解析

导读

pvalueW 是 RGF_CJ 项目 rgf.win_def 子包中随开箱即用的 Windows API 一并提供的 Win32 注册表相关结构体,用于描述一个采用宽字符(UTF-16)值名的注册表值项。本文以 API 文档页 pvalueW.md 为主体,结合仓库源码 hwinreg.cj 中与注册表提供程序(Registry Provider)机制相关的 val_context、provider_info、QUERYHANDLER 等类型,完整讲解其仓颉定义、四个字段的 Win32 语义、配套类型别名,并给出在仓颉工程中使用它的代码示例。读完本文,你将理解如何在 RGF_CJ 中通过仓颉 C 互操作层使用注册表查询回调所依赖的值描述结构体。

一、pvalueW 在 RGF_CJ 中的定位

RGF(RGF 仓颉版)是 Windows 系统下基于 Direct3D、Direct2D、DXGI、DirectWrite、WIC、GDI、GDIplus 等技术开发的通用渲染框架(兼应用开发框架)。正如项目主文档 README_zh.md 所述,在 Windows 开发方面,RGF 在子包内提供开箱即用的 Windows API,确保熟悉 Win32 的开发者快速上手。

pvalueW 即属于其中的 rgf.win_def 子包——该子包对应 Win32 SDK 中 winreg.h、winuser.h、windef.h 等头文件声明的数据类型与常量,包括句柄、结构体、类型别名、函数包装等。从包目录 doc/api/rgf.win_def/readme.md 可以看到,该包结构体家族中还包含 _FILETIME、_GUID、tagPOINT、tagRECT、pvalueA、val_context、value_entW、provider_info 等成员,pvalueW 与它们共同组成注册表与系统信息相关 API 的仓颉侧数据结构层。

在源码层面,pvalueW 定义于 hwinreg.cj,与注册表查询/提供程序机制的类型集中放在一起,因此其核心用途指向 Win32 注册表查询回调(QUERYHANDLER)中对注册表值进行描述。

二、结构体定义与构造签名

2.1 声明形式

文档给出了 pvalueW 的完整声明:

@C
public struct pvalueW
  • @C 属性表示该结构体采用 C 互操作内存布局,可直接与 Win32 原生代码进行无拷贝的数据交换;
  • 结构体字段全部使用 let ...! 声明为不可变字段,并通过构造函数提供默认值,因此可以零参数实例化。

2.2 构造函数签名

public pvalueW(
    let pv_valuename!: LPWSTR = LPWSTR(),
    let pv_valuelen!: INT = 0,
    let pv_value_context!: LPVOID = LPVOID(),
    let pv_type!: DWORD = 0
)

四个形参均带有默认值:值名指针默认空指针、长度默认 0、上下文默认空指针、类型默认 0。这意味着一行 pvalueW() 即可得到一个所有字段为零值的合法实例,便于在回调场景中先声明后填充。

2.3 字段语义

名称 类型 Win32 语义 默认值
pv_valuename LPWSTR 指向注册表值名的宽字符(UTF-16)字符串指针,对应 Win32 中 WCHAR* LPWSTR()(空指针)
pv_valuelen INT 值名长度(字符数),INT 即 Int32 0
pv_value_context LPVOID 值上下文指针,供查询方携带与具体值绑定的上下文数据 LPVOID()(空指针)
pv_type DWORD 注册表值的数据类型标识(如 REG_SZ、REG_DWORD 等),DWORD 即 UInt32 0

从源码结构看,pv_value_context 与注册表查询机制中 val_context 结构体的 value_context 字段相呼应,二者共同服务于把“值的上下文”在查询回调间传递的设计。

三、配套类型别名:PVALUEW 与 PPVALUEW

紧随结构体定义,源码在同一文件中给出了两个类型别名:

public type PVALUEW = pvalueW
public type PPVALUEW = CPointer<PVALUEW>
  • PVALUEW:即 pvalueW 本身,对应 Win32 中 PVALUEW 的语义(指向值结构体的指针类型名);
  • PPVALUEW:指向 PVALUEW 的仓颉 CPointer,用于在 foreign 互操作函数签名中表达“指向值结构体数组/指针的指针”。

这两个别名同样登记在 类型别名.md 中,供包外开发者直接引用。与之对称的 ANSI 版本为 pvalueA(值名为 LPSTR 窄字符指针)及其别名 PVALUEA、PPVALUEA,定义见 pvalueA.md。若开发场景需要同时支持 ANSI 与 Unicode 两套注册表 API,可分别使用 pvalueA/pvalueW 对应两条函数变体。

四、在注册表查询机制中的角色(源码佐证)

4.1 与同组类型的源码关系

在 hwinreg.cj 中,pvalueW 与以下类型连续排列,构成一套完整的注册表提供程序(Registry Provider)查询数据结构:

  • val_context:值上下文,含 valuelen、value_context、val_buff_ptr 三个字段;
  • provider_info(别名 REG_PROVIDER):注册表提供程序描述,含 pi_R0_1val、pi_R0_allvals、pi_R3_1val、pi_R3_allvals 四个查询回调指针(类型均为 PQUERYHANDLER)、pi_flags 与 pi_key_context;
  • QUERYHANDLER:查询回调类型,源码注释给出了其 C 原型:
DWORD __cdecl QUERYHANDLER(
    LPVOID keycontext,
    PVALCONTEXT val_list,
    DWORD num_vals,
    LPVOID outputbuffer,
    DWORD *total_outlen,
    DWORD input_blen
);

从这种“值描述结构体 + 上下文结构体 + 提供程序结构体 + 回调类型”集中定义、以及 pvalueW/pvalueA 成对出现的组织方式可以推断:pvalueW 是注册表查询回调中用于描述单个注册表值(宽字符值名)的数据载体,配合 val_context 与 provider_info 使用。

4.2 与常规注册表 API 的对比

除上述提供程序机制外,hwinreg.cj 中还封装了大量常规注册表操作函数,可作为理解 pvalueW 用途的对照:

  • wRegQueryValueExW(hwinreg.cj):按值名查询单个注册表值,签名中直接使用 LPCWSTR、LPBYTE、LPDWORD,无需 pvalueW;
  • wRegEnumValueW(hwinreg.cj):枚举注册表键下的值;
  • wRegQueryMultipleValuesW(hwinreg.cj):批量查询多个值,其 val_list 参数类型为 PVALENTW(对应结构体 value_entW,含 ve_valuename、ve_valuelen、ve_valueptr、ve_type 四个字段)。

可以看出:常规 API 走“参数列表传指针”的方式,而 pvalueW 所属的提供程序机制走“结构体打包传递”的方式。两者并存于同一个头文件对应的互操作层中。

五、在仓颉工程中使用 pvalueW 的代码示例

以下示例演示如何在 RGF_CJ 工程中引入 rgf.win_def 包并实例化、使用 pvalueW。注意:pvalueW 主要用于接收 Win32 回调传入的数据,示例聚焦于声明与构造两种方式。

5.1 依赖引入

在 cjpm.toml 中声明对 RGF_CJ 的依赖(此处以本地路径形式示意):

[dependencies]
rgf = { path = "RGF_CJ" }

在仓颉源码中导入子包:

import rgf.win_def.*

5.2 零参数构造(全默认值)

// 使用全部默认值,得到一个所有字段为零的结构体实例
let empty: pvalueW = pvalueW()

5.3 显式指定字段构造

// 显式指定值名指针、长度、上下文与类型
let pw: pvalueW = pvalueW(
    pv_valuename = uStrToUTF16Ptr("AppVersion"), // 借助 rgf.win_def 的字符串转换工具得到 LPWSTR
    pv_valuelen = 10,
    pv_value_context = LPVOID(),
    pv_type = 1 // 示例:REG_SZ 的取值
)

说明:rgf.win_def 包提供 uStrToUTF16Ptr(String) 等字符串编码转换工具(见 readme.md 函数列表),可将仓颉 String 转为 CPointer<WCHAR>(即 LPWSTR),再填入 pv_valuename。

5.4 通过指针别名互操作

当需要把 pvalueW 实例交给 foreign 函数时,使用 PPVALUEW(或 PVALUEW 配合 inout)传递地址:

let val: PVALUEW = pvalueW()
let pVal: PPVALUEW = CPointer<PVALUEW>(inout val) // 将实例地址包装为指针

具体互操作函数的签名与 PVALENTW、PVALCONTEXT 等指针类型的用法一致,均以 CPointer 家族类型承接 Win32 原生指针。

六、使用注意事项

  • 宽字符语义:pvalueW 的 pv_valuename 类型为 LPWSTR(CPointer<WCHAR>,WCHAR 为 Int16),值名按 UTF-16 编码解释;需要窄字符(ANSI)值时改用 pvalueA,避免混用导致编码错乱。
  • 指针生命周期:pv_valuename 与 pv_value_context 均为指针字段,RGF_CJ 的互操作层负责与原生内存对接,但指针指向的内存的分配与释放需遵循对应 Win32 API 的约定(由系统或提供程序负责),仓颉侧不应擅自释放非本层分配的内存。
  • 默认值与零值:构造函数的默认值(空指针、0、0、0)与 Win32 对未初始化结构体置零后的布局一致,可用于回调前的“先零后填”模式。
  • 适用前提:本文涉及的注册表提供程序机制属于 Win32 高级互操作场景,面向熟悉注册表 API 的开发者;常规读写注册表可优先选用 wRegGetValueW、wRegSetValueExW 等函数包装(同样位于 hwinreg.cj)。

七、小结

pvalueW 是 RGF_CJ rgf.win_def 子包注册表互操作层中的一个精简单元结构体:@C 布局保证与 Win32 原生结构一致,四个字段完整覆盖“值名、长度、上下文、类型”四要素,配套的 PVALUEW/PPVALUEW 别名让其在仓颉指针互操作中可直接使用。结合同文件中的 val_context、provider_info、QUERYHANDLER 等类型,可以判断它服务于 Win32 注册表查询回调中对注册表值的描述与传递。对需要在 RGF_CJ 中深度对接 Win32 注册表机制(尤其是提供程序查询场景)的开发者,本文给出的定义、字段语义与示例可直接作为上手参考。

参考路径

登录后查看全文
RGF_CJ