WSL C SDK 结构体解析WslcImageInfo 镜像元数据模型与 WslcListSessionImages 调用链【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSLWslcImageInfo是 WSLWindows Subsystem for LinuxC SDK 中用于描述「会话内容器镜像」元数据的核心结构体由WslcListSessionImages一次性填充返回。本文将围绕该结构体的字段语义、长度常量、内存所有权以及从底层兼容层到 WinRT 投影的完整转换链路展开帮助开发者准确地在 C/C 与 WinRT 两侧读写镜像信息并正确衔接加载、删除、标记、推送等镜像生命周期 API。结构体定义与字段语义WslcImageInfo在 wslcsdk.h 中定义如下#define WSLC_IMAGE_NAME_LENGTH 256 // 255 chars null typedef struct WslcImageInfo { // we should expose this CHAR name[WSLC_IMAGE_NAME_LENGTH]; uint8_t sha256[32]; int64_t sizeBytes; uint64_t createdUnixTime; } WslcImageInfo;字段一览字段类型语义nameCHAR[WSLC_IMAGE_NAME_LENGTH]镜像名称固定 256 字节255 个字符 终止符\0sha256uint8_t[32]镜像内容 SHA-256 摘要32 字节原始二进制sizeBytesint64_t镜像大小字节有符号 64 位整数createdUnixTimeuint64_t镜像创建时间Unix 时间戳自 1970-01-01 起的秒数name定长 ANSI 字符串缓冲区name是定长字符数组长度由宏WSLC_IMAGE_NAME_LENGTH控制值为256源码注释明确说明为 255 chars null。该常量同时记录在 constants.md 的常量清单中是 SDK 各镜像相关结构体共用的命名长度约定。由于是定长数组而非指针WslcImageInfo可以直接被整体拷贝例如放进数组、按值传递无需额外深拷贝字符串这正是 SDK 选择该布局的原因之一。sha25632 字节原始二进制摘要sha256保存的是原始二进制摘要而非十六进制字符串因此在打印或比对前需要自行转码。关于该字段的来源格式细节参见下文WslcListSessionImages的填充逻辑。createdUnixTimeUnix 秒级时间戳createdUnixTime是uint64_t类型的 Unix 时间戳。在 WinRT 投影层中它会被转换为Windows::Foundation::DateTime见 ImageInfo.cpp转换方式为winrt::clock::from_time_t即按「秒」解释该数值这印证了其单位为 Unix 秒。数据从哪来WslcListSessionImages 的填充逻辑WslcImageInfo由WslcListSessionImages批量产出其声明位于 wslcsdk.hSTDAPI WslcListSessionImages( _In_ WslcSession session, _Outptr_result_buffer_(*count) WslcImageInfo** images, _Out_ uint32_t* count);该 API 的实现在 wslcsdk.cpp核心流程如下编译期契约校验通过static_assert断言WslcImageInfo::name与内部兼容结构WSLCCompatImageInformation::Image的尺寸一致并通过static_assert(std::is_trivial_vWslcImageInfo, ...)要求该结构体保持平凡trivial类型保证可以直接用memcpy级操作拷贝。参数与状态检查images、count为空时返回E_POINTER会话句柄无效时返回HRESULT_FROM_WIN32(ERROR_INVALID_STATE)。调用内部会话服务session-ListImages(...)拿到一组内部镜像信息源码中留有 TODO 注释说明后续可通过WSLC_LIST_IMAGES_OPTIONS增加过滤选项。逐字段填充对每个内部条目执行memcpy_s拷贝镜像名到nameConvertSHA256Hash(currentImage.Hash, currentResult.sha256)解析哈希currentResult.sizeBytes currentImage.Size;currentResult.createdUnixTime currentImage.Created;ConvertSHA256Hash从 sha256: 字符串到 32 字节sha256字段的来源字符串解析位于 wslcsdk.cpp 的ConvertSHA256Hashvoid ConvertSHA256Hash(const char* hashString, uint8_t sha256[32]) { static constexpr std::string_view s_sha256Prefix sha256:sv; static constexpr size_t s_sha256ByteCount 32; ... auto hashBytes wsl::windows::common::string::HexToBytes(hashStringView.substr(s_sha256Prefix.length())); THROW_HR_IF_MSG(E_INVALIDARG, hashBytes.size() ! s_sha256ByteCount, SHA256 hash was not 32 bytes: %zu, hashBytes.size()); memcpy(sha256, hashBytes[0], s_sha256ByteCount); }要点内部哈希以sha256:为前缀的十六进制字符串形式存在函数先校验前缀不匹配时抛E_UNEXPECTED再去掉前缀做十六进制到字节的转换转换结果必须恰好为 32 字节否则抛E_INVALIDARG从而保证WslcImageInfo::sha256恒为完整的 32 字节摘要。兼容层转换WSLCImageInformation → WSLCCompatImageInformation内部数据的兼容转换定义在 APICompat.cppWSLCCompatImageInformation Convert(const WSLCImageInformation Image) { WSLCCompatImageInformation result{}; CopyString(result.Image, Image.Image); CopyString(result.Hash, Image.Hash); CopyString(result.Digest, Image.Digest); result.Size Image.Size; result.Created Image.Created; CopyString(result.ParentId, Image.ParentId); return result; }可见WslcImageInfo的四个字段只是内部镜像信息名称、哈希、大小、创建时间在公开 C API 层的精简投影Digest、ParentId等内部字段并未暴露到公开结构体中。内存所有权与调用示例WslcListSessionImages通过_Outptr_result_buffer_(*count)输出数组指针实现中使用wil::make_unique_cotaskmemWslcImageInfo[]分配wslcsdk.cpp因此数组由调用方负责释放应使用CoTaskMemFree或其 WIL 封装归还WslcSession session /* 已创建的会话句柄 */; WslcImageInfo* images nullptr; uint32_t count 0; HRESULT hr WslcListSessionImages(session, images, count); if (SUCCEEDED(hr) images ! nullptr) { for (uint32_t i 0; i count; i) { // images[i].name —— ANSI 字符串最长 255 字符 // images[i].sha256 —— 32 字节 SHA-256 摘要 // images[i].sizeBytes —— 镜像字节大小 // images[i].createdUnixTime —— Unix 秒级时间戳 } CoTaskMemFree(images); // 必须由调用方释放 }配套注意点返回数组以count为准count 0时images可能为nullptr实现中仅在非空时才分配调用方应分别判空name字段后续可直接作为删除依据传给WslcDeleteSessionImage(_In_ WslcSession session, _In_z_ PCSTR nameOrID, ...)声明见 wslcsdk.h即「先列出镜像拿到 name再按 name 或 ID 删除」的标准操作闭环。WinRT 投影ImageInfo runtimeclass除纯 C API 外SDK 还提供了 WinRT 投影层。WslcImageInfo被包装为Microsoft.WSL.Containers.ImageInfo其 IDL 定义在 wslcsdk.idlruntimeclass ImageInfo { String Name { get; }; Windows.Storage.Streams.IBuffer Sha256 { get; }; UInt64 Size { get; }; Windows.Foundation.DateTime CreatedTimestamp { get; }; };实现类见 ImageInfo.cpp四个属性的转换规则为WinRT 属性来源字段转换方式Namenamewinrt::to_hstring转为hstringSha256sha256经DataWriter.WriteBytes写入IBufferSizesizeBytes直接赋值uint64_tCreatedTimestampcreatedUnixTimewinrt::clock::from_time_t转为DateTime会话侧由Session::GetImages()统一编排Session.cpp先调用WslcListSessionImagescheck_hresult强校验 HRESULT再把每个WslcImageInfo包装为ImageInfo并返回只读向量视图。也就是说无论走 C 接口还是 WinRT 接口最终数据源都是WslcImageInfo所对应的那一条镜像记录。在镜像生命周期管理中的位置WslcImageInfo是「查询」环节的数据载体与之配套的写操作 API 全部声明在 wslcsdk.h 中并同步导出在 wslcsdk.def加载WslcLoadSessionImage/WslcLoadSessionImageFromFile配套选项结构见 wslcloadimageoptions.md删除WslcDeleteSessionImage参数nameOrID即WslcImageInfo::name的典型消费方打标签WslcTagSessionImage配套 wslctagimageoptions.md含image、repo、tag三字段推送WslcPushSessionImage配套 wslcpushimageoptions.md需 Base64 编码的registryAuth认证WslcAuthenticateSession返回的 token 可直接作为registryAuth使用wslcsdk.cpp 的注释说明。典型的开发流程为列出镜像得到WslcImageInfo数组→ 依据name/sha256判断目标镜像 → 执行加载、删除、打标签或推送。其他相关结构体的完整索引见 structures/index.md。使用要点与限制平凡类型约束WslcImageInfo被static_assert强制为 trivial 类型wslcsdk.cppSDK 依赖该性质做零初始化currentResult {}与整体拷贝因此不要用带自管理资源的成员去扩展该结构体定长命名name上限 255 个 ANSI 字符wslcsdk.h超长镜像名会被截断或无法匹配跨平台场景需注意非 ASCII 名称的编码问题哈希为二进制sha256是原始字节与常见sha256:xxxx...十六进制形式不同需要时可用HexToBytes的逆操作转换该工具函数定义于src/windows/common/string模块错误语义空指针返回E_POINTER、会话失效返回ERROR_INVALID_STATE、内部列表失败直接透传 HRESULT调用方应统一按 HRESULT 处理平台前提本结构体属于 WSL 容器 SDKWSLC的 Windows 侧 C 接口仅在启用容器功能的 WSL 环境中配合WslcSession使用。综上WslcImageInfo以极小的四个字段承载了镜像查询的核心信息其定长、平凡、二进制安全的布局设计贯穿了整个 SDK 的内存与类型约定理解它就等于拿到了 WSL 容器镜像管理链路的数据契约。【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考