WSL 容器镜像 API 指南：WslcImage APIs 完整详解与 C 语言实战

导读

本文聚焦 Windows Subsystem for Linux（WSL）仓库中 WslcSDK 提供的 Image APIs，系统讲解 WSL 自定义容器（WSL Custom Container）会话中镜像的拉取（Pull）、导入（Import）、加载（Load）、删除（Delete）、列出（List）、打标签（Tag）与推送（Push）九大 C 语言接口。文中将逐一给出函数签名、参数语义、返回约定、内存管理规则与可直接编译运行的代码示例，并结合 wslcsdk.h 头文件与 wslcsdk.cpp 实现剖析其底层数据结构与回调机制。读完本文，你将能够在自己的 Windows 程序中通过 WslcSDK 完整管理 WSL 容器镜像生命周期。

Image APIs 概览：九大镜像操作

Image APIs 是 WslcSDK 头文件 中以 Wslc 前缀导出的镜像管理接口集合，全部作用于同一个不透明句柄 WslcSession（DECLARE_HANDLE 定义见 wslcsdk.h#L60）。会话由 WslcInitSessionSettings / WslcCreateSession 创建，是镜像操作的前提。九大接口如下：

接口	功能	输入来源	方向
WslcPullSessionImage	从容器注册表拉取镜像	远程 URI	入
WslcImportSessionImage	从 HANDLE 流导入镜像	本地数据流	入
WslcImportSessionImageFromFile	从文件导入镜像	本地文件	入
WslcLoadSessionImage	从 HANDLE 流加载镜像	本地数据流	入
WslcLoadSessionImageFromFile	从文件加载镜像	本地文件	入
WslcDeleteSessionImage	按名称或 ID 删除镜像	会话内镜像	管理
WslcListSessionImages	列出会话内全部镜像	会话内镜像	管理
WslcTagSessionImage	为镜像打标签	会话内镜像	管理
WslcPushSessionImage	推送镜像到注册表	会话内镜像	出

Import 与 Load 的区别：从接口形态看，Import 需要显式指定 imageName（导入后命名），Load 不指定名称（加载后保留镜像自身携带的名称）；两者都接受 WslcImportImageOptions / WslcLoadImageOptions（结构体完全一致，仅类型名不同，见 wslcsdk.h#L483-L504）。

所有接口统一遵循以下约定：

• 返回类型均为 HRESULT，用 SUCCEEDED(hr) / FAILED(hr) 判断成败；
• 所有接口最后一个参数是 _Outptr_opt_result_z_ PWSTR* errorMessage，可选，成功后为 NULL，失败时返回错误文本，使用后需以 CoTaskMemFree 释放；
• 所有镜像操作都以 WslcSession 为第一个参数，属于"会话级"操作，不提供全局游离的镜像管理接口。

会话与镜像进度回调：所有接口的公共基础

WslcSession 句柄

WslcSession 是不透明句柄（wslcsdk.h#L60），所有镜像 API 的第一个入参。它必须由以下流程先创建：

WslcSessionSettings settings = { 0 };
WslcInitSessionSettings(L"my-session", L"C:\\wsl\\storage", &settings);

WslcSession session = NULL;
WslcCreateSession(&settings, &session, NULL);

镜像进度回调机制

Pull / Import / Load / Push 四类接口都支持进度回调。核心数据结构定义在 wslcsdk.h#L445-L470：

typedef struct WslcImageProgressDetail
{
    _Out_ uint64_t currentBytes; // bytes downloaded so far
    _Out_ uint64_t totalBytes;   // total bytes expected
} WslcImageProgressDetail;

typedef enum WslcImageProgressStatus
{
    WSLC_IMAGE_PROGRESS_STATUS_UNKNOWN = 0,
    WSLC_IMAGE_PROGRESS_STATUS_PULLING = 1,     // "Pulling fs layer"
    WSLC_IMAGE_PROGRESS_STATUS_WAITING = 2,     // "Waiting"
    WSLC_IMAGE_PROGRESS_STATUS_DOWNLOADING = 3, // "Downloading"
    WSLC_IMAGE_PROGRESS_STATUS_VERIFYING = 4,   // "Verifying Checksum"
    WSLC_IMAGE_PROGRESS_STATUS_EXTRACTING = 5,  // "Extracting"
    WSLC_IMAGE_PROGRESS_STATUS_COMPLETE = 6     // "Pull complete"
} WslcImageProgressStatus;

typedef struct WslcImageProgressMessage
{
    _Out_ PCSTR id;                       // layer ID or digest
    _Out_ WslcImageProgressStatus status; // "Downloading", "Extracting", etc.
    _Out_ WslcImageProgressDetail detail;
} WslcImageProgressMessage;

typedef HRESULT(CALLBACK* WslcContainerImageProgressCallback)(const WslcImageProgressMessage* progress, PVOID context);

要点：

• WslcImageProgressStatus 六个枚举值与 Docker CLI 的进度语义一一对应，从 "Pulling fs layer" 到 "Pull complete"，方便直接映射到 UI 文案；
• detail 携带 currentBytes / totalBytes，可计算百分比进度；
• 回调返回 S_OK 表示继续，返回其他 HRESULT 可中止操作（依据标准 COM 回调约定）；
• context 是透传指针，用于把用户数据（如进度条控件指针）传入回调，避免全局变量。

一个通用的进度回调实现如下（即 Pull 接口示例中使用的回调）：

HRESULT CALLBACK OnImageProgress(const WslcImageProgressMessage* progress, PVOID context)
{
    UNREFERENCED_PARAMETER(context);
    printf("%s %llu/%llu\n",
        progress->id,
        (unsigned long long)progress->detail.currentBytes,
        (unsigned long long)progress->detail.totalBytes);
    return S_OK;
}

拉取镜像：WslcPullSessionImage

从容器注册表拉取镜像到当前会话，对应 Docker 的 docker pull。声明见 wslcsdk.h#L481：

STDAPI WslcPullSessionImage(_In_ WslcSession session, _In_ const WslcPullImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);

参数表：

参数	类型	方向	说明
session	WslcSession	in	目标会话句柄
options	const WslcPullImageOptions*	in	拉取选项，见下
errorMessage	PWSTR*	out, optional	失败时的错误文本，需 CoTaskMemFree

WslcPullImageOptions 定义（wslcsdk.h#L473-L479）：

typedef struct WslcPullImageOptions
{
    _In_z_ PCSTR uri;                          // 必填，如 "docker.io/library/alpine:latest"
    WslcContainerImageProgressCallback progressCallback;      // 可选，进度回调
    PVOID progressCallbackContext;                            // 可选，回调上下文
    _In_opt_z_ PCSTR registryAuth;                            // 可选，注册表认证（Base64 编码）
} WslcPullImageOptions;

字段语义：

• uri：完整的镜像引用，包含注册表地址、仓库名与标签，例如 docker.io/library/alpine:latest；
• progressCallback / progressCallbackContext：可选进度回调及其上下文，传 NULL 表示不需要进度通知；
• registryAuth：可选，注册表身份凭证。SDK 提供了 WslcAuthenticate 系列接口用于获取可直接用作 registryAuth 的 identity token（见 wslcsdk.h#L548-L556 附近的身份令牌类型说明），私有仓库拉取时必填。

完整示例：

WslcPullImageOptions pullOptions = { 0 };
pullOptions.uri = "docker.io/library/alpine:latest";
pullOptions.progressCallback = OnImageProgress;
pullOptions.progressCallbackContext = NULL;
pullOptions.registryAuth = NULL;

HRESULT hr = WslcPullSessionImage(session, &pullOptions, NULL);
if (FAILED(hr))
{
    // 处理失败，可从 errorMessage 获取详细错误
}

导入镜像：WslcImportSessionImage 与 WslcImportSessionImageFromFile

导入指把本地容器镜像归档（如 OCI/Docker tar 格式）注册进会话。两个接口分别面向"数据流句柄"与"文件路径"两种输入方式。

从 HANDLE 数据流导入：WslcImportSessionImage

STDAPI WslcImportSessionImage(
    _In_ WslcSession session,
    _In_z_ PCSTR imageName,
    _In_ HANDLE imageContent,
    _In_ uint64_t imageContentBytes,
    _In_opt_ const WslcImportImageOptions* options,
    _Outptr_opt_result_z_ PWSTR* errorMessage);

参数表：

参数	类型	方向	说明
session	WslcSession	in	目标会话
imageName	PCSTR	in	导入后的镜像名称（含标签），如 "demo/imported:latest"
imageContent	HANDLE	in	镜像归档文件的句柄（注意：是 HANDLE 而非 void*）
imageContentBytes	uint64_t	in	镜像数据总字节数
options	const WslcImportImageOptions*	in, optional	导入选项
errorMessage	PWSTR*	out, optional	错误文本

头文件特别强调：imageContent 声明为 HANDLE，不是 void*。这意味着直接传入内存缓冲指针是类型不匹配的，必须传 CreateFileW 等 Win32 API 返回的文件句柄。

完整示例：

HANDLE imageContent = CreateFileW(
    L"C:\\images\\demo-import.tar",
    GENERIC_READ,
    FILE_SHARE_READ,
    NULL,
    OPEN_EXISTING,
    FILE_ATTRIBUTE_NORMAL,
    NULL);
if (imageContent == INVALID_HANDLE_VALUE) { /* 处理打开失败 */ }

LARGE_INTEGER size = { 0 };
GetFileSizeEx(imageContent, &size);

WslcImportImageOptions importOptions = { 0 };
HRESULT hr = WslcImportSessionImage(
    session,
    "demo/imported:latest",
    imageContent,
    (uint64_t)size.QuadPart,
    &importOptions,
    NULL);

CloseHandle(imageContent);

从文件路径导入：WslcImportSessionImageFromFile

STDAPI WslcImportSessionImageFromFile(
    _In_ WslcSession session, _In_z_ PCSTR imageName, _In_z_ PCWSTR path, _In_opt_ const WslcImportImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);

参数	类型	方向	说明
session	WslcSession	in	目标会话
imageName	PCSTR	in	导入后的镜像名称（ANSI 字符串）
path	PCWSTR	in	镜像归档文件的宽字符路径
options	const WslcImportImageOptions*	in, optional	导入选项
errorMessage	PWSTR*	out, optional	错误文本

示例：

WslcImportImageOptions importOptions = { 0 };
HRESULT hr = WslcImportSessionImageFromFile(
    session,
    "demo/imported:latest",
    L"C:\\images\\demo-import.tar",
    &importOptions,
    NULL);

两种方式的选择建议：已有文件句柄（如正在流式下载、解包过程中）用 WslcImportSessionImage 避免二次打开；直接从固定路径读取用 WslcImportSessionImageFromFile 代码更简洁。

加载镜像：WslcLoadSessionImage 与 WslcLoadSessionImageFromFile

加载与导入的区别在于：Load 不需要指定镜像名，镜像归档中自带的名称与标签会被保留（对应 Docker 的 docker load）。加载同样支持 HANDLE 流与文件路径两种方式。

从 HANDLE 数据流加载：WslcLoadSessionImage

STDAPI WslcLoadSessionImage(
    _In_ WslcSession session,
    _In_ HANDLE imageContent,
    _In_ uint64_t imageContentBytes,
    _In_opt_ const WslcLoadImageOptions* options,
    _Outptr_opt_result_z_ PWSTR* errorMessage);

参数	类型	方向	说明
session	WslcSession	in	目标会话
imageContent	HANDLE	in	归档文件句柄（同为 HANDLE 而非 void*）
imageContentBytes	uint64_t	in	数据字节数
options	const WslcLoadImageOptions*	in, optional	加载选项
errorMessage	PWSTR*	out, optional	错误文本

示例：

HANDLE imageContent = CreateFileW(
    L"C:\\images\\demo-load.tar",
    GENERIC_READ,
    FILE_SHARE_READ,
    NULL,
    OPEN_EXISTING,
    FILE_ATTRIBUTE_NORMAL,
    NULL);
if (imageContent == INVALID_HANDLE_VALUE) { /* 处理打开失败 */ }

LARGE_INTEGER size = { 0 };
GetFileSizeEx(imageContent, &size);

WslcLoadImageOptions loadOptions = { 0 };
HRESULT hr = WslcLoadSessionImage(
    session,
    imageContent,
    (uint64_t)size.QuadPart,
    &loadOptions,
    NULL);

CloseHandle(imageContent);

从文件路径加载：WslcLoadSessionImageFromFile

STDAPI WslcLoadSessionImageFromFile(
    _In_ WslcSession session, _In_z_ PCWSTR path, _In_opt_ const WslcLoadImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);

参数	类型	方向	说明
session	WslcSession	in	目标会话
path	PCWSTR	in	归档文件路径（宽字符）
options	const WslcLoadImageOptions*	in, optional	加载选项
errorMessage	PWSTR*	out, optional	错误文本

示例：

WslcLoadImageOptions loadOptions = { 0 };
HRESULT hr = WslcLoadSessionImageFromFile(
    session,
    L"C:\\images\\demo-load.tar",
    &loadOptions,
    NULL);

WslcLoadImageOptions 与 WslcImportImageOptions 结构体字段完全一致（均含 progressCallback 与 progressCallbackContext 两个可选字段），因此加载同样可以挂接进度回调。

删除镜像：WslcDeleteSessionImage

按名称或 ID 删除会话内镜像，对应 Docker 的 docker rmi：

STDAPI WslcDeleteSessionImage(_In_ WslcSession session, _In_z_ PCSTR nameOrID, _Outptr_opt_result_z_ PWSTR* errorMessage);

参数	类型	方向	说明
session	WslcSession	in	目标会话
nameOrID	PCSTR	in	镜像名称（含标签）或镜像 ID
errorMessage	PWSTR*	out, optional	错误文本

示例：

HRESULT hr = WslcDeleteSessionImage(session, "demo/imported:latest", NULL);

nameOrID 同时接受名称与 ID 两种形态，这得益于 SDK 内部镜像索引同时维护名称与 SHA-256 摘要（见下方 WslcImageInfo 的 sha256[32] 字段），为调用方提供了灵活的寻址方式。

列出镜像：WslcListSessionImages

枚举会话内的全部镜像，对应 Docker 的 docker images：

STDAPI WslcListSessionImages(_In_ WslcSession session, _Outptr_result_buffer_(*count) WslcImageInfo** images, _Out_ uint32_t* count);

参数	类型	方向	说明
session	WslcSession	in	目标会话
images	WslcImageInfo**	out	镜像信息数组指针（成功时由 SDK 分配）
count	uint32_t*	out	镜像数量；失败时置为 0

WslcImageInfo 定义（wslcsdk.h#L518-L525）：

#define WSLC_IMAGE_NAME_LENGTH 256 // 255 chars + null

typedef struct WslcImageInfo
{
    // we should expose this
    CHAR name[WSLC_IMAGE_NAME_LENGTH];  // 镜像名称（含标签），固定 256 字节缓冲区
    uint8_t sha256[32];                 // 镜像的 SHA-256 摘要
    int64_t sizeBytes;                  // 镜像大小（字节）
    uint64_t createdUnixTime;           // 创建时间（Unix 时间戳）
} WslcImageInfo;

内存管理规则（头文件明确要求）：images 数组由 SDK 使用 CoTaskMemAlloc 分配，调用方取得所有权后必须调用 CoTaskMemFree 释放（见 wslcsdk.h#L617-L625 的注释说明）。

完整示例：

WslcImageInfo* images = NULL;
uint32_t count = 0;
HRESULT hr = WslcListSessionImages(session, &images, &count);

if (SUCCEEDED(hr))
{
    for (uint32_t i = 0; i < count; ++i)
    {
        printf("%s\n", images[i].name);
    }
    CoTaskMemFree(images);   // 必须释放，否则内存泄漏
}

WslcImageInfo 提供了名称、SHA-256 摘要、字节大小与创建时间四项元数据，足以支撑镜像浏览、去重、空间统计等常见管理功能；WSLC_IMAGE_NAME_LENGTH（255 字符 + 结尾空字符）限定了名称缓冲区长度。

打标签：WslcTagSessionImage

为会话内已有镜像追加或改写标签，对应 Docker 的 docker tag：

STDAPI WslcTagSessionImage(_In_ WslcSession session, _In_ const WslcTagImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);

WslcTagImageOptions 定义（wslcsdk.h#L529-L534）：

typedef struct WslcTagImageOptions
{
    _In_z_ PCSTR image; // Source image name or ID.
    _In_z_ PCSTR repo;  // Target repository name.
    _In_z_ PCSTR tag;   // Target tag name.
} WslcTagImageOptions;

字段	说明
image	源镜像名称或 ID
repo	目标仓库名
tag	目标标签名

示例：

WslcTagImageOptions tagOptions = { 0 };
tagOptions.image = "docker.io/library/alpine:latest";
tagOptions.repo = "demo/alpine";
tagOptions.tag = "stable";

HRESULT hr = WslcTagSessionImage(session, &tagOptions, NULL);

该示例将 alpine:latest 标记为 demo/alpine:stable，典型用途是：本地镜像在推送私有仓库前，先改写为包含仓库前缀的完整引用；或为同一镜像维护 latest 与 stable 等多个语义标签。image 同样支持 ID 寻址，与 WslcDeleteSessionImage 的寻址约定一致。

推送镜像：WslcPushSessionImage

将会话内镜像推送到容器注册表，对应 Docker 的 docker push：

STDAPI WslcPushSessionImage(_In_ WslcSession session, _In_ const WslcPushImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);

WslcPushImageOptions 定义（wslcsdk.h#L538-L544）：

typedef struct WslcPushImageOptions
{
    _In_z_ PCSTR image;
    _In_z_ PCSTR registryAuth; // Base64-encoded X-Registry-Auth header value.
    _In_opt_ WslcContainerImageProgressCallback progressCallback;
    _In_opt_ PVOID progressCallbackContext;
} WslcPushImageOptions;

字段	说明
image	要推送的镜像引用
registryAuth	必填，Base64 编码的 X-Registry-Auth 请求头值
progressCallback / progressCallbackContext	可选进度回调及其上下文

完整示例：

WslcPushImageOptions pushOptions = { 0 };
pushOptions.image = "demo/alpine:stable";
pushOptions.registryAuth = "BASE64_X_REGISTRY_AUTH";
pushOptions.progressCallback = OnImageProgress;
pushOptions.progressCallbackContext = NULL;

HRESULT hr = WslcPushSessionImage(session, &pushOptions, NULL);

注意两点：

1. registryAuth 字段在此结构体中是必填项，注释明确指出其值必须是 Base64 编码的 X-Registry-Auth 请求头值，即标准 Docker Registry HTTP API 的认证头格式，私有仓库推送时需确保凭据正确编码；
2. 推送前通常先用 WslcTagSessionImage 把镜像引用改写为包含目标仓库与标签的完整形式（如 demo/alpine:stable），再执行推送。

镜像操作典型工作流

将上述接口串联起来，一个完整的"拉取-打标签-推送"工作流如下：

// 1. 创建会话
WslcSessionSettings settings = { 0 };
WslcInitSessionSettings(L"ci-session", L"C:\\wsl\\storage", &settings);
WslcSession session = NULL;
WslcCreateSession(&settings, &session, NULL);

// 2. 拉取官方镜像
WslcPullImageOptions pullOptions = { 0 };
pullOptions.uri = "docker.io/library/alpine:latest";
WslcPullSessionImage(session, &pullOptions, NULL);

// 3. 为推送打标签
WslcTagImageOptions tagOptions = { 0 };
tagOptions.image = "docker.io/library/alpine:latest";
tagOptions.repo = "myregistry.example.com/team/alpine";
tagOptions.tag = "v1.0";
WslcTagSessionImage(session, &tagOptions, NULL);

// 4. 推送到私有仓库
WslcPushImageOptions pushOptions = { 0 };
pushOptions.image = "myregistry.example.com/team/alpine:v1.0";
pushOptions.registryAuth = base64AuthString;
WslcPushSessionImage(session, &pushOptions, NULL);

// 5. 校验结果并清理
WslcImageInfo* images = NULL;
uint32_t count = 0;
WslcListSessionImages(session, &images, &count);
// ... 遍历 images[0..count-1] ...
CoTaskMemFree(images);

WslcDeleteSessionImage(session, "myregistry.example.com/team/alpine:v1.0", NULL);

迁移场景（离线分发）则走"导出 → Load/Import"链路：在其他机器上通过 WslcImportSessionImageFromFile / WslcLoadSessionImageFromFile 把 tar 归档灌入新会话。选择 Load 可保留镜像原始名称，选择 Import 则可在导入时自定义名称，适合统一命名规范。

与 WinRT 封装的对应关系

WslcSDK 在 C 接口之上还提供了 WinRT 层封装（见 src/windows/WslcSDK/winrt 目录下的 Session.cpp、PullImageOptions.cpp、TagImageOptions.cpp、ImageInfo.cpp），供 C#/XAML 应用使用。C 接口是本 API 的基础层：结构体定义、进度回调语义、CoTaskMemAlloc 内存规则都在 C 头文件 wslcsdk.h 中确立，WinRT 层仅做投影封装。因此理解本文的 C 接口，也就掌握了整个镜像 API 的底层行为。

使用建议与注意事项

• 内存管理：WslcListSessionImages 返回的数组必须 CoTaskMemFree；errorMessage 非空时同样需要 CoTaskMemFree 释放；
• 句柄类型：WslcImportSessionImage / WslcLoadSessionImage 的 imageContent 参数是 HANDLE，不是内存指针，切勿混用；
• 进度回调：回调在 SDK 内部线程上执行，若需更新 UI，请通过 progressCallbackContext 传递同步机制（如投递到 UI 线程的消息），不要在回调中直接操作 UI 句柄；
• 认证：私有仓库的 Pull / Push 需提供认证凭据——Pull 通过 WslcPullImageOptions.registryAuth，Push 通过 WslcPushImageOptions.registryAuth（Base64 编码的 X-Registry-Auth 值）；SDK 提供的身份令牌接口（见 wslcsdk.h 中 WslcIdentityTokenType 相关注释）可直接生成适用于这两个字段的 token；
• 失败处理：所有接口都应检查 HRESULT 并优先将 errorMessage 透传给用户，便于定位注册表网络、镜像格式或认证类问题。

小结

Image APIs 以 WslcSession 为统一上下文，通过九大接口覆盖了 WSL 自定义容器镜像从拉取、导入、加载到列出、删除、打标签、推送的完整生命周期。理解 WslcImageProgressMessage 回调机制与 CoTaskMemAlloc 内存约定，是在真实项目中正确使用这套 API 的关键。相关的 WinRT 封装与完整头文件声明可继续查阅 src/windows/WslcSDK/wslcsdk.h、src/windows/WslcSDK/wslcsdk.cpp 以及 doc/docs/api-reference/c/index.md 中的 C API 参考索引。