Added WSLc API docs (#40922)
* Updated doc structure --------- Co-authored-by: docs-builder <docs-builder@localhost>
Craig Loewen committed
Jun 26, 2026 at 17:28 UTC
7ba8496e8c5c25e7641e2080f064046ee990d7b0
228 files changed
+5090
-10
.github/workflows/documentation.yml
+4
-3
@@ -3,6 +3,7 @@ on:
3
workflow_dispatch:
4
push:
5
branches: [main, master]
6
+ paths: ['doc/**']
7
8
concurrency:
9
group: ${{ github.workflow }}
@@ -23,11 +24,11 @@ jobs:
24
uses: actions/checkout@v4
25
26
- name: Install packages
26
- run: pip install mkdocs-mermaid2-plugin mkdocs --break-system-packages
27
+ run: pip install -r doc/requirements.txt --break-system-packages
28
shell: bash
29
30
- name: Build documentation
30
- run: mkdocs build -f doc/mkdocs.yml
31
+ run: mkdocs build -f doc/mkdocs.yml
32
shell: bash
33
34
- uses: actions/upload-pages-artifact@v4
@@ -36,4 +37,4 @@ jobs:
37
38
- name: Deploy to GitHub Pages
39
id: deployment
39
- uses: actions/deploy-pages@v4
\ No newline at end of file
40
+ uses: actions/deploy-pages@v4
doc/README.md
+3
-3
@@ -1,10 +1,10 @@
1
# WSL open source documentation
2
3
-Build instructions:
3
+Build instructions:
4
5
```
6
-$ pip install mkdocs mkdocs-mermaid2-plugin
7
-$ mkdocs serve
6
+$ pip install -r doc/requirements.txt
7
+$ mkdocs serve -f doc/mkdocs.yml
8
```
9
10
You can then view the documentation at `http://127.0.0.1:8000/`.
\ No newline at end of file
doc/docs/api-reference/.pages
new
+6
@@ -0,0 +1,6 @@
1
+nav:
2
+ - index.md
3
+ - c
4
+ - cpp
5
+ - csharp
6
+title: API reference
doc/docs/api-reference/c/.pages
new
+15
@@ -0,0 +1,15 @@
1
+title: C API reference
2
+nav:
3
+ - index.md
4
+ - structures
5
+ - callback-types
6
+ - session-apis
7
+ - container-apis
8
+ - process-apis
9
+ - image-apis
10
+ - storage-apis
11
+ - install-and-version-apis
12
+ - enumerations
13
+ - error-codes.md
14
+ - not-yet-implemented-apis.md
15
+ - end-to-end-example.md
doc/docs/api-reference/c/callback-types/.pages
new
+8
@@ -0,0 +1,8 @@
1
+title: Callback Types
2
+nav:
3
+ - index.md
4
+ - wslcsessioncrashdumpcallback.md
5
+ - wslcstdiocallback.md
6
+ - wslcprocessexitcallback.md
7
+ - wslccontainerimageprogresscallback.md
8
+ - wslcinstallcallback.md
doc/docs/api-reference/c/callback-types/index.md
new
+10
@@ -0,0 +1,10 @@
1
+# Callback Types
2
+
3
+
4
+## Members
5
+
6
+- [WslcSessionCrashDumpCallback](wslcsessioncrashdumpcallback.md)
7
+- [WslcStdIOCallback](wslcstdiocallback.md)
8
+- [WslcProcessExitCallback](wslcprocessexitcallback.md)
9
+- [WslcContainerImageProgressCallback](wslccontainerimageprogresscallback.md)
10
+- [WslcInstallCallback](wslcinstallcallback.md)
doc/docs/api-reference/c/callback-types/wslccontainerimageprogresscallback.md
new
+10
@@ -0,0 +1,10 @@
1
+# WslcContainerImageProgressCallback
2
+
3
+```c
4
+typedef HRESULT(CALLBACK* WslcContainerImageProgressCallback)(const WslcImageProgressMessage* progress, PVOID context);
5
+```
6
+
7
+| Parameter | Type |
8
+|---|---|
9
+| `progress` | `const WslcImageProgressMessage*` |
10
+| `context` | `PVOID` |
doc/docs/api-reference/c/callback-types/wslcinstallcallback.md
new
+15
@@ -0,0 +1,15 @@
1
+# WslcInstallCallback
2
+
3
+```c
4
+typedef __callback void(CALLBACK* WslcInstallCallback)(
5
+ _In_ WslcComponentFlags component, _In_ uint32_t progressSteps, _In_ uint32_t totalSteps, _In_opt_ PVOID context);
6
+```
7
+
8
+| Parameter | Type |
9
+|---|---|
10
+| `component` | `WslcComponentFlags` |
11
+| `progressSteps` | `uint32_t` |
12
+| `totalSteps` | `uint32_t` |
13
+| `context` | `PVOID` |
14
+
15
+---
doc/docs/api-reference/c/callback-types/wslcprocessexitcallback.md
new
+10
@@ -0,0 +1,10 @@
1
+# WslcProcessExitCallback
2
+
3
+```c
4
+typedef __callback void(CALLBACK* WslcProcessExitCallback)(INT32 exitCode, _In_opt_ PVOID context);
5
+```
6
+
7
+| Parameter | Type |
8
+|---|---|
9
+| `exitCode` | `INT32` |
10
+| `context` | `PVOID` |
doc/docs/api-reference/c/callback-types/wslcsessioncrashdumpcallback.md
new
+12
@@ -0,0 +1,12 @@
1
+# WslcSessionCrashDumpCallback
2
+
3
+```c
4
+typedef __callback void(CALLBACK* WslcSessionCrashDumpCallback)(_In_ const WslcSessionCrashDumpInfo* info, _In_opt_ PVOID context);
5
+```
6
+
7
+Parameters:
8
+
9
+| Parameter | Type |
10
+|---|---|
11
+| `info` | `const WslcSessionCrashDumpInfo*` |
12
+| `context` | `PVOID` |
doc/docs/api-reference/c/callback-types/wslcstdiocallback.md
new
+13
@@ -0,0 +1,13 @@
1
+# WslcStdIOCallback
2
+
3
+```c
4
+typedef __callback void(CALLBACK* WslcStdIOCallback)(
5
+ WslcProcessIOHandle ioHandle, _In_reads_bytes_(dataBytes) const BYTE* data, _In_ uint32_t dataBytes, _In_opt_ PVOID context);
6
+```
7
+
8
+Header notes:
9
+
10
+- Only `STDOUT` and `STDERR` receive callbacks.
11
+- `data` is owned by WSLC and is only valid during the callback.
12
+- The buffer is not null-terminated.
13
+- The callback should return promptly.
doc/docs/api-reference/c/container-apis/.pages
new
+23
@@ -0,0 +1,23 @@
1
+title: Container APIs
2
+nav:
3
+ - index.md
4
+ - wslcinitcontainersettings.md
5
+ - wslccreatecontainer.md
6
+ - wslcstartcontainer.md
7
+ - wslcsetcontainersettingsname.md
8
+ - wslcsetcontainersettingsinitprocess.md
9
+ - wslcsetcontainersettingsnetworkingmode.md
10
+ - wslcsetcontainersettingshostname.md
11
+ - wslcsetcontainersettingsdomainname.md
12
+ - wslcsetcontainersettingsflags.md
13
+ - wslcsetcontainersettingsportmappings.md
14
+ - wslcsetcontainersettingsvolumes.md
15
+ - wslcsetcontainersettingsnamedvolumes.md
16
+ - wslccreatecontainerprocess.md
17
+ - wslcgetcontainerid.md
18
+ - wslcgetcontainerinitprocess.md
19
+ - wslcinspectcontainer.md
20
+ - wslcgetcontainerstate.md
21
+ - wslcstopcontainer.md
22
+ - wslcdeletecontainer.md
23
+ - wslcreleasecontainer.md
doc/docs/api-reference/c/container-apis/index.md
new
+25
@@ -0,0 +1,25 @@
1
+# Container APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcInitContainerSettings](wslcinitcontainersettings.md)
7
+- [WslcCreateContainer](wslccreatecontainer.md)
8
+- [WslcStartContainer](wslcstartcontainer.md)
9
+- [WslcSetContainerSettingsName](wslcsetcontainersettingsname.md)
10
+- [WslcSetContainerSettingsInitProcess](wslcsetcontainersettingsinitprocess.md)
11
+- [WslcSetContainerSettingsNetworkingMode](wslcsetcontainersettingsnetworkingmode.md)
12
+- [WslcSetContainerSettingsHostName](wslcsetcontainersettingshostname.md)
13
+- [WslcSetContainerSettingsDomainName](wslcsetcontainersettingsdomainname.md)
14
+- [WslcSetContainerSettingsFlags](wslcsetcontainersettingsflags.md)
15
+- [WslcSetContainerSettingsPortMappings](wslcsetcontainersettingsportmappings.md)
16
+- [WslcSetContainerSettingsVolumes](wslcsetcontainersettingsvolumes.md)
17
+- [WslcSetContainerSettingsNamedVolumes](wslcsetcontainersettingsnamedvolumes.md)
18
+- [WslcCreateContainerProcess](wslccreatecontainerprocess.md)
19
+- [WslcGetContainerID](wslcgetcontainerid.md)
20
+- [WslcGetContainerInitProcess](wslcgetcontainerinitprocess.md)
21
+- [WslcInspectContainer](wslcinspectcontainer.md)
22
+- [WslcGetContainerState](wslcgetcontainerstate.md)
23
+- [WslcStopContainer](wslcstopcontainer.md)
24
+- [WslcDeleteContainer](wslcdeletecontainer.md)
25
+- [WslcReleaseContainer](wslcreleasecontainer.md)
doc/docs/api-reference/c/container-apis/wslccreatecontainer.md
new
+21
@@ -0,0 +1,21 @@
1
+# WslcCreateContainer
2
+
3
+```c
4
+STDAPI WslcCreateContainer(_In_ WslcSession session, _In_ const WslcContainerSettings* containerSettings, _Out_ WslcContainer* container, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `containerSettings` | `const WslcContainerSettings*` | in |
11
+| `container` | `WslcContainer*` | out |
12
+| `errorMessage` | `PWSTR*` | out, optional |
13
+
14
+Return value: `HRESULT`.
15
+
16
+Example:
17
+
18
+```c
19
+WslcContainer container = NULL;
20
+HRESULT hr = WslcCreateContainer(session, &containerSettings, &container, NULL);
21
+```
doc/docs/api-reference/c/container-apis/wslccreatecontainerprocess.md
new
+28
@@ -0,0 +1,28 @@
1
+# WslcCreateContainerProcess
2
+
3
+```c
4
+STDAPI WslcCreateContainerProcess(
5
+ _In_ WslcContainer container, _In_ WslcProcessSettings* newProcessSettings, _Out_ WslcProcess* newProcess, _Outptr_opt_result_z_ PWSTR* errorMessage);
6
+```
7
+
8
+| Parameter | Type | Direction |
9
+|---|---|---|
10
+| `container` | `WslcContainer` | in |
11
+| `newProcessSettings` | `WslcProcessSettings*` | in |
12
+| `newProcess` | `WslcProcess*` | out |
13
+| `errorMessage` | `PWSTR*` | out, optional |
14
+
15
+Return value: `HRESULT`.
16
+
17
+Example:
18
+
19
+```c
20
+WslcProcessSettings processSettings;
21
+WslcProcess process = NULL;
22
+PCSTR const argv[] = { "/bin/echo", "hello from wscl" };
23
+
24
+WslcInitProcessSettings(&processSettings);
25
+WslcSetProcessSettingsCmdLine(&processSettings, argv, _countof(argv));
26
+
27
+HRESULT hr = WslcCreateContainerProcess(container, &processSettings, &process, NULL);
28
+```
doc/docs/api-reference/c/container-apis/wslcdeletecontainer.md
new
+22
@@ -0,0 +1,22 @@
1
+# WslcDeleteContainer
2
+
3
+```c
4
+STDAPI WslcDeleteContainer(_In_ WslcContainer container, _In_ WslcDeleteContainerFlags flags, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `flags` | `WslcDeleteContainerFlags` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HRESULT hr = WslcDeleteContainer(
19
+ container,
20
+ WSLC_DELETE_CONTAINER_FLAG_FORCE,
21
+ NULL);
22
+```
doc/docs/api-reference/c/container-apis/wslcgetcontainerid.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetContainerID
2
+
3
+```c
4
+STDAPI WslcGetContainerID(_In_ WslcContainer container, _Out_writes_(WSLC_CONTAINER_ID_BUFFER_SIZE) CHAR containerID[WSLC_CONTAINER_ID_BUFFER_SIZE]);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `containerID` | `CHAR[WSLC_CONTAINER_ID_BUFFER_SIZE]` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+CHAR containerID[WSLC_CONTAINER_ID_BUFFER_SIZE] = { 0 };
18
+HRESULT hr = WslcGetContainerID(container, containerID);
19
+```
doc/docs/api-reference/c/container-apis/wslcgetcontainerinitprocess.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetContainerInitProcess
2
+
3
+```c
4
+STDAPI WslcGetContainerInitProcess(_In_ WslcContainer container, _Out_ WslcProcess* initProcess);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `initProcess` | `WslcProcess*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcProcess initProcess = NULL;
18
+HRESULT hr = WslcGetContainerInitProcess(container, &initProcess);
19
+```
doc/docs/api-reference/c/container-apis/wslcgetcontainerstate.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetContainerState
2
+
3
+```c
4
+STDAPI WslcGetContainerState(_In_ WslcContainer container, _Out_ WslcContainerState* state);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `state` | `WslcContainerState*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcContainerState state = WSLC_CONTAINER_STATE_INVALID;
18
+HRESULT hr = WslcGetContainerState(container, &state);
19
+```
doc/docs/api-reference/c/container-apis/wslcinitcontainersettings.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcInitContainerSettings
2
+
3
+```c
4
+STDAPI WslcInitContainerSettings(_In_ PCSTR imageName, _Out_ WslcContainerSettings* containerSettings);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `imageName` | `PCSTR` | in |
10
+| `containerSettings` | `WslcContainerSettings*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcContainerSettings containerSettings;
18
+HRESULT hr = WslcInitContainerSettings("docker.io/library/alpine:latest", &containerSettings);
19
+```
doc/docs/api-reference/c/container-apis/wslcinspectcontainer.md
new
+26
@@ -0,0 +1,26 @@
1
+# WslcInspectContainer
2
+
3
+```c
4
+STDAPI WslcInspectContainer(_In_ WslcContainer container, _Outptr_result_z_ PSTR* inspectData);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `inspectData` | `PSTR*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Header note: `inspectData` is allocated using `CoTaskMemAlloc`; free it with `CoTaskMemFree`.
15
+
16
+Example:
17
+
18
+```c
19
+PSTR inspectData = NULL;
20
+HRESULT hr = WslcInspectContainer(container, &inspectData);
21
+if (SUCCEEDED(hr))
22
+{
23
+ puts(inspectData);
24
+ CoTaskMemFree(inspectData);
25
+}
26
+```
doc/docs/api-reference/c/container-apis/wslcreleasecontainer.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcReleaseContainer
2
+
3
+```c
4
+STDAPI WslcReleaseContainer(_In_ WslcContainer container);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+HRESULT hr = WslcReleaseContainer(container);
17
+container = NULL;
18
+```
19
+
20
+---
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsdomainname.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetContainerSettingsDomainName
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsDomainName(_In_ WslcContainerSettings* containerSettings, _In_ PCSTR domainName);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `domainName` | `PCSTR` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetContainerSettingsDomainName(&containerSettings, "example.internal");
18
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsflags.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSetContainerSettingsFlags
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsFlags(_In_ WslcContainerSettings* containerSettings, _In_ WslcContainerFlags flags);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `flags` | `WslcContainerFlags` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetContainerSettingsFlags(
18
+ &containerSettings,
19
+ (WslcContainerFlags)(WSLC_CONTAINER_FLAG_AUTO_REMOVE | WSLC_CONTAINER_FLAG_ENABLE_GPU));
20
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingshostname.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetContainerSettingsHostName
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsHostName(_In_ WslcContainerSettings* containerSettings, _In_ PCSTR hostName);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `hostName` | `PCSTR` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetContainerSettingsHostName(&containerSettings, "demo-host");
18
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsinitprocess.md
new
+24
@@ -0,0 +1,24 @@
1
+# WslcSetContainerSettingsInitProcess
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsInitProcess(_In_ WslcContainerSettings* containerSettings, _In_ WslcProcessSettings* initProcess);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `initProcess` | `WslcProcessSettings*` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcProcessSettings initProcess;
18
+PCSTR const argv[] = { "/bin/sh", "-c", "sleep 3600" };
19
+
20
+WslcInitProcessSettings(&initProcess);
21
+WslcSetProcessSettingsCmdLine(&initProcess, argv, _countof(argv));
22
+
23
+HRESULT hr = WslcSetContainerSettingsInitProcess(&containerSettings, &initProcess);
24
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsname.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetContainerSettingsName
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsName(_In_ WslcContainerSettings* containerSettings, _In_ PCSTR name);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `name` | `PCSTR` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetContainerSettingsName(&containerSettings, "demo-container");
18
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsnamedvolumes.md
new
+30
@@ -0,0 +1,30 @@
1
+# WslcSetContainerSettingsNamedVolumes
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsNamedVolumes(
5
+ _In_ WslcContainerSettings* containerSettings,
6
+ _In_reads_opt_(namedVolumeCount) const WslcContainerNamedVolume* namedVolumes,
7
+ _In_ uint32_t namedVolumeCount);
8
+```
9
+
10
+| Parameter | Type | Direction |
11
+|---|---|---|
12
+| `containerSettings` | `WslcContainerSettings*` | in |
13
+| `namedVolumes` | `const WslcContainerNamedVolume*` | in, optional |
14
+| `namedVolumeCount` | `uint32_t` | in |
15
+
16
+Return value: `HRESULT`.
17
+
18
+Example:
19
+
20
+```c
21
+WslcContainerNamedVolume namedVolumes[1] = { 0 };
22
+namedVolumes[0].name = "cache";
23
+namedVolumes[0].containerPath = "/var/cache/demo";
24
+namedVolumes[0].readOnly = FALSE;
25
+
26
+HRESULT hr = WslcSetContainerSettingsNamedVolumes(
27
+ &containerSettings,
28
+ namedVolumes,
29
+ (uint32_t)_countof(namedVolumes));
30
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsnetworkingmode.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSetContainerSettingsNetworkingMode
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsNetworkingMode(_In_ WslcContainerSettings* containerSettings, _In_ WslcContainerNetworkingMode networkingMode);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `containerSettings` | `WslcContainerSettings*` | in |
10
+| `networkingMode` | `WslcContainerNetworkingMode` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetContainerSettingsNetworkingMode(
18
+ &containerSettings,
19
+ WSLC_CONTAINER_NETWORKING_MODE_BRIDGED);
20
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsportmappings.md
new
+31
@@ -0,0 +1,31 @@
1
+# WslcSetContainerSettingsPortMappings
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsPortMappings(
5
+ _In_ WslcContainerSettings* containerSettings,
6
+ _In_reads_opt_(portMappingCount) const WslcContainerPortMapping* portMappings,
7
+ _In_ uint32_t portMappingCount);
8
+```
9
+
10
+| Parameter | Type | Direction |
11
+|---|---|---|
12
+| `containerSettings` | `WslcContainerSettings*` | in |
13
+| `portMappings` | `const WslcContainerPortMapping*` | in, optional |
14
+| `portMappingCount` | `uint32_t` | in |
15
+
16
+Return value: `HRESULT`.
17
+
18
+Example:
19
+
20
+```c
21
+WslcContainerPortMapping portMappings[1] = { 0 };
22
+portMappings[0].windowsPort = (uint16_t)8080;
23
+portMappings[0].containerPort = (uint16_t)80;
24
+portMappings[0].protocol = WSLC_PORT_PROTOCOL_TCP;
25
+portMappings[0].windowsAddress = NULL;
26
+
27
+HRESULT hr = WslcSetContainerSettingsPortMappings(
28
+ &containerSettings,
29
+ portMappings,
30
+ (uint32_t)_countof(portMappings));
31
+```
doc/docs/api-reference/c/container-apis/wslcsetcontainersettingsvolumes.md
new
+28
@@ -0,0 +1,28 @@
1
+# WslcSetContainerSettingsVolumes
2
+
3
+```c
4
+STDAPI WslcSetContainerSettingsVolumes(
5
+ _In_ WslcContainerSettings* containerSettings, _In_reads_opt_(volumeCount) const WslcContainerVolume* volumes, _In_ uint32_t volumeCount);
6
+```
7
+
8
+| Parameter | Type | Direction |
9
+|---|---|---|
10
+| `containerSettings` | `WslcContainerSettings*` | in |
11
+| `volumes` | `const WslcContainerVolume*` | in, optional |
12
+| `volumeCount` | `uint32_t` | in |
13
+
14
+Return value: `HRESULT`.
15
+
16
+Example:
17
+
18
+```c
19
+WslcContainerVolume volumes[1] = { 0 };
20
+volumes[0].windowsPath = L"C:\\data";
21
+volumes[0].containerPath = "/mnt/data";
22
+volumes[0].readOnly = FALSE;
23
+
24
+HRESULT hr = WslcSetContainerSettingsVolumes(
25
+ &containerSettings,
26
+ volumes,
27
+ (uint32_t)_countof(volumes));
28
+```
doc/docs/api-reference/c/container-apis/wslcstartcontainer.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcStartContainer
2
+
3
+```c
4
+STDAPI WslcStartContainer(_In_ WslcContainer container, _In_ WslcContainerStartFlags flags, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `flags` | `WslcContainerStartFlags` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HRESULT hr = WslcStartContainer(container, WSLC_CONTAINER_START_FLAG_ATTACH, NULL);
19
+```
doc/docs/api-reference/c/container-apis/wslcstopcontainer.md
new
+24
@@ -0,0 +1,24 @@
1
+# WslcStopContainer
2
+
3
+```c
4
+STDAPI WslcStopContainer(_In_ WslcContainer container, _In_ WslcSignal signal, _In_ uint32_t timeoutSeconds, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `container` | `WslcContainer` | in |
10
+| `signal` | `WslcSignal` | in |
11
+| `timeoutSeconds` | `uint32_t` | in |
12
+| `errorMessage` | `PWSTR*` | out, optional |
13
+
14
+Return value: `HRESULT`.
15
+
16
+Example:
17
+
18
+```c
19
+HRESULT hr = WslcStopContainer(
20
+ container,
21
+ WSLC_SIGNAL_SIGTERM,
22
+ (uint32_t)30,
23
+ NULL);
24
+```
doc/docs/api-reference/c/end-to-end-example.md
new
+148
@@ -0,0 +1,148 @@
1
+# End-to-End Example
2
+
3
+The example below shows one full lifecycle:
4
+
5
+1. Initialize session settings
6
+2. Create a session
7
+3. Pull an image
8
+4. Configure a container
9
+5. Create and start the container
10
+6. Inspect it
11
+7. Create a second process
12
+8. Stop and delete the container
13
+9. Release handles and terminate the session
14
+
15
+```c
16
+
17
+#include <winsock2.h>
18
+#include <windows.h>
19
+#include <stdio.h>
20
+#include <objbase.h>
21
+#include <filesystem>
22
+#include "wslcsdk.h"
23
+
24
+#pragma comment(lib, "ole32.lib")
25
+#pragma comment(lib, "wslcsdk.lib")
26
+
27
+int main()
28
+{
29
+ // Initialize COM
30
+ CoInitializeEx(nullptr, COINIT_MULTITHREADED);
31
+
32
+ HRESULT hr;
33
+ PWSTR error = nullptr;
34
+
35
+ // 0. Check prerequisites
36
+ WslcComponentFlags missing = WSLC_COMPONENT_FLAG_NONE;
37
+ hr = WslcGetMissingComponents(&missing);
38
+ if (FAILED(hr) || missing != WSLC_COMPONENT_FLAG_NONE) {
39
+ printf("WSL components are missing. Run: wsl --install\n");
40
+ CoUninitialize();
41
+ return 1;
42
+ }
43
+
44
+ WslcVersion ver = {};
45
+ WslcGetVersion(&ver);
46
+ printf("WSL version: %u.%u.%u\n", ver.major, ver.minor, ver.revision);
47
+
48
+ // 1. Initialize and create a session
49
+ std::filesystem::path storagePath = std::filesystem::current_path();
50
+
51
+ WslcSessionSettings sessionSettings;
52
+ hr = WslcInitSessionSettings(L"MyApp", storagePath.c_str(), &sessionSettings);
53
+ if (FAILED(hr)) return 1;
54
+
55
+ // Optionally customize resources
56
+ WslcSetSessionSettingsCpuCount(&sessionSettings, 4);
57
+ WslcSetSessionSettingsMemory(&sessionSettings, 4096);
58
+
59
+ WslcSession session = nullptr;
60
+ hr = WslcCreateSession(&sessionSettings, &session, &error);
61
+ if (FAILED(hr)) {
62
+ wprintf(L"Session creation failed: %s\n", error ? error : L"unknown");
63
+ CoTaskMemFree(error);
64
+ CoUninitialize();
65
+ return 1;
66
+ }
67
+
68
+ // 2. Pull an image
69
+ WslcPullImageOptions pullOpts = {};
70
+ pullOpts.uri = "docker.io/library/alpine:latest";
71
+ hr = WslcPullSessionImage(session, &pullOpts, &error);
72
+ if (FAILED(hr)) {
73
+ wprintf(L"Pull failed: %s\n", error ? error : L"unknown");
74
+ CoTaskMemFree(error);
75
+ WslcTerminateSession(session);
76
+ WslcReleaseSession(session);
77
+ CoUninitialize();
78
+ return 1;
79
+ }
80
+
81
+ // 3. Configure an init process
82
+ WslcProcessSettings initProcSettings;
83
+ WslcInitProcessSettings(&initProcSettings);
84
+
85
+ PCSTR argv[] = { "/bin/echo", "Hello from WSL Container!" };
86
+ WslcSetProcessSettingsCmdLine(&initProcSettings, argv, 2);
87
+
88
+ // 4. Configure and create a container
89
+ WslcContainerSettings containerSettings;
90
+ WslcInitContainerSettings("alpine:latest", &containerSettings);
91
+ WslcSetContainerSettingsName(&containerSettings, "hello-container");
92
+ WslcSetContainerSettingsInitProcess(&containerSettings, &initProcSettings);
93
+
94
+ WslcContainer container = nullptr;
95
+ hr = WslcCreateContainer(session, &containerSettings, &container, &error);
96
+ if (FAILED(hr)) {
97
+ wprintf(L"Container creation failed: %s\n", error ? error : L"unknown");
98
+ CoTaskMemFree(error);
99
+ WslcTerminateSession(session);
100
+ WslcReleaseSession(session);
101
+ CoUninitialize();
102
+ return 1;
103
+ }
104
+
105
+ // 5. Start the container
106
+ hr = WslcStartContainer(container, WSLC_CONTAINER_START_FLAG_NONE, &error);
107
+ if (FAILED(hr)) {
108
+ wprintf(L"Start failed: %s\n", error ? error : L"unknown");
109
+ CoTaskMemFree(error);
110
+ WslcDeleteContainer(container, WSLC_DELETE_CONTAINER_FLAG_FORCE, nullptr);
111
+ WslcReleaseContainer(container);
112
+ WslcTerminateSession(session);
113
+ WslcReleaseSession(session);
114
+ CoUninitialize();
115
+ return 1;
116
+ }
117
+
118
+ // 6. Wait for the init process to exit
119
+ WslcProcess initProc = nullptr;
120
+ hr = WslcGetContainerInitProcess(container, &initProc);
121
+ if (SUCCEEDED(hr)) {
122
+ HANDLE exitEvent = nullptr;
123
+ if (SUCCEEDED(WslcGetProcessExitEvent(initProc, &exitEvent))) {
124
+ WaitForSingleObject(exitEvent, 30000); // 30-second timeout
125
+ }
126
+
127
+ INT32 exitCode = 0;
128
+ if (SUCCEEDED(WslcGetProcessExitCode(initProc, &exitCode))) {
129
+ printf("Process exited with code: %d\n", exitCode);
130
+ }
131
+ WslcReleaseProcess(initProc);
132
+ }
133
+
134
+ // 7. Clean up
135
+ WslcContainerState containerState = WSLC_CONTAINER_STATE_INVALID;
136
+ if (SUCCEEDED(WslcGetContainerState(container, &containerState)) &&
137
+ containerState == WSLC_CONTAINER_STATE_RUNNING) {
138
+ WslcStopContainer(container, WSLC_SIGNAL_SIGTERM, 10, nullptr);
139
+ }
140
+ WslcDeleteContainer(container, WSLC_DELETE_CONTAINER_FLAG_NONE, nullptr);
141
+ WslcReleaseContainer(container);
142
+ WslcTerminateSession(session);
143
+ WslcReleaseSession(session);
144
+
145
+ CoUninitialize();
146
+ return 0;
147
+}
148
+```
doc/docs/api-reference/c/enumerations/.pages
new
+18
@@ -0,0 +1,18 @@
1
+title: Enumerations
2
+nav:
3
+ - index.md
4
+ - wslccontainernetworkingmode.md
5
+ - wslcvhdtype.md
6
+ - wslcvhdrequirementsflags.md
7
+ - wslcsessionfeatureflags.md
8
+ - wslcsessionterminationreason.md
9
+ - wslcportprotocol.md
10
+ - wslccontainerflags.md
11
+ - wslccontainerstartflags.md
12
+ - wslccontainerstate.md
13
+ - wslcsignal.md
14
+ - wslcdeletecontainerflags.md
15
+ - wslcprocessiohandle.md
16
+ - wslcprocessstate.md
17
+ - wslcimageprogressstatus.md
18
+ - wslccomponentflags.md
doc/docs/api-reference/c/enumerations/index.md
new
+20
@@ -0,0 +1,20 @@
1
+# Enumerations
2
+
3
+
4
+## Members
5
+
6
+- [WslcContainerNetworkingMode](wslccontainernetworkingmode.md)
7
+- [WslcVhdType](wslcvhdtype.md)
8
+- [WslcVhdRequirementsFlags](wslcvhdrequirementsflags.md)
9
+- [WslcSessionFeatureFlags](wslcsessionfeatureflags.md)
10
+- [WslcSessionTerminationReason](wslcsessionterminationreason.md)
11
+- [WslcPortProtocol](wslcportprotocol.md)
12
+- [WslcContainerFlags](wslccontainerflags.md)
13
+- [WslcContainerStartFlags](wslccontainerstartflags.md)
14
+- [WslcContainerState](wslccontainerstate.md)
15
+- [WslcSignal](wslcsignal.md)
16
+- [WslcDeleteContainerFlags](wslcdeletecontainerflags.md)
17
+- [WslcProcessIOHandle](wslcprocessiohandle.md)
18
+- [WslcProcessState](wslcprocessstate.md)
19
+- [WslcImageProgressStatus](wslcimageprogressstatus.md)
20
+- [WslcComponentFlags](wslccomponentflags.md)
doc/docs/api-reference/c/enumerations/wslccomponentflags.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcComponentFlags
2
+
3
+```c
4
+typedef enum WslcComponentFlags
5
+{
6
+ WSLC_COMPONENT_FLAG_NONE = 0,
7
+ WSLC_COMPONENT_FLAG_VIRTUAL_MACHINE_PLATFORM = 1,
8
+ WSLC_COMPONENT_FLAG_WSL_PACKAGE = 2,
9
+ WSLC_COMPONENT_FLAG_SDK_NEEDS_UPDATE = 4,
10
+} WslcComponentFlags;
11
+```
12
+
13
+| Enumerator | Value |
14
+|---|---|
15
+| `WSLC_COMPONENT_FLAG_NONE` | `0` |
16
+| `WSLC_COMPONENT_FLAG_VIRTUAL_MACHINE_PLATFORM` | `1` |
17
+| `WSLC_COMPONENT_FLAG_WSL_PACKAGE` | `2` |
18
+| `WSLC_COMPONENT_FLAG_SDK_NEEDS_UPDATE` | `4` |
19
+
20
+---
doc/docs/api-reference/c/enumerations/wslccontainerflags.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcContainerFlags
2
+
3
+```c
4
+typedef enum WslcContainerFlags
5
+{
6
+ WSLC_CONTAINER_FLAG_NONE = 0x00000000,
7
+ WSLC_CONTAINER_FLAG_AUTO_REMOVE = 0x00000001,
8
+ WSLC_CONTAINER_FLAG_ENABLE_GPU = 0x00000002,
9
+ WSLC_CONTAINER_FLAG_PRIVILEGED = 0x00000004,
10
+
11
+} WslcContainerFlags;
12
+```
13
+
14
+| Enumerator | Value |
15
+|---|---|
16
+| `WSLC_CONTAINER_FLAG_NONE` | `0x00000000` |
17
+| `WSLC_CONTAINER_FLAG_AUTO_REMOVE` | `0x00000001` |
18
+| `WSLC_CONTAINER_FLAG_ENABLE_GPU` | `0x00000002` |
19
+| `WSLC_CONTAINER_FLAG_PRIVILEGED` | `0x00000004` |
doc/docs/api-reference/c/enumerations/wslccontainernetworkingmode.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcContainerNetworkingMode
2
+
3
+```c
4
+typedef enum WslcContainerNetworkingMode
5
+{
6
+ WSLC_CONTAINER_NETWORKING_MODE_NONE = 0, // No networking / isolated
7
+ WSLC_CONTAINER_NETWORKING_MODE_BRIDGED = 1
8
+} WslcContainerNetworkingMode;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_CONTAINER_NETWORKING_MODE_NONE` | `0` |
14
+| `WSLC_CONTAINER_NETWORKING_MODE_BRIDGED` | `1` |
doc/docs/api-reference/c/enumerations/wslccontainerstartflags.md
new
+15
@@ -0,0 +1,15 @@
1
+# WslcContainerStartFlags
2
+
3
+```c
4
+typedef enum WslcContainerStartFlags
5
+{
6
+ WSLC_CONTAINER_START_FLAG_NONE = 0x00000000,
7
+ WSLC_CONTAINER_START_FLAG_ATTACH = 0x00000001,
8
+
9
+} WslcContainerStartFlags;
10
+```
11
+
12
+| Enumerator | Value |
13
+|---|---|
14
+| `WSLC_CONTAINER_START_FLAG_NONE` | `0x00000000` |
15
+| `WSLC_CONTAINER_START_FLAG_ATTACH` | `0x00000001` |
doc/docs/api-reference/c/enumerations/wslccontainerstate.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcContainerState
2
+
3
+```c
4
+typedef enum WslcContainerState
5
+{
6
+ WSLC_CONTAINER_STATE_INVALID = 0,
7
+ WSLC_CONTAINER_STATE_CREATED = 1,
8
+ WSLC_CONTAINER_STATE_RUNNING = 2,
9
+ WSLC_CONTAINER_STATE_EXITED = 3,
10
+ WSLC_CONTAINER_STATE_DELETED = 4,
11
+} WslcContainerState;
12
+```
13
+
14
+| Enumerator | Value |
15
+|---|---|
16
+| `WSLC_CONTAINER_STATE_INVALID` | `0` |
17
+| `WSLC_CONTAINER_STATE_CREATED` | `1` |
18
+| `WSLC_CONTAINER_STATE_RUNNING` | `2` |
19
+| `WSLC_CONTAINER_STATE_EXITED` | `3` |
20
+| `WSLC_CONTAINER_STATE_DELETED` | `4` |
doc/docs/api-reference/c/enumerations/wslcdeletecontainerflags.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcDeleteContainerFlags
2
+
3
+```c
4
+typedef enum WslcDeleteContainerFlags
5
+{
6
+ WSLC_DELETE_CONTAINER_FLAG_NONE = 0,
7
+ WSLC_DELETE_CONTAINER_FLAG_FORCE = 0x01
8
+} WslcDeleteContainerFlags;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_DELETE_CONTAINER_FLAG_NONE` | `0` |
14
+| `WSLC_DELETE_CONTAINER_FLAG_FORCE` | `0x01` |
doc/docs/api-reference/c/enumerations/wslcimageprogressstatus.md
new
+24
@@ -0,0 +1,24 @@
1
+# WslcImageProgressStatus
2
+
3
+```c
4
+typedef enum WslcImageProgressStatus
5
+{
6
+ WSLC_IMAGE_PROGRESS_STATUS_UNKNOWN = 0,
7
+ WSLC_IMAGE_PROGRESS_STATUS_PULLING = 1, // "Pulling fs layer"
8
+ WSLC_IMAGE_PROGRESS_STATUS_WAITING = 2, // "Waiting"
9
+ WSLC_IMAGE_PROGRESS_STATUS_DOWNLOADING = 3, // "Downloading"
10
+ WSLC_IMAGE_PROGRESS_STATUS_VERIFYING = 4, // "Verifying Checksum"
11
+ WSLC_IMAGE_PROGRESS_STATUS_EXTRACTING = 5, // "Extracting"
12
+ WSLC_IMAGE_PROGRESS_STATUS_COMPLETE = 6 // "Pull complete"
13
+} WslcImageProgressStatus;
14
+```
15
+
16
+| Enumerator | Value |
17
+|---|---|
18
+| `WSLC_IMAGE_PROGRESS_STATUS_UNKNOWN` | `0` |
19
+| `WSLC_IMAGE_PROGRESS_STATUS_PULLING` | `1` |
20
+| `WSLC_IMAGE_PROGRESS_STATUS_WAITING` | `2` |
21
+| `WSLC_IMAGE_PROGRESS_STATUS_DOWNLOADING` | `3` |
22
+| `WSLC_IMAGE_PROGRESS_STATUS_VERIFYING` | `4` |
23
+| `WSLC_IMAGE_PROGRESS_STATUS_EXTRACTING` | `5` |
24
+| `WSLC_IMAGE_PROGRESS_STATUS_COMPLETE` | `6` |
doc/docs/api-reference/c/enumerations/wslcportprotocol.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcPortProtocol
2
+
3
+```c
4
+typedef enum WslcPortProtocol
5
+{
6
+ WSLC_PORT_PROTOCOL_TCP = 0,
7
+ WSLC_PORT_PROTOCOL_UDP = 1
8
+} WslcPortProtocol;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_PORT_PROTOCOL_TCP` | `0` |
14
+| `WSLC_PORT_PROTOCOL_UDP` | `1` |
doc/docs/api-reference/c/enumerations/wslcprocessiohandle.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcProcessIOHandle
2
+
3
+```c
4
+typedef enum WslcProcessIOHandle
5
+{
6
+ WSLC_PROCESS_IO_HANDLE_STDIN = 0,
7
+ WSLC_PROCESS_IO_HANDLE_STDOUT = 1,
8
+ WSLC_PROCESS_IO_HANDLE_STDERR = 2
9
+} WslcProcessIOHandle;
10
+```
11
+
12
+| Enumerator | Value |
13
+|---|---|
14
+| `WSLC_PROCESS_IO_HANDLE_STDIN` | `0` |
15
+| `WSLC_PROCESS_IO_HANDLE_STDOUT` | `1` |
16
+| `WSLC_PROCESS_IO_HANDLE_STDERR` | `2` |
doc/docs/api-reference/c/enumerations/wslcprocessstate.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcProcessState
2
+
3
+```c
4
+typedef enum WslcProcessState
5
+{
6
+ WSLC_PROCESS_STATE_UNKNOWN = 0,
7
+ WSLC_PROCESS_STATE_RUNNING = 1,
8
+ WSLC_PROCESS_STATE_EXITED = 2,
9
+ WSLC_PROCESS_STATE_SIGNALLED = 3
10
+} WslcProcessState;
11
+```
12
+
13
+| Enumerator | Value |
14
+|---|---|
15
+| `WSLC_PROCESS_STATE_UNKNOWN` | `0` |
16
+| `WSLC_PROCESS_STATE_RUNNING` | `1` |
17
+| `WSLC_PROCESS_STATE_EXITED` | `2` |
18
+| `WSLC_PROCESS_STATE_SIGNALLED` | `3` |
doc/docs/api-reference/c/enumerations/wslcsessionfeatureflags.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcSessionFeatureFlags
2
+
3
+```c
4
+typedef enum WslcSessionFeatureFlags
5
+{
6
+ WSLC_SESSION_FEATURE_FLAG_NONE = 0x00000000,
7
+ WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU = 0x00000004
8
+} WslcSessionFeatureFlags;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_SESSION_FEATURE_FLAG_NONE` | `0x00000000` |
14
+| `WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU` | `0x00000004` |
doc/docs/api-reference/c/enumerations/wslcsessionterminationreason.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcSessionTerminationReason
2
+
3
+```c
4
+typedef enum WslcSessionTerminationReason
5
+{
6
+ WSLC_SESSION_TERMINATION_REASON_UNKNOWN = 0,
7
+ WSLC_SESSION_TERMINATION_REASON_SHUTDOWN = 1,
8
+ WSLC_SESSION_TERMINATION_REASON_CRASHED = 2,
9
+} WslcSessionTerminationReason;
10
+```
11
+
12
+| Enumerator | Value |
13
+|---|---|
14
+| `WSLC_SESSION_TERMINATION_REASON_UNKNOWN` | `0` |
15
+| `WSLC_SESSION_TERMINATION_REASON_SHUTDOWN` | `1` |
16
+| `WSLC_SESSION_TERMINATION_REASON_CRASHED` | `2` |
doc/docs/api-reference/c/enumerations/wslcsignal.md
new
+22
@@ -0,0 +1,22 @@
1
+# WslcSignal
2
+
3
+```c
4
+typedef enum WslcSignal
5
+{
6
+ WSLC_SIGNAL_NONE = 0, // No signal; reserved for future use
7
+ WSLC_SIGNAL_SIGHUP = 1, // SIGHUP: reload / hangup
8
+ WSLC_SIGNAL_SIGINT = 2, // SIGINT: interrupt (Ctrl-C)
9
+ WSLC_SIGNAL_SIGQUIT = 3, // SIGQUIT: quit with core dump
10
+ WSLC_SIGNAL_SIGKILL = 9, // SIGKILL: immediate termination
11
+ WSLC_SIGNAL_SIGTERM = 15, // SIGTERM: graceful shutdown
12
+} WslcSignal;
13
+```
14
+
15
+| Enumerator | Value |
16
+|---|---|
17
+| `WSLC_SIGNAL_NONE` | `0` |
18
+| `WSLC_SIGNAL_SIGHUP` | `1` |
19
+| `WSLC_SIGNAL_SIGINT` | `2` |
20
+| `WSLC_SIGNAL_SIGQUIT` | `3` |
21
+| `WSLC_SIGNAL_SIGKILL` | `9` |
22
+| `WSLC_SIGNAL_SIGTERM` | `15` |
doc/docs/api-reference/c/enumerations/wslcvhdrequirementsflags.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcVhdRequirementsFlags
2
+
3
+```c
4
+typedef enum WslcVhdRequirementsFlags
5
+{
6
+ WSLC_VHD_REQ_FLAG_NONE = 0x00000000,
7
+ WSLC_VHD_REQ_FLAG_OWNER = 0x00000001,
8
+} WslcVhdRequirementsFlags;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_VHD_REQ_FLAG_NONE` | `0x00000000` |
14
+| `WSLC_VHD_REQ_FLAG_OWNER` | `0x00000001` |
doc/docs/api-reference/c/enumerations/wslcvhdtype.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcVhdType
2
+
3
+```c
4
+typedef enum WslcVhdType
5
+{
6
+ WSLC_VHD_TYPE_DYNAMIC = 0, // Expanding VHDX (default)
7
+ WSLC_VHD_TYPE_FIXED = 1 // Fixed-allocation VHDX (only honored by WslcCreateSessionVhdVolume)
8
+} WslcVhdType;
9
+```
10
+
11
+| Enumerator | Value |
12
+|---|---|
13
+| `WSLC_VHD_TYPE_DYNAMIC` | `0` |
14
+| `WSLC_VHD_TYPE_FIXED` | `1` |
doc/docs/api-reference/c/error-codes.md
new
+41
@@ -0,0 +1,41 @@
1
+# Error Codes
2
+
3
+```c
4
+#define WSLC_E_BASE (0x0600)
5
+#define WSLC_E_IMAGE_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 1) /* 0x80040601 */
6
+#define WSLC_E_CONTAINER_PREFIX_AMBIGUOUS MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 2) /* 0x80040602 */
7
+#define WSLC_E_CONTAINER_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 3) /* 0x80040603 */
8
+#define WSLC_E_VOLUME_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 4) /* 0x80040604 */
9
+#define WSLC_E_CONTAINER_NOT_RUNNING MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 5) /* 0x80040605 */
10
+#define WSLC_E_CONTAINER_IS_RUNNING MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 6) /* 0x80040606 */
11
+#define WSLC_E_SESSION_RESERVED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 7) /* 0x80040607 */
12
+#define WSLC_E_INVALID_SESSION_NAME MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 8) /* 0x80040608 */
13
+#define WSLC_E_NETWORK_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 9) /* 0x80040609 */
14
+#define WSLC_E_WU_SEARCH_FAILED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 10) /* 0x8004060A */
15
+#define WSLC_E_SDK_UPDATE_NEEDED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 11) /* 0x8004060B */
16
+#define WSLC_E_CONTAINER_DISABLED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 12) /* 0x8004060C */
17
+#define WSLC_E_REGISTRY_BLOCKED_BY_POLICY MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 13) /* 0x8004060D */
18
+#define WSLC_E_VOLUME_NOT_AVAILABLE MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 14) /* 0x8004060E */
19
+#define WSLC_E_SESSION_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 15) /* 0x8004060F */
20
+```
21
+
22
+| Symbol | Hex Value |
23
+|---|---|
24
+| `WSLC_E_BASE` | `0x0600` |
25
+| `WSLC_E_IMAGE_NOT_FOUND` | `0x80040601` |
26
+| `WSLC_E_CONTAINER_PREFIX_AMBIGUOUS` | `0x80040602` |
27
+| `WSLC_E_CONTAINER_NOT_FOUND` | `0x80040603` |
28
+| `WSLC_E_VOLUME_NOT_FOUND` | `0x80040604` |
29
+| `WSLC_E_CONTAINER_NOT_RUNNING` | `0x80040605` |
30
+| `WSLC_E_CONTAINER_IS_RUNNING` | `0x80040606` |
31
+| `WSLC_E_SESSION_RESERVED` | `0x80040607` |
32
+| `WSLC_E_INVALID_SESSION_NAME` | `0x80040608` |
33
+| `WSLC_E_NETWORK_NOT_FOUND` | `0x80040609` |
34
+| `WSLC_E_WU_SEARCH_FAILED` | `0x8004060A` |
35
+| `WSLC_E_SDK_UPDATE_NEEDED` | `0x8004060B` |
36
+| `WSLC_E_CONTAINER_DISABLED` | `0x8004060C` |
37
+| `WSLC_E_REGISTRY_BLOCKED_BY_POLICY` | `0x8004060D` |
38
+| `WSLC_E_VOLUME_NOT_AVAILABLE` | `0x8004060E` |
39
+| `WSLC_E_SESSION_NOT_FOUND` | `0x8004060F` |
40
+
41
+---
doc/docs/api-reference/c/image-apis/.pages
new
+12
@@ -0,0 +1,12 @@
1
+title: Image APIs
2
+nav:
3
+ - index.md
4
+ - wslcpullsessionimage.md
5
+ - wslcimportsessionimage.md
6
+ - wslcimportsessionimagefromfile.md
7
+ - wslcloadsessionimage.md
8
+ - wslcloadsessionimagefromfile.md
9
+ - wslcdeletesessionimage.md
10
+ - wslclistsessionimages.md
11
+ - wslctagsessionimage.md
12
+ - wslcpushsessionimage.md
doc/docs/api-reference/c/image-apis/index.md
new
+14
@@ -0,0 +1,14 @@
1
+# Image APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcPullSessionImage](wslcpullsessionimage.md)
7
+- [WslcImportSessionImage](wslcimportsessionimage.md)
8
+- [WslcImportSessionImageFromFile](wslcimportsessionimagefromfile.md)
9
+- [WslcLoadSessionImage](wslcloadsessionimage.md)
10
+- [WslcLoadSessionImageFromFile](wslcloadsessionimagefromfile.md)
11
+- [WslcDeleteSessionImage](wslcdeletesessionimage.md)
12
+- [WslcListSessionImages](wslclistsessionimages.md)
13
+- [WslcTagSessionImage](wslctagsessionimage.md)
14
+- [WslcPushSessionImage](wslcpushsessionimage.md)
doc/docs/api-reference/c/image-apis/wslcdeletesessionimage.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcDeleteSessionImage
2
+
3
+```c
4
+STDAPI WslcDeleteSessionImage(_In_ WslcSession session, _In_z_ PCSTR nameOrID, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `nameOrID` | `PCSTR` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HRESULT hr = WslcDeleteSessionImage(session, "demo/imported:latest", NULL);
19
+```
doc/docs/api-reference/c/image-apis/wslcimportsessionimage.md
new
+51
@@ -0,0 +1,51 @@
1
+# WslcImportSessionImage
2
+
3
+```c
4
+STDAPI WslcImportSessionImage(
5
+ _In_ WslcSession session,
6
+ _In_z_ PCSTR imageName,
7
+ _In_ HANDLE imageContent,
8
+ _In_ uint64_t imageContentBytes,
9
+ _In_opt_ const WslcImportImageOptions* options,
10
+ _Outptr_opt_result_z_ PWSTR* errorMessage);
11
+```
12
+
13
+| Parameter | Type | Direction |
14
+|---|---|---|
15
+| `session` | `WslcSession` | in |
16
+| `imageName` | `PCSTR` | in |
17
+| `imageContent` | `HANDLE` | in |
18
+| `imageContentBytes` | `uint64_t` | in |
19
+| `options` | `const WslcImportImageOptions*` | in, optional |
20
+| `errorMessage` | `PWSTR*` | out, optional |
21
+
22
+Return value: `HRESULT`.
23
+
24
+Important: the header declares `imageContent` as `HANDLE`, not `void*`.
25
+
26
+Example:
27
+
28
+```c
29
+HANDLE imageContent = CreateFileW(
30
+ L"C:\\images\\demo-import.tar",
31
+ GENERIC_READ,
32
+ FILE_SHARE_READ,
33
+ NULL,
34
+ OPEN_EXISTING,
35
+ FILE_ATTRIBUTE_NORMAL,
36
+ NULL);
37
+
38
+LARGE_INTEGER size = { 0 };
39
+GetFileSizeEx(imageContent, &size);
40
+
41
+WslcImportImageOptions importOptions = { 0 };
42
+HRESULT hr = WslcImportSessionImage(
43
+ session,
44
+ "demo/imported:latest",
45
+ imageContent,
46
+ (uint64_t)size.QuadPart,
47
+ &importOptions,
48
+ NULL);
49
+
50
+CloseHandle(imageContent);
51
+```
doc/docs/api-reference/c/image-apis/wslcimportsessionimagefromfile.md
new
+28
@@ -0,0 +1,28 @@
1
+# WslcImportSessionImageFromFile
2
+
3
+```c
4
+STDAPI WslcImportSessionImageFromFile(
5
+ _In_ WslcSession session, _In_z_ PCSTR imageName, _In_z_ PCWSTR path, _In_opt_ const WslcImportImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
6
+```
7
+
8
+| Parameter | Type | Direction |
9
+|---|---|---|
10
+| `session` | `WslcSession` | in |
11
+| `imageName` | `PCSTR` | in |
12
+| `path` | `PCWSTR` | in |
13
+| `options` | `const WslcImportImageOptions*` | in, optional |
14
+| `errorMessage` | `PWSTR*` | out, optional |
15
+
16
+Return value: `HRESULT`.
17
+
18
+Example:
19
+
20
+```c
21
+WslcImportImageOptions importOptions = { 0 };
22
+HRESULT hr = WslcImportSessionImageFromFile(
23
+ session,
24
+ "demo/imported:latest",
25
+ L"C:\\images\\demo-import.tar",
26
+ &importOptions,
27
+ NULL);
28
+```
doc/docs/api-reference/c/image-apis/wslclistsessionimages.md
new
+32
@@ -0,0 +1,32 @@
1
+# WslcListSessionImages
2
+
3
+```c
4
+STDAPI WslcListSessionImages(_In_ WslcSession session, _Outptr_result_buffer_(*count) WslcImageInfo** images, _Out_ uint32_t* count);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `images` | `WslcImageInfo**` | out |
11
+| `count` | `uint32_t*` | out |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Header note: `images` is allocated using `CoTaskMemAlloc`; free it with `CoTaskMemFree`.
16
+
17
+Example:
18
+
19
+```c
20
+WslcImageInfo* images = NULL;
21
+uint32_t count = 0;
22
+HRESULT hr = WslcListSessionImages(session, &images, &count);
23
+
24
+if (SUCCEEDED(hr))
25
+{
26
+ for (uint32_t i = 0; i < count; ++i)
27
+ {
28
+ printf("%s\n", images[i].name);
29
+ }
30
+ CoTaskMemFree(images);
31
+}
32
+```
doc/docs/api-reference/c/image-apis/wslcloadsessionimage.md
new
+48
@@ -0,0 +1,48 @@
1
+# WslcLoadSessionImage
2
+
3
+```c
4
+STDAPI WslcLoadSessionImage(
5
+ _In_ WslcSession session,
6
+ _In_ HANDLE imageContent,
7
+ _In_ uint64_t imageContentBytes,
8
+ _In_opt_ const WslcLoadImageOptions* options,
9
+ _Outptr_opt_result_z_ PWSTR* errorMessage);
10
+```
11
+
12
+| Parameter | Type | Direction |
13
+|---|---|---|
14
+| `session` | `WslcSession` | in |
15
+| `imageContent` | `HANDLE` | in |
16
+| `imageContentBytes` | `uint64_t` | in |
17
+| `options` | `const WslcLoadImageOptions*` | in, optional |
18
+| `errorMessage` | `PWSTR*` | out, optional |
19
+
20
+Return value: `HRESULT`.
21
+
22
+Important: the header declares `imageContent` as `HANDLE`, not `void*`.
23
+
24
+Example:
25
+
26
+```c
27
+HANDLE imageContent = CreateFileW(
28
+ L"C:\\images\\demo-load.tar",
29
+ GENERIC_READ,
30
+ FILE_SHARE_READ,
31
+ NULL,
32
+ OPEN_EXISTING,
33
+ FILE_ATTRIBUTE_NORMAL,
34
+ NULL);
35
+
36
+LARGE_INTEGER size = { 0 };
37
+GetFileSizeEx(imageContent, &size);
38
+
39
+WslcLoadImageOptions loadOptions = { 0 };
40
+HRESULT hr = WslcLoadSessionImage(
41
+ session,
42
+ imageContent,
43
+ (uint64_t)size.QuadPart,
44
+ &loadOptions,
45
+ NULL);
46
+
47
+CloseHandle(imageContent);
48
+```
doc/docs/api-reference/c/image-apis/wslcloadsessionimagefromfile.md
new
+26
@@ -0,0 +1,26 @@
1
+# WslcLoadSessionImageFromFile
2
+
3
+```c
4
+STDAPI WslcLoadSessionImageFromFile(
5
+ _In_ WslcSession session, _In_z_ PCWSTR path, _In_opt_ const WslcLoadImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
6
+```
7
+
8
+| Parameter | Type | Direction |
9
+|---|---|---|
10
+| `session` | `WslcSession` | in |
11
+| `path` | `PCWSTR` | in |
12
+| `options` | `const WslcLoadImageOptions*` | in, optional |
13
+| `errorMessage` | `PWSTR*` | out, optional |
14
+
15
+Return value: `HRESULT`.
16
+
17
+Example:
18
+
19
+```c
20
+WslcLoadImageOptions loadOptions = { 0 };
21
+HRESULT hr = WslcLoadSessionImageFromFile(
22
+ session,
23
+ L"C:\\images\\demo-load.tar",
24
+ &loadOptions,
25
+ NULL);
26
+```
doc/docs/api-reference/c/image-apis/wslcpullsessionimage.md
new
+35
@@ -0,0 +1,35 @@
1
+# WslcPullSessionImage
2
+
3
+```c
4
+STDAPI WslcPullSessionImage(_In_ WslcSession session, _In_ const WslcPullImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `options` | `const WslcPullImageOptions*` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HRESULT CALLBACK OnImageProgress(const WslcImageProgressMessage* progress, PVOID context)
19
+{
20
+ UNREFERENCED_PARAMETER(context);
21
+ printf("%s %llu/%llu\n",
22
+ progress->id,
23
+ (unsigned long long)progress->detail.currentBytes,
24
+ (unsigned long long)progress->detail.totalBytes);
25
+ return S_OK;
26
+}
27
+
28
+WslcPullImageOptions pullOptions = { 0 };
29
+pullOptions.uri = "docker.io/library/alpine:latest";
30
+pullOptions.progressCallback = OnImageProgress;
31
+pullOptions.progressCallbackContext = NULL;
32
+pullOptions.registryAuth = NULL;
33
+
34
+HRESULT hr = WslcPullSessionImage(session, &pullOptions, NULL);
35
+```
doc/docs/api-reference/c/image-apis/wslcpushsessionimage.md
new
+27
@@ -0,0 +1,27 @@
1
+# WslcPushSessionImage
2
+
3
+```c
4
+STDAPI WslcPushSessionImage(_In_ WslcSession session, _In_ const WslcPushImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `options` | `const WslcPushImageOptions*` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+WslcPushImageOptions pushOptions = { 0 };
19
+pushOptions.image = "demo/alpine:stable";
20
+pushOptions.registryAuth = "BASE64_X_REGISTRY_AUTH";
21
+pushOptions.progressCallback = OnImageProgress;
22
+pushOptions.progressCallbackContext = NULL;
23
+
24
+HRESULT hr = WslcPushSessionImage(session, &pushOptions, NULL);
25
+```
26
+
27
+---
doc/docs/api-reference/c/image-apis/wslctagsessionimage.md
new
+24
@@ -0,0 +1,24 @@
1
+# WslcTagSessionImage
2
+
3
+```c
4
+STDAPI WslcTagSessionImage(_In_ WslcSession session, _In_ const WslcTagImageOptions* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `options` | `const WslcTagImageOptions*` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+WslcTagImageOptions tagOptions = { 0 };
19
+tagOptions.image = "docker.io/library/alpine:latest";
20
+tagOptions.repo = "demo/alpine";
21
+tagOptions.tag = "stable";
22
+
23
+HRESULT hr = WslcTagSessionImage(session, &tagOptions, NULL);
24
+```
doc/docs/api-reference/c/index.md
new
+26
@@ -0,0 +1,26 @@
1
+# WSL container API C reference
2
+
3
+The WSL container API exposes a C API for creating sessions, creating containers inside those sessions, starting processes, managing images, managing VHD-backed storage, and checking/installing required platform components.
4
+
5
+> **Header:** `wslcsdk.h`
6
+>
7
+> **Library:** `wslcsdk.lib` / `wslcsdk.dll`
8
+>
9
+> **PREVIEW NOTICE:** This API is currently in preview and is subject to breaking changes in future releases without prior notice. Do not rely on API stability for production workloads. Features, function signatures, and behaviors may change between releases during the preview period.
10
+
11
+---
12
+
13
+## In this reference
14
+
15
+- [Structures](structures/index.md)
16
+- [Callback Types](callback-types/index.md)
17
+- [Session APIs](session-apis/index.md)
18
+- [Container APIs](container-apis/index.md)
19
+- [Process APIs](process-apis/index.md)
20
+- [Image APIs](image-apis/index.md)
21
+- [Storage APIs](storage-apis/index.md)
22
+- [Install and Version APIs](install-and-version-apis/index.md)
23
+- [Enumerations](enumerations/index.md)
24
+- [Error Codes](error-codes.md)
25
+- [Not Yet Implemented APIs](not-yet-implemented-apis.md)
26
+- [End-to-End Example](end-to-end-example.md)
doc/docs/api-reference/c/install-and-version-apis/.pages
new
+6
@@ -0,0 +1,6 @@
1
+title: Install and Version APIs
2
+nav:
3
+ - index.md
4
+ - wslcgetmissingcomponents.md
5
+ - wslcgetversion.md
6
+ - wslcinstallwithdependencies.md
doc/docs/api-reference/c/install-and-version-apis/index.md
new
+8
@@ -0,0 +1,8 @@
1
+# Install and Version APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcGetMissingComponents](wslcgetmissingcomponents.md)
7
+- [WslcGetVersion](wslcgetversion.md)
8
+- [WslcInstallWithDependencies](wslcinstallwithdependencies.md)
doc/docs/api-reference/c/install-and-version-apis/wslcgetmissingcomponents.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcGetMissingComponents
2
+
3
+```c
4
+STDAPI WslcGetMissingComponents(_Out_ WslcComponentFlags* missingComponents);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `missingComponents` | `WslcComponentFlags*` | out |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+WslcComponentFlags missingComponents = WSLC_COMPONENT_FLAG_NONE;
17
+HRESULT hr = WslcGetMissingComponents(&missingComponents);
18
+```
doc/docs/api-reference/c/install-and-version-apis/wslcgetversion.md
new
+22
@@ -0,0 +1,22 @@
1
+# WslcGetVersion
2
+
3
+```c
4
+STDAPI WslcGetVersion(_Out_writes_(1) WslcVersion* version);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `version` | `WslcVersion*` | out |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+WslcVersion version = { 0 };
17
+HRESULT hr = WslcGetVersion(&version);
18
+if (SUCCEEDED(hr))
19
+{
20
+ printf("%u.%u.%u\n", version.major, version.minor, version.revision);
21
+}
22
+```
doc/docs/api-reference/c/install-and-version-apis/wslcinstallwithdependencies.md
new
+32
@@ -0,0 +1,32 @@
1
+# WslcInstallWithDependencies
2
+
3
+```c
4
+STDAPI WslcInstallWithDependencies(_In_opt_ WslcInstallCallback progressCallback, _In_opt_ PVOID context);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `progressCallback` | `WslcInstallCallback` | in, optional |
10
+| `context` | `PVOID` | in, optional |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Header note: callbacks are only made for components actively installed by this call. That list can be acquired beforehand with [`WslcGetMissingComponents`](wslcgetmissingcomponents.md).
15
+
16
+Example:
17
+
18
+```c
19
+void CALLBACK OnInstallProgress(
20
+ WslcComponentFlags component,
21
+ uint32_t progressSteps,
22
+ uint32_t totalSteps,
23
+ PVOID context)
24
+{
25
+ UNREFERENCED_PARAMETER(context);
26
+ printf("component=%u %u/%u\n", (unsigned)component, progressSteps, totalSteps);
27
+}
28
+
29
+HRESULT hr = WslcInstallWithDependencies(OnInstallProgress, NULL);
30
+```
31
+
32
+---
doc/docs/api-reference/c/not-yet-implemented-apis.md
new
+10
@@ -0,0 +1,10 @@
1
+# Not Yet Implemented APIs
2
+
3
+The following APIs or features are **not yet implemented** and will return **`E_NOTIMPL`** when called. This list is provided so callers can plan accordingly:
4
+
5
+| API / Feature | Details |
6
+|---|---|
7
+| **`WslcSetContainerSettingsPortMappings`** — UDP protocol | Only **TCP** (`WSLC_PORT_PROTOCOL_TCP`) is supported. Passing `WSLC_PORT_PROTOCOL_UDP` returns `E_NOTIMPL`. |
8
+| **`WslcCreateSessionVhdVolume`** / **`WslcSetSessionSettingsVhd`** — fixed VHD type | Only **dynamic** VHDs (`WSLC_VHD_TYPE_DYNAMIC`) are supported. Passing `WSLC_VHD_TYPE_FIXED` returns `E_NOTIMPL`. |
9
+
10
+---
doc/docs/api-reference/c/process-apis/.pages
new
+15
@@ -0,0 +1,15 @@
1
+title: Process APIs
2
+nav:
3
+ - index.md
4
+ - wslcinitprocesssettings.md
5
+ - wslcsetprocesssettingsworkingdirectory.md
6
+ - wslcsetprocesssettingscmdline.md
7
+ - wslcsetprocesssettingsenvvariables.md
8
+ - wslcsetprocesssettingscallbacks.md
9
+ - wslcgetprocesspid.md
10
+ - wslcgetprocessexitevent.md
11
+ - wslcgetprocessstate.md
12
+ - wslcgetprocessexitcode.md
13
+ - wslcsignalprocess.md
14
+ - wslcgetprocessiohandle.md
15
+ - wslcreleaseprocess.md
doc/docs/api-reference/c/process-apis/index.md
new
+17
@@ -0,0 +1,17 @@
1
+# Process APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcInitProcessSettings](wslcinitprocesssettings.md)
7
+- [WslcSetProcessSettingsWorkingDirectory](wslcsetprocesssettingsworkingdirectory.md)
8
+- [WslcSetProcessSettingsCmdLine](wslcsetprocesssettingscmdline.md)
9
+- [WslcSetProcessSettingsEnvVariables](wslcsetprocesssettingsenvvariables.md)
10
+- [WslcSetProcessSettingsCallbacks](wslcsetprocesssettingscallbacks.md)
11
+- [WslcGetProcessPid](wslcgetprocesspid.md)
12
+- [WslcGetProcessExitEvent](wslcgetprocessexitevent.md)
13
+- [WslcGetProcessState](wslcgetprocessstate.md)
14
+- [WslcGetProcessExitCode](wslcgetprocessexitcode.md)
15
+- [WslcSignalProcess](wslcsignalprocess.md)
16
+- [WslcGetProcessIOHandle](wslcgetprocessiohandle.md)
17
+- [WslcReleaseProcess](wslcreleaseprocess.md)
doc/docs/api-reference/c/process-apis/wslcgetprocessexitcode.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetProcessExitCode
2
+
3
+```c
4
+STDAPI WslcGetProcessExitCode(_In_ WslcProcess process, _Out_ PINT32 exitCode);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `exitCode` | `PINT32` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+INT32 exitCode = 0;
18
+HRESULT hr = WslcGetProcessExitCode(process, &exitCode);
19
+```
doc/docs/api-reference/c/process-apis/wslcgetprocessexitevent.md
new
+23
@@ -0,0 +1,23 @@
1
+# WslcGetProcessExitEvent
2
+
3
+```c
4
+STDAPI WslcGetProcessExitEvent(_In_ WslcProcess process, _Out_ HANDLE* exitEvent);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `exitEvent` | `HANDLE*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HANDLE exitEvent = NULL;
18
+HRESULT hr = WslcGetProcessExitEvent(process, &exitEvent);
19
+if (SUCCEEDED(hr))
20
+{
21
+ WaitForSingleObject(exitEvent, INFINITE);
22
+}
23
+```
doc/docs/api-reference/c/process-apis/wslcgetprocessiohandle.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcGetProcessIOHandle
2
+
3
+```c
4
+STDAPI WslcGetProcessIOHandle(_In_ WslcProcess process, _In_ WslcProcessIOHandle ioHandle, _Out_ HANDLE* handle);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `ioHandle` | `WslcProcessIOHandle` | in |
11
+| `handle` | `HANDLE*` | out |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HANDLE stdoutHandle = NULL;
19
+HRESULT hr = WslcGetProcessIOHandle(process, WSLC_PROCESS_IO_HANDLE_STDOUT, &stdoutHandle);
20
+```
doc/docs/api-reference/c/process-apis/wslcgetprocesspid.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetProcessPid
2
+
3
+```c
4
+STDAPI WslcGetProcessPid(_In_ WslcProcess process, _Out_ uint32_t* pid);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `pid` | `uint32_t*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+uint32_t pid = 0;
18
+HRESULT hr = WslcGetProcessPid(process, &pid);
19
+```
doc/docs/api-reference/c/process-apis/wslcgetprocessstate.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetProcessState
2
+
3
+```c
4
+STDAPI WslcGetProcessState(_In_ WslcProcess process, _Out_ WslcProcessState* state);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `state` | `WslcProcessState*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcProcessState state = WSLC_PROCESS_STATE_UNKNOWN;
18
+HRESULT hr = WslcGetProcessState(process, &state);
19
+```
doc/docs/api-reference/c/process-apis/wslcinitprocesssettings.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcInitProcessSettings
2
+
3
+```c
4
+STDAPI WslcInitProcessSettings(_Out_ WslcProcessSettings* processSettings);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `processSettings` | `WslcProcessSettings*` | out |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+WslcProcessSettings processSettings;
17
+HRESULT hr = WslcInitProcessSettings(&processSettings);
18
+```
doc/docs/api-reference/c/process-apis/wslcreleaseprocess.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcReleaseProcess
2
+
3
+```c
4
+STDAPI WslcReleaseProcess(_In_ WslcProcess process);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+HRESULT hr = WslcReleaseProcess(process);
17
+process = NULL;
18
+```
19
+
20
+---
doc/docs/api-reference/c/process-apis/wslcsetprocesssettingscallbacks.md
new
+39
@@ -0,0 +1,39 @@
1
+# WslcSetProcessSettingsCallbacks
2
+
3
+```c
4
+STDAPI WslcSetProcessSettingsCallbacks(_In_ WslcProcessSettings* processSettings, _In_ const WslcProcessCallbacks* callbacks, _In_opt_ PVOID context);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `processSettings` | `WslcProcessSettings*` | in |
10
+| `callbacks` | `const WslcProcessCallbacks*` | in |
11
+| `context` | `PVOID` | in, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Header note: using callbacks consumes the process I/O handles and prevents later acquisition through `WslcGetProcessIOHandle`.
16
+
17
+Example:
18
+
19
+```c
20
+void CALLBACK OnStdOut(WslcProcessIOHandle ioHandle, const BYTE* data, uint32_t dataBytes, PVOID context)
21
+{
22
+ UNREFERENCED_PARAMETER(ioHandle);
23
+ UNREFERENCED_PARAMETER(context);
24
+ fwrite(data, 1, dataBytes, stdout);
25
+}
26
+
27
+void CALLBACK OnExit(INT32 exitCode, PVOID context)
28
+{
29
+ UNREFERENCED_PARAMETER(context);
30
+ printf("exit=%ld\n", (long)exitCode);
31
+}
32
+
33
+WslcProcessCallbacks callbacks = { 0 };
34
+callbacks.onStdOut = OnStdOut;
35
+callbacks.onStdErr = OnStdOut;
36
+callbacks.onExit = OnExit;
37
+
38
+HRESULT hr = WslcSetProcessSettingsCallbacks(&processSettings, &callbacks, NULL);
39
+```
doc/docs/api-reference/c/process-apis/wslcsetprocesssettingscmdline.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSetProcessSettingsCmdLine
2
+
3
+```c
4
+STDAPI WslcSetProcessSettingsCmdLine(_In_ WslcProcessSettings* processSettings, _In_reads_(argc) PCSTR const* argv, size_t argc);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `processSettings` | `WslcProcessSettings*` | in |
10
+| `argv` | `PCSTR const*` | in |
11
+| `argc` | `size_t` | in |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+PCSTR const argv[] = { "/bin/sh", "-c", "echo ready" };
19
+HRESULT hr = WslcSetProcessSettingsCmdLine(&processSettings, argv, _countof(argv));
20
+```
doc/docs/api-reference/c/process-apis/wslcsetprocesssettingsenvvariables.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSetProcessSettingsEnvVariables
2
+
3
+```c
4
+STDAPI WslcSetProcessSettingsEnvVariables(_In_ WslcProcessSettings* processSettings, _In_reads_(argc) PCSTR const* key_value, size_t argc);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `processSettings` | `WslcProcessSettings*` | in |
10
+| `key_value` | `PCSTR const*` | in |
11
+| `argc` | `size_t` | in |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+PCSTR const key_value[] = { "HOME=/root", "DEMO_FLAG=1" };
19
+HRESULT hr = WslcSetProcessSettingsEnvVariables(&processSettings, key_value, _countof(key_value));
20
+```
doc/docs/api-reference/c/process-apis/wslcsetprocesssettingsworkingdirectory.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetProcessSettingsWorkingDirectory
2
+
3
+```c
4
+STDAPI WslcSetProcessSettingsWorkingDirectory(_In_ WslcProcessSettings* processSettings, _In_ PCSTR workingDirectory);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `processSettings` | `WslcProcessSettings*` | in |
10
+| `workingDirectory` | `PCSTR` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetProcessSettingsWorkingDirectory(&processSettings, "/work");
18
+```
doc/docs/api-reference/c/process-apis/wslcsignalprocess.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSignalProcess
2
+
3
+```c
4
+STDAPI WslcSignalProcess(_In_ WslcProcess process, _In_ WslcSignal signal);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `process` | `WslcProcess` | in |
10
+| `signal` | `WslcSignal` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSignalProcess(process, WSLC_SIGNAL_SIGTERM);
18
+```
doc/docs/api-reference/c/session-apis/.pages
new
+17
@@ -0,0 +1,17 @@
1
+title: Session APIs
2
+nav:
3
+ - index.md
4
+ - wslcinitsessionsettings.md
5
+ - wslccreatesession.md
6
+ - wslcsetsessionsettingscpucount.md
7
+ - wslcsetsessionsettingsmemory.md
8
+ - wslcsetsessionsettingstimeout.md
9
+ - wslcsetsessionsettingsvhd.md
10
+ - wslcsetsessionsettingsfeatureflags.md
11
+ - wslcgetsessionterminationevent.md
12
+ - wslcgetsessionterminationreason.md
13
+ - wslcregistersessioncrashdumpcallback.md
14
+ - wslcreleasecrashdumpsubscription.md
15
+ - wslcterminatesession.md
16
+ - wslcreleasesession.md
17
+ - wslcsessionauthenticate.md
doc/docs/api-reference/c/session-apis/index.md
new
+19
@@ -0,0 +1,19 @@
1
+# Session APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcInitSessionSettings](wslcinitsessionsettings.md)
7
+- [WslcCreateSession](wslccreatesession.md)
8
+- [WslcSetSessionSettingsCpuCount](wslcsetsessionsettingscpucount.md)
9
+- [WslcSetSessionSettingsMemory](wslcsetsessionsettingsmemory.md)
10
+- [WslcSetSessionSettingsTimeout](wslcsetsessionsettingstimeout.md)
11
+- [WslcSetSessionSettingsVhd](wslcsetsessionsettingsvhd.md)
12
+- [WslcSetSessionSettingsFeatureFlags](wslcsetsessionsettingsfeatureflags.md)
13
+- [WslcGetSessionTerminationEvent](wslcgetsessionterminationevent.md)
14
+- [WslcGetSessionTerminationReason](wslcgetsessionterminationreason.md)
15
+- [WslcRegisterSessionCrashDumpCallback](wslcregistersessioncrashdumpcallback.md)
16
+- [WslcReleaseCrashDumpSubscription](wslcreleasecrashdumpsubscription.md)
17
+- [WslcTerminateSession](wslcterminatesession.md)
18
+- [WslcReleaseSession](wslcreleasesession.md)
19
+- [WslcSessionAuthenticate](wslcsessionauthenticate.md)
doc/docs/api-reference/c/session-apis/wslccreatesession.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcCreateSession
2
+
3
+```c
4
+STDAPI WslcCreateSession(_In_ WslcSessionSettings* sessionSettings, _Out_ WslcSession* session, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `session` | `WslcSession*` | out |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+WslcSession session = NULL;
19
+HRESULT hr = WslcCreateSession(&sessionSettings, &session, NULL);
20
+```
doc/docs/api-reference/c/session-apis/wslcgetsessionterminationevent.md
new
+23
@@ -0,0 +1,23 @@
1
+# WslcGetSessionTerminationEvent
2
+
3
+```c
4
+STDAPI WslcGetSessionTerminationEvent(_In_ WslcSession session, _Out_ HANDLE* terminationEvent);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `terminationEvent` | `HANDLE*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HANDLE terminationEvent = NULL;
18
+HRESULT hr = WslcGetSessionTerminationEvent(session, &terminationEvent);
19
+if (SUCCEEDED(hr))
20
+{
21
+ WaitForSingleObject(terminationEvent, 1000);
22
+}
23
+```
doc/docs/api-reference/c/session-apis/wslcgetsessionterminationreason.md
new
+19
@@ -0,0 +1,19 @@
1
+# WslcGetSessionTerminationReason
2
+
3
+```c
4
+STDAPI WslcGetSessionTerminationReason(_In_ WslcSession session, _Out_ WslcSessionTerminationReason* reason);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `reason` | `WslcSessionTerminationReason*` | out |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+WslcSessionTerminationReason reason = WSLC_SESSION_TERMINATION_REASON_UNKNOWN;
18
+HRESULT hr = WslcGetSessionTerminationReason(session, &reason);
19
+```
doc/docs/api-reference/c/session-apis/wslcinitsessionsettings.md
new
+23
@@ -0,0 +1,23 @@
1
+# WslcInitSessionSettings
2
+
3
+```c
4
+STDAPI WslcInitSessionSettings(_In_ PCWSTR name, _In_ PCWSTR storagePath, _Out_ WslcSessionSettings* sessionSettings);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `name` | `PCWSTR` | in |
10
+| `storagePath` | `PCWSTR` | in |
11
+| `sessionSettings` | `WslcSessionSettings*` | out |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+WslcSessionSettings sessionSettings;
19
+HRESULT hr = WslcInitSessionSettings(
20
+ L"demo-session",
21
+ L"C:\\WSLC\\demo-session",
22
+ &sessionSettings);
23
+```
doc/docs/api-reference/c/session-apis/wslcregistersessioncrashdumpcallback.md
new
+38
@@ -0,0 +1,38 @@
1
+# WslcRegisterSessionCrashDumpCallback
2
+
3
+```c
4
+STDAPI WslcRegisterSessionCrashDumpCallback(
5
+ _In_ WslcSession session,
6
+ _In_ WslcSessionCrashDumpCallback crashDumpCallback,
7
+ _In_opt_ PVOID crashDumpContext,
8
+ _Out_ WslcCrashDumpSubscription* subscription,
9
+ _Outptr_opt_result_z_ PWSTR* errorMessage);
10
+```
11
+
12
+| Parameter | Type | Direction |
13
+|---|---|---|
14
+| `session` | `WslcSession` | in |
15
+| `crashDumpCallback` | `WslcSessionCrashDumpCallback` | in |
16
+| `crashDumpContext` | `PVOID` | in, optional |
17
+| `subscription` | `WslcCrashDumpSubscription*` | out |
18
+| `errorMessage` | `PWSTR*` | out, optional |
19
+
20
+Return value: `HRESULT`.
21
+
22
+Example:
23
+
24
+```c
25
+void CALLBACK OnCrashDump(const WslcSessionCrashDumpInfo* info, PVOID context)
26
+{
27
+ UNREFERENCED_PARAMETER(context);
28
+ wprintf(L"dump=%ls\n", info->dumpPath);
29
+}
30
+
31
+WslcCrashDumpSubscription subscription = NULL;
32
+HRESULT hr = WslcRegisterSessionCrashDumpCallback(
33
+ session,
34
+ OnCrashDump,
35
+ NULL,
36
+ &subscription,
37
+ NULL);
38
+```
doc/docs/api-reference/c/session-apis/wslcreleasecrashdumpsubscription.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcReleaseCrashDumpSubscription
2
+
3
+```c
4
+STDAPI WslcReleaseCrashDumpSubscription(_In_ WslcCrashDumpSubscription subscription);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `subscription` | `WslcCrashDumpSubscription` | in |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+HRESULT hr = WslcReleaseCrashDumpSubscription(subscription);
17
+subscription = NULL;
18
+```
doc/docs/api-reference/c/session-apis/wslcreleasesession.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcReleaseSession
2
+
3
+```c
4
+STDAPI WslcReleaseSession(_In_ WslcSession session);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+HRESULT hr = WslcReleaseSession(session);
17
+session = NULL;
18
+```
doc/docs/api-reference/c/session-apis/wslcsessionauthenticate.md
new
+45
@@ -0,0 +1,45 @@
1
+# WslcSessionAuthenticate
2
+
3
+```c
4
+STDAPI WslcSessionAuthenticate(
5
+ _In_ WslcSession session,
6
+ _In_z_ PCSTR serverAddress,
7
+ _In_z_ PCSTR username,
8
+ _In_z_ PCSTR password,
9
+ _Outptr_result_z_ PSTR* identityToken,
10
+ _Outptr_opt_result_z_ PWSTR* errorMessage);
11
+```
12
+
13
+| Parameter | Type | Direction |
14
+|---|---|---|
15
+| `session` | `WslcSession` | in |
16
+| `serverAddress` | `PCSTR` | in |
17
+| `username` | `PCSTR` | in |
18
+| `password` | `PCSTR` | in |
19
+| `identityToken` | `PSTR*` | out |
20
+| `errorMessage` | `PWSTR*` | out, optional |
21
+
22
+Return value: `HRESULT`.
23
+
24
+Header note: `identityToken` is allocated using `CoTaskMemAlloc`; free it with `CoTaskMemFree`.
25
+
26
+Example:
27
+
28
+```c
29
+PSTR identityToken = NULL;
30
+HRESULT hr = WslcSessionAuthenticate(
31
+ session,
32
+ "127.0.0.1:5000",
33
+ "user",
34
+ "password",
35
+ &identityToken,
36
+ NULL);
37
+
38
+if (SUCCEEDED(hr))
39
+{
40
+ printf("token=%s\n", identityToken);
41
+ CoTaskMemFree(identityToken);
42
+}
43
+```
44
+
45
+---
doc/docs/api-reference/c/session-apis/wslcsetsessionsettingscpucount.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetSessionSettingsCpuCount
2
+
3
+```c
4
+STDAPI WslcSetSessionSettingsCpuCount(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t cpuCount);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `cpuCount` | `uint32_t` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetSessionSettingsCpuCount(&sessionSettings, (uint32_t)4);
18
+```
doc/docs/api-reference/c/session-apis/wslcsetsessionsettingsfeatureflags.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSetSessionSettingsFeatureFlags
2
+
3
+```c
4
+STDAPI WslcSetSessionSettingsFeatureFlags(_In_ WslcSessionSettings* sessionSettings, _In_ WslcSessionFeatureFlags flags);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `flags` | `WslcSessionFeatureFlags` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetSessionSettingsFeatureFlags(
18
+ &sessionSettings,
19
+ WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU);
20
+```
doc/docs/api-reference/c/session-apis/wslcsetsessionsettingsmemory.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetSessionSettingsMemory
2
+
3
+```c
4
+STDAPI WslcSetSessionSettingsMemory(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t memoryMB);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `memoryMB` | `uint32_t` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetSessionSettingsMemory(&sessionSettings, (uint32_t)4096);
18
+```
doc/docs/api-reference/c/session-apis/wslcsetsessionsettingstimeout.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcSetSessionSettingsTimeout
2
+
3
+```c
4
+STDAPI WslcSetSessionSettingsTimeout(_In_ WslcSessionSettings* sessionSettings, _In_ uint32_t timeoutMS);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `timeoutMS` | `uint32_t` | in |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Example:
15
+
16
+```c
17
+HRESULT hr = WslcSetSessionSettingsTimeout(&sessionSettings, (uint32_t)120000);
18
+```
doc/docs/api-reference/c/session-apis/wslcsetsessionsettingsvhd.md
new
+31
@@ -0,0 +1,31 @@
1
+# WslcSetSessionSettingsVhd
2
+
3
+```c
4
+STDAPI WslcSetSessionSettingsVhd(_In_ WslcSessionSettings* sessionSettings, _In_opt_ const WslcVhdRequirements* vhdRequirements);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `sessionSettings` | `WslcSessionSettings*` | in |
10
+| `vhdRequirements` | `const WslcVhdRequirements*` | in, optional |
11
+
12
+Return value: `HRESULT`.
13
+
14
+Header notes:
15
+
16
+- `WslcSetSessionSettingsVhd` rejects non-`NONE` flags with `E_INVALIDARG`.
17
+- `WSLC_VHD_TYPE_FIXED` is only honored by `WslcCreateSessionVhdVolume`.
18
+
19
+Example:
20
+
21
+```c
22
+WslcVhdRequirements vhdRequirements = { 0 };
23
+vhdRequirements.name = "ignored-by-WslcSetSessionSettingsVhd";
24
+vhdRequirements.sizeBytes = (uint64_t)64 * 1024 * 1024 * 1024;
25
+vhdRequirements.type = WSLC_VHD_TYPE_DYNAMIC;
26
+vhdRequirements.flags = WSLC_VHD_REQ_FLAG_NONE;
27
+vhdRequirements.uid = (uint32_t)0;
28
+vhdRequirements.gid = (uint32_t)0;
29
+
30
+HRESULT hr = WslcSetSessionSettingsVhd(&sessionSettings, &vhdRequirements);
31
+```
doc/docs/api-reference/c/session-apis/wslcterminatesession.md
new
+17
@@ -0,0 +1,17 @@
1
+# WslcTerminateSession
2
+
3
+```c
4
+STDAPI WslcTerminateSession(_In_ WslcSession session);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+
11
+Return value: `HRESULT`.
12
+
13
+Example:
14
+
15
+```c
16
+HRESULT hr = WslcTerminateSession(session);
17
+```
doc/docs/api-reference/c/storage-apis/.pages
new
+5
@@ -0,0 +1,5 @@
1
+title: Storage APIs
2
+nav:
3
+ - index.md
4
+ - wslccreatesessionvhdvolume.md
5
+ - wslcdeletesessionvhdvolume.md
doc/docs/api-reference/c/storage-apis/index.md
new
+7
@@ -0,0 +1,7 @@
1
+# Storage APIs
2
+
3
+
4
+## Members
5
+
6
+- [WslcCreateSessionVhdVolume](wslccreatesessionvhdvolume.md)
7
+- [WslcDeleteSessionVhdVolume](wslcdeletesessionvhdvolume.md)
doc/docs/api-reference/c/storage-apis/wslccreatesessionvhdvolume.md
new
+32
@@ -0,0 +1,32 @@
1
+# WslcCreateSessionVhdVolume
2
+
3
+```c
4
+STDAPI WslcCreateSessionVhdVolume(_In_ WslcSession session, _In_ const WslcVhdRequirements* options, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `options` | `const WslcVhdRequirements*` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Header notes:
16
+
17
+- `WSLC_VHD_TYPE_FIXED` is only honored by `WslcCreateSessionVhdVolume`.
18
+- `uid` and `gid` are honored iff `flags & WSLC_VHD_REQ_FLAG_OWNER`.
19
+
20
+Example:
21
+
22
+```c
23
+WslcVhdRequirements options = { 0 };
24
+options.name = "cache";
25
+options.sizeBytes = (uint64_t)8 * 1024 * 1024 * 1024;
26
+options.type = WSLC_VHD_TYPE_DYNAMIC;
27
+options.flags = WSLC_VHD_REQ_FLAG_OWNER;
28
+options.uid = (uint32_t)1000;
29
+options.gid = (uint32_t)1000;
30
+
31
+HRESULT hr = WslcCreateSessionVhdVolume(session, &options, NULL);
32
+```
doc/docs/api-reference/c/storage-apis/wslcdeletesessionvhdvolume.md
new
+21
@@ -0,0 +1,21 @@
1
+# WslcDeleteSessionVhdVolume
2
+
3
+```c
4
+STDAPI WslcDeleteSessionVhdVolume(_In_ WslcSession session, _In_z_ PCSTR name, _Outptr_opt_result_z_ PWSTR* errorMessage);
5
+```
6
+
7
+| Parameter | Type | Direction |
8
+|---|---|---|
9
+| `session` | `WslcSession` | in |
10
+| `name` | `PCSTR` | in |
11
+| `errorMessage` | `PWSTR*` | out, optional |
12
+
13
+Return value: `HRESULT`.
14
+
15
+Example:
16
+
17
+```c
18
+HRESULT hr = WslcDeleteSessionVhdVolume(session, "cache", NULL);
19
+```
20
+
21
+---
doc/docs/api-reference/c/structures/.pages
new
+23
@@ -0,0 +1,23 @@
1
+title: Structures
2
+nav:
3
+ - index.md
4
+ - handle-types.md
5
+ - constants.md
6
+ - wslcsessionsettings.md
7
+ - wslccontainersettings.md
8
+ - wslcprocesssettings.md
9
+ - wslcvhdrequirements.md
10
+ - wslcsessioncrashdumpinfo.md
11
+ - wslccontainerportmapping.md
12
+ - wslccontainervolume.md
13
+ - wslccontainernamedvolume.md
14
+ - wslcprocesscallbacks.md
15
+ - wslcimageprogressdetail.md
16
+ - wslcimageprogressmessage.md
17
+ - wslcpullimageoptions.md
18
+ - wslcimportimageoptions.md
19
+ - wslcloadimageoptions.md
20
+ - wslcimageinfo.md
21
+ - wslctagimageoptions.md
22
+ - wslcpushimageoptions.md
23
+ - wslcversion.md
doc/docs/api-reference/c/structures/constants.md
new
+23
@@ -0,0 +1,23 @@
1
+# Constants
2
+
3
+```c
4
+#define WSLC_SESSION_OPTIONS_SIZE 72
5
+#define WSLC_SESSION_OPTIONS_ALIGNMENT 8
6
+#define WSLC_CONTAINER_OPTIONS_SIZE 104
7
+#define WSLC_CONTAINER_OPTIONS_ALIGNMENT 8
8
+#define WSLC_CONTAINER_PROCESS_OPTIONS_SIZE 72
9
+#define WSLC_CONTAINER_PROCESS_OPTIONS_ALIGNMENT 8
10
+#define WSLC_CONTAINER_ID_BUFFER_SIZE 65
11
+#define WSLC_IMAGE_NAME_LENGTH 256
12
+```
13
+
14
+| Constant | Value |
15
+|---|---|
16
+| `WSLC_SESSION_OPTIONS_SIZE` | `72` |
17
+| `WSLC_SESSION_OPTIONS_ALIGNMENT` | `8` |
18
+| `WSLC_CONTAINER_OPTIONS_SIZE` | `104` |
19
+| `WSLC_CONTAINER_OPTIONS_ALIGNMENT` | `8` |
20
+| `WSLC_CONTAINER_PROCESS_OPTIONS_SIZE` | `72` |
21
+| `WSLC_CONTAINER_PROCESS_OPTIONS_ALIGNMENT` | `8` |
22
+| `WSLC_CONTAINER_ID_BUFFER_SIZE` | `65` |
23
+| `WSLC_IMAGE_NAME_LENGTH` | `256` |
doc/docs/api-reference/c/structures/handle-types.md
new
+10
@@ -0,0 +1,10 @@
1
+# Handle Types
2
+
3
+The header declares these opaque handles:
4
+
5
+```c
6
+DECLARE_HANDLE(WslcSession);
7
+DECLARE_HANDLE(WslcContainer);
8
+DECLARE_HANDLE(WslcProcess);
9
+DECLARE_HANDLE(WslcCrashDumpSubscription);
10
+```
doc/docs/api-reference/c/structures/index.md
new
+25
@@ -0,0 +1,25 @@
1
+# Structures
2
+
3
+
4
+## Members
5
+
6
+- [Handle Types](handle-types.md)
7
+- [Constants](constants.md)
8
+- [WslcSessionSettings](wslcsessionsettings.md)
9
+- [WslcContainerSettings](wslccontainersettings.md)
10
+- [WslcProcessSettings](wslcprocesssettings.md)
11
+- [WslcVhdRequirements](wslcvhdrequirements.md)
12
+- [WslcSessionCrashDumpInfo](wslcsessioncrashdumpinfo.md)
13
+- [WslcContainerPortMapping](wslccontainerportmapping.md)
14
+- [WslcContainerVolume](wslccontainervolume.md)
15
+- [WslcContainerNamedVolume](wslccontainernamedvolume.md)
16
+- [WslcProcessCallbacks](wslcprocesscallbacks.md)
17
+- [WslcImageProgressDetail](wslcimageprogressdetail.md)
18
+- [WslcImageProgressMessage](wslcimageprogressmessage.md)
19
+- [WslcPullImageOptions](wslcpullimageoptions.md)
20
+- [WslcImportImageOptions](wslcimportimageoptions.md)
21
+- [WslcLoadImageOptions](wslcloadimageoptions.md)
22
+- [WslcImageInfo](wslcimageinfo.md)
23
+- [WslcTagImageOptions](wslctagimageoptions.md)
24
+- [WslcPushImageOptions](wslcpushimageoptions.md)
25
+- [WslcVersion](wslcversion.md)
doc/docs/api-reference/c/structures/wslccontainernamedvolume.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcContainerNamedVolume
2
+
3
+```c
4
+typedef struct WslcContainerNamedVolume
5
+{
6
+ _In_z_ PCSTR name; // Name of the session volume (from WslcVhdRequirements.name)
7
+ _In_z_ PCSTR containerPath; // Absolute path inside the container
8
+ _In_ BOOL readOnly;
9
+} WslcContainerNamedVolume;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `name` | `PCSTR` |
15
+| `containerPath` | `PCSTR` |
16
+| `readOnly` | `BOOL` |
doc/docs/api-reference/c/structures/wslccontainerportmapping.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcContainerPortMapping
2
+
3
+```c
4
+typedef struct WslcContainerPortMapping
5
+{
6
+ _In_ uint16_t windowsPort; // Port on Windows host
7
+ _In_ uint16_t containerPort; // Port inside container
8
+ _In_ WslcPortProtocol protocol; // TCP or UDP
9
+
10
+ // if you want to override the default binding address
11
+ _In_opt_ struct sockaddr_storage* windowsAddress; // accepts ipv4/6
12
+} WslcContainerPortMapping;
13
+```
14
+
15
+| Field | Type |
16
+|---|---|
17
+| `windowsPort` | `uint16_t` |
18
+| `containerPort` | `uint16_t` |
19
+| `protocol` | `WslcPortProtocol` |
20
+| `windowsAddress` | `struct sockaddr_storage*` |
doc/docs/api-reference/c/structures/wslccontainersettings.md
new
+8
@@ -0,0 +1,8 @@
1
+# WslcContainerSettings
2
+
3
+```c
4
+typedef struct WslcContainerSettings
5
+{
6
+ __declspec(align(WSLC_CONTAINER_OPTIONS_ALIGNMENT)) BYTE _opaque[WSLC_CONTAINER_OPTIONS_SIZE];
7
+} WslcContainerSettings;
8
+```
doc/docs/api-reference/c/structures/wslccontainervolume.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcContainerVolume
2
+
3
+```c
4
+typedef struct WslcContainerVolume
5
+{
6
+ _In_z_ PCWSTR windowsPath;
7
+ _In_z_ PCSTR containerPath;
8
+ _In_ BOOL readOnly;
9
+} WslcContainerVolume;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `windowsPath` | `PCWSTR` |
15
+| `containerPath` | `PCSTR` |
16
+| `readOnly` | `BOOL` |
doc/docs/api-reference/c/structures/wslcimageinfo.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcImageInfo
2
+
3
+```c
4
+typedef struct WslcImageInfo
5
+{
6
+ CHAR name[WSLC_IMAGE_NAME_LENGTH];
7
+ uint8_t sha256[32];
8
+ int64_t sizeBytes;
9
+ uint64_t createdUnixTime;
10
+} WslcImageInfo;
11
+```
12
+
13
+| Field | Type |
14
+|---|---|
15
+| `name` | `CHAR[WSLC_IMAGE_NAME_LENGTH]` |
16
+| `sha256` | `uint8_t[32]` |
17
+| `sizeBytes` | `int64_t` |
18
+| `createdUnixTime` | `uint64_t` |
doc/docs/api-reference/c/structures/wslcimageprogressdetail.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcImageProgressDetail
2
+
3
+```c
4
+typedef struct WslcImageProgressDetail
5
+{
6
+ _Out_ uint64_t currentBytes; // bytes downloaded so far
7
+ _Out_ uint64_t totalBytes; // total bytes expected
8
+} WslcImageProgressDetail;
9
+```
10
+
11
+| Field | Type |
12
+|---|---|
13
+| `currentBytes` | `uint64_t` |
14
+| `totalBytes` | `uint64_t` |
doc/docs/api-reference/c/structures/wslcimageprogressmessage.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcImageProgressMessage
2
+
3
+```c
4
+typedef struct WslcImageProgressMessage
5
+{
6
+ _Out_ PCSTR id; // layer ID or digest
7
+ _Out_ WslcImageProgressStatus status; // "Downloading", "Extracting", etc.
8
+ _Out_ WslcImageProgressDetail detail;
9
+} WslcImageProgressMessage;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `id` | `PCSTR` |
15
+| `status` | `WslcImageProgressStatus` |
16
+| `detail` | `WslcImageProgressDetail` |
doc/docs/api-reference/c/structures/wslcimportimageoptions.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcImportImageOptions
2
+
3
+```c
4
+typedef struct WslcImportImageOptions
5
+{
6
+ _In_opt_ WslcContainerImageProgressCallback progressCallback;
7
+ _In_opt_ PVOID progressCallbackContext;
8
+} WslcImportImageOptions;
9
+```
10
+
11
+| Field | Type |
12
+|---|---|
13
+| `progressCallback` | `WslcContainerImageProgressCallback` |
14
+| `progressCallbackContext` | `PVOID` |
doc/docs/api-reference/c/structures/wslcloadimageoptions.md
new
+14
@@ -0,0 +1,14 @@
1
+# WslcLoadImageOptions
2
+
3
+```c
4
+typedef struct WslcLoadImageOptions
5
+{
6
+ _In_opt_ WslcContainerImageProgressCallback progressCallback;
7
+ _In_opt_ PVOID progressCallbackContext;
8
+} WslcLoadImageOptions;
9
+```
10
+
11
+| Field | Type |
12
+|---|---|
13
+| `progressCallback` | `WslcContainerImageProgressCallback` |
14
+| `progressCallbackContext` | `PVOID` |
doc/docs/api-reference/c/structures/wslcprocesscallbacks.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcProcessCallbacks
2
+
3
+```c
4
+typedef struct WslcProcessCallbacks
5
+{
6
+ WslcStdIOCallback onStdOut;
7
+ WslcStdIOCallback onStdErr;
8
+ WslcProcessExitCallback onExit;
9
+} WslcProcessCallbacks;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `onStdOut` | `WslcStdIOCallback` |
15
+| `onStdErr` | `WslcStdIOCallback` |
16
+| `onExit` | `WslcProcessExitCallback` |
doc/docs/api-reference/c/structures/wslcprocesssettings.md
new
+8
@@ -0,0 +1,8 @@
1
+# WslcProcessSettings
2
+
3
+```c
4
+typedef struct WslcProcessSettings
5
+{
6
+ __declspec(align(WSLC_CONTAINER_PROCESS_OPTIONS_ALIGNMENT)) BYTE _opaque[WSLC_CONTAINER_PROCESS_OPTIONS_SIZE];
7
+} WslcProcessSettings;
8
+```
doc/docs/api-reference/c/structures/wslcpullimageoptions.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcPullImageOptions
2
+
3
+```c
4
+typedef struct WslcPullImageOptions
5
+{
6
+ _In_z_ PCSTR uri;
7
+ WslcContainerImageProgressCallback progressCallback;
8
+ PVOID progressCallbackContext;
9
+ _In_opt_z_ PCSTR registryAuth;
10
+} WslcPullImageOptions;
11
+```
12
+
13
+| Field | Type |
14
+|---|---|
15
+| `uri` | `PCSTR` |
16
+| `progressCallback` | `WslcContainerImageProgressCallback` |
17
+| `progressCallbackContext` | `PVOID` |
18
+| `registryAuth` | `PCSTR` |
doc/docs/api-reference/c/structures/wslcpushimageoptions.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcPushImageOptions
2
+
3
+```c
4
+typedef struct WslcPushImageOptions
5
+{
6
+ _In_z_ PCSTR image;
7
+ _In_z_ PCSTR registryAuth; // Base64-encoded X-Registry-Auth header value.
8
+ _In_opt_ WslcContainerImageProgressCallback progressCallback;
9
+ _In_opt_ PVOID progressCallbackContext;
10
+} WslcPushImageOptions;
11
+```
12
+
13
+| Field | Type |
14
+|---|---|
15
+| `image` | `PCSTR` |
16
+| `registryAuth` | `PCSTR` |
17
+| `progressCallback` | `WslcContainerImageProgressCallback` |
18
+| `progressCallbackContext` | `PVOID` |
doc/docs/api-reference/c/structures/wslcsessioncrashdumpinfo.md
new
+20
@@ -0,0 +1,20 @@
1
+# WslcSessionCrashDumpInfo
2
+
3
+```c
4
+typedef struct WslcSessionCrashDumpInfo
5
+{
6
+ _Field_z_ PCWSTR dumpPath;
7
+ _Field_z_ PCSTR processName;
8
+ uint32_t pid;
9
+ uint32_t signal;
10
+ uint64_t timestamp;
11
+} WslcSessionCrashDumpInfo;
12
+```
13
+
14
+| Field | Type |
15
+|---|---|
16
+| `dumpPath` | `PCWSTR` |
17
+| `processName` | `PCSTR` |
18
+| `pid` | `uint32_t` |
19
+| `signal` | `uint32_t` |
20
+| `timestamp` | `uint64_t` |
doc/docs/api-reference/c/structures/wslcsessionsettings.md
new
+8
@@ -0,0 +1,8 @@
1
+# WslcSessionSettings
2
+
3
+```c
4
+typedef struct WslcSessionSettings
5
+{
6
+ __declspec(align(WSLC_SESSION_OPTIONS_ALIGNMENT)) BYTE _opaque[WSLC_SESSION_OPTIONS_SIZE];
7
+} WslcSessionSettings;
8
+```
doc/docs/api-reference/c/structures/wslctagimageoptions.md
new
+16
@@ -0,0 +1,16 @@
1
+# WslcTagImageOptions
2
+
3
+```c
4
+typedef struct WslcTagImageOptions
5
+{
6
+ _In_z_ PCSTR image; // Source image name or ID.
7
+ _In_z_ PCSTR repo; // Target repository name.
8
+ _In_z_ PCSTR tag; // Target tag name.
9
+} WslcTagImageOptions;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `image` | `PCSTR` |
15
+| `repo` | `PCSTR` |
16
+| `tag` | `PCSTR` |
doc/docs/api-reference/c/structures/wslcversion.md
new
+18
@@ -0,0 +1,18 @@
1
+# WslcVersion
2
+
3
+```c
4
+typedef struct WslcVersion
5
+{
6
+ uint32_t major;
7
+ uint32_t minor;
8
+ uint32_t revision;
9
+} WslcVersion;
10
+```
11
+
12
+| Field | Type |
13
+|---|---|
14
+| `major` | `uint32_t` |
15
+| `minor` | `uint32_t` |
16
+| `revision` | `uint32_t` |
17
+
18
+---
doc/docs/api-reference/c/structures/wslcvhdrequirements.md
new
+28
@@ -0,0 +1,28 @@
1
+# WslcVhdRequirements
2
+
3
+```c
4
+typedef struct WslcVhdRequirements
5
+{
6
+ _In_z_ PCSTR name;
7
+ _In_ uint64_t sizeBytes; // Desired size (for create/expand)
8
+ _In_ WslcVhdType type;
9
+ _In_ WslcVhdRequirementsFlags flags;
10
+ _In_ uint32_t uid; // honored iff (flags & WSLC_VHD_REQ_FLAG_OWNER)
11
+ _In_ uint32_t gid; // honored iff (flags & WSLC_VHD_REQ_FLAG_OWNER)
12
+} WslcVhdRequirements;
13
+```
14
+
15
+| Field | Type |
16
+|---|---|
17
+| `name` | `PCSTR` |
18
+| `sizeBytes` | `uint64_t` |
19
+| `type` | `WslcVhdType` |
20
+| `flags` | `WslcVhdRequirementsFlags` |
21
+| `uid` | `uint32_t` |
22
+| `gid` | `uint32_t` |
23
+
24
+Header notes:
25
+
26
+- `name` is ignored by `WslcSetSessionSettingsVhd`.
27
+- The remaining fields after `type` are only honored by `WslcCreateSessionVhdVolume`.
28
+- `WslcSetSessionSettingsVhd` rejects non-`NONE` flags with `E_INVALIDARG`.
doc/docs/api-reference/cpp/.pages
new
+11
@@ -0,0 +1,11 @@
1
+title: C++ API reference
2
+nav:
3
+ - index.md
4
+ - data-classes
5
+ - settings-classes
6
+ - core-classes
7
+ - service-class
8
+ - delegates-and-events
9
+ - enumerations
10
+ - not-yet-implemented-and-known-gaps.md
11
+ - end-to-end-example.md
doc/docs/api-reference/cpp/core-classes/.pages
new
+6
@@ -0,0 +1,6 @@
1
+title: Core Classes
2
+nav:
3
+ - index.md
4
+ - session.md
5
+ - container.md
6
+ - process.md
doc/docs/api-reference/cpp/core-classes/container.md
new
+45
@@ -0,0 +1,45 @@
1
+# Container
2
+
3
+**Methods**
4
+- `Start()`
5
+- `Stop(Signal signal, TimeSpan timeout)`
6
+- `Delete(DeleteContainerOption options)`
7
+- `CreateProcess(ProcessSettings newProcessSettings)`
8
+- `Inspect()`
9
+- `Id()`
10
+- `InitProcess()`
11
+- `State()`
12
+- `Close()`
13
+
14
+**Behavior notes**
15
+- `Start()` automatically sets `WSLC_CONTAINER_START_FLAG_ATTACH` if an init process exists and its output mode is `Event` or `Stream`.
16
+- `Stop()` converts the timeout to **seconds**, rejects negative values, and rejects values that exceed `uint32_t`.
17
+- `InitProcess()` throws if the container was not configured with one.
18
+
19
+**Examples**
20
+
21
+```cpp
22
+container.Start();
23
+```
24
+
25
+```cpp
26
+container.Stop(static_cast<Signal>(15), std::chrono::seconds(10));
27
+```
28
+
29
+```cpp
30
+container.Delete(DeleteContainerOption::None);
31
+```
32
+
33
+```cpp
34
+auto proc = container.CreateProcess(procSettings);
35
+```
36
+
37
+```cpp
38
+auto inspectJson = container.Inspect();
39
+auto id = container.Id();
40
+auto state = container.State();
41
+```
42
+
43
+```cpp
44
+auto init = container.InitProcess();
45
+```
doc/docs/api-reference/cpp/core-classes/index.md
new
+8
@@ -0,0 +1,8 @@
1
+# Core Classes
2
+
3
+
4
+## Members
5
+
6
+- [Session](session.md)
7
+- [Container](container.md)
8
+- [Process](process.md)
doc/docs/api-reference/cpp/core-classes/process.md
new
+83
@@ -0,0 +1,83 @@
1
+# Process
2
+
3
+`Process` objects are returned by `Container::CreateProcess()` and `Container::InitProcess()`.
4
+
5
+**Methods / events**
6
+- `Start()`
7
+- `Signal(Signal signal)`
8
+- `GetOutputStream(ProcessOutputHandle outputHandle)`
9
+- `GetInputStream()`
10
+- `Pid()`
11
+- `State()`
12
+- `ExitCode()`
13
+- event `OutputReceived`
14
+- event `ErrorReceived`
15
+- event `Exited`
16
+- `Close()`
17
+
18
+**Behavior notes**
19
+- `Start()` cannot be called on the init process.
20
+- `Start()` requires a non-empty `ProcessSettings::CommandLine()`.
21
+- `GetOutputStream()` requires `ProcessOutputMode::Stream`.
22
+- `OutputReceived` and `ErrorReceived` require `ProcessOutputMode::Event`.
23
+- `Exited` is raised by the exit callback in event mode, and by waiting on the process exit event in stream/discard mode.
24
+
25
+**Examples**
26
+
27
+```cpp
28
+auto proc = container.CreateProcess(procSettings);
29
+proc.Exited([](int32_t exitCode)
30
+{
31
+ printf("process exited: %d\n", exitCode);
32
+});
33
+proc.Start();
34
+```
35
+
36
+```cpp
37
+auto pid = proc.Pid();
38
+auto state = proc.State();
39
+```
40
+
41
+```cpp
42
+proc.Signal(static_cast<Signal>(2)); // SIGINT
43
+```
44
+
45
+```cpp
46
+auto stdinStream = proc.GetInputStream();
47
+```
48
+
49
+```cpp
50
+ProcessSettings streamSettings;
51
+streamSettings.OutputMode(ProcessOutputMode::Stream);
52
+// ... set CommandLine ...
53
+auto streamProc = container.CreateProcess(streamSettings);
54
+streamProc.Start();
55
+auto stdoutStream = streamProc.GetOutputStream(static_cast<ProcessOutputHandle>(1));
56
+auto stderrStream = streamProc.GetOutputStream(static_cast<ProcessOutputHandle>(2));
57
+```
58
+
59
+```cpp
60
+ProcessSettings eventSettings;
61
+eventSettings.OutputMode(ProcessOutputMode::Event);
62
+// ... set CommandLine ...
63
+auto eventProc = container.CreateProcess(eventSettings);
64
+eventProc.OutputReceived([](auto const& data)
65
+{
66
+ printf("stdout bytes: %zu\n", data.size());
67
+});
68
+eventProc.ErrorReceived([](auto const& data)
69
+{
70
+ printf("stderr bytes: %zu\n", data.size());
71
+});
72
+eventProc.Exited([](int32_t exitCode)
73
+{
74
+ printf("done: %d\n", exitCode);
75
+});
76
+eventProc.Start();
77
+```
78
+
79
+```cpp
80
+auto exitCode = proc.ExitCode();
81
+```
82
+
83
+---
doc/docs/api-reference/cpp/core-classes/session.md
new
+104
@@ -0,0 +1,104 @@
1
+# Session
2
+
3
+**Constructor**
4
+- `Session(SessionSettings settings)`
5
+ - rejects `nullptr` settings.
6
+
7
+**Methods**
8
+- `Start()`
9
+- `Terminate()`
10
+- `CreateContainer(ContainerSettings containerSettings)`
11
+- `PullImage(PullImageOptions options)`
12
+- `PullImageAsync(PullImageOptions options)`
13
+- `ImportImage(hstring path, hstring imageName)`
14
+- `ImportImageAsync(hstring path, hstring imageName)`
15
+- `LoadImage(hstring path)`
16
+- `LoadImageAsync(hstring path)`
17
+- `PushImage(PushImageOptions options)`
18
+- `PushImageAsync(PushImageOptions options)`
19
+- `DeleteImage(hstring nameOrId)`
20
+- `TagImage(TagImageOptions options)`
21
+- `CreateVhdVolume(VhdOptions options)`
22
+- `DeleteVhdVolume(hstring name)`
23
+- `Authenticate(Uri serverAddress, hstring username, hstring password)`
24
+- `GetImages()`
25
+- event `Terminated`
26
+- event `ProcessCrashed`
27
+- `Close()`
28
+
29
+**Behavior notes**
30
+- `Start()` is one-shot; calling it twice throws.
31
+- Most methods call `EnsureStarted()` first.
32
+- `ImportImage` / `ImportImageAsync` and `LoadImage` / `LoadImageAsync` are path-based only.
33
+- `Authenticate` requires a non-null `Uri` and non-empty username.
34
+- `GetImages()` materializes WinRT `ImageInfo` objects from the C array returned by `WslcListSessionImages`.
35
+
36
+**Examples**
37
+
38
+```cpp
39
+Session session{ settings };
40
+session.Terminated([](SessionTerminationReason reason)
41
+{
42
+ printf("session terminated: %d\n", static_cast<int>(reason));
43
+});
44
+session.ProcessCrashed([](ProcessCrashInformation const& info)
45
+{
46
+ printf("process crashed: %ws\n", info.ProcessName().c_str());
47
+});
48
+session.Start();
49
+```
50
+
51
+```cpp
52
+auto container = session.CreateContainer(containerSettings);
53
+```
54
+
55
+```cpp
56
+auto importOp = session.ImportImageAsync(L"C:\\images\\alpine.tar", L"demo/alpine:latest");
57
+importOp.Progress([](auto&&, ImageProgress const& p) { /* progress */ });
58
+co_await importOp;
59
+```
60
+
61
+```cpp
62
+auto loadOp = session.LoadImageAsync(L"C:\\images\\bundle.tar");
63
+co_await loadOp;
64
+```
65
+
66
+```cpp
67
+session.DeleteImage(L"demo/alpine:latest");
68
+```
69
+
70
+```cpp
71
+auto token = session.Authenticate(
72
+ winrt::Windows::Foundation::Uri{ L"https://registry.example.com" },
73
+ L"user",
74
+ L"password");
75
+```
76
+
77
+```cpp
78
+auto images = session.GetImages();
79
+for (auto const& image : images)
80
+{
81
+ printf("%ws\n", image.Name().c_str());
82
+}
83
+```
84
+
85
+```cpp
86
+PullImageOptions pullOptions = ;
87
+auto pullOp = session.PullImageAsync(pullOptions);
88
+pullOp.Progress([](auto&&, ImageProgress const& p) { /* progress */ });
89
+co_await pullOp;
90
+
91
+PushImageOptions pushOptions = ;
92
+co_await session.PushImageAsync(pushOptions);
93
+
94
+TagImageOptions tagOptions = ;
95
+session.TagImage(tagOptions);
96
+
97
+VhdOptions vhdOptions = ;
98
+session.CreateVhdVolume(vhdOptions);
99
+session.DeleteVhdVolume(L"build-cache");
100
+```
101
+
102
+```cpp
103
+session.Terminate();
104
+```
doc/docs/api-reference/cpp/data-classes/.pages
new
+10
@@ -0,0 +1,10 @@
1
+title: Data Classes
2
+nav:
3
+ - index.md
4
+ - imageinfo.md
5
+ - imageprogress.md
6
+ - installprogress.md
7
+ - containerportmapping.md
8
+ - containervolume.md
9
+ - containernamedvolume.md
10
+ - referenced.md
doc/docs/api-reference/cpp/data-classes/containernamedvolume.md
new
+16
@@ -0,0 +1,16 @@
1
+# ContainerNamedVolume
2
+
3
+Attaches a named session VHD volume to a container.
4
+
5
+**Constructors / properties**
6
+- `ContainerNamedVolume(hstring name, hstring containerPath, bool readOnly)`
7
+- `Name()` / setter
8
+- `ContainerPath()` / setter
9
+- `ReadOnly()` / setter
10
+
11
+```cpp
12
+ContainerNamedVolume named{ L"build-cache", L"/cache", false };
13
+named.Name(L"build-cache");
14
+named.ContainerPath(L"/cache");
15
+named.ReadOnly(false);
16
+```
doc/docs/api-reference/cpp/data-classes/containerportmapping.md
new
+27
@@ -0,0 +1,27 @@
1
+# ContainerPortMapping
2
+
3
+Maps a Windows host port to a container port.
4
+
5
+**Constructors / properties**
6
+- `ContainerPortMapping(uint16_t windowsPort, uint16_t containerPort, PortProtocol protocol)`
7
+- `WindowsPort()` / setter
8
+- `ContainerPort()` / setter
9
+- `Protocol()` / setter
10
+- `WindowsAddress()` / setter
11
+
12
+**Important notes**
13
+- `WindowsAddress` is implemented.
14
+- The setter accepts only `Windows::Networking::HostName` values whose type is `Ipv4` or `Ipv6`.
15
+- `ToStruct()` uses `inet_pton` and stores a real `sockaddr_in` / `sockaddr_in6`.
16
+
17
+```cpp
18
+using namespace winrt::Windows::Networking;
19
+
20
+ContainerPortMapping mapping{ 8080, 80, PortProtocol::TCP };
21
+mapping.WindowsAddress(HostName{ L"127.0.0.1" });
22
+
23
+auto hostPort = mapping.WindowsPort();
24
+auto guestPort = mapping.ContainerPort();
25
+auto protocol = mapping.Protocol();
26
+auto bindAddress = mapping.WindowsAddress();
27
+```
doc/docs/api-reference/cpp/data-classes/containervolume.md
new
+16
@@ -0,0 +1,16 @@
1
+# ContainerVolume
2
+
3
+Binds a Windows path into the container.
4
+
5
+**Constructors / properties**
6
+- `ContainerVolume(hstring windowsPath, hstring containerPath, bool readOnly)`
7
+- `WindowsPath()` / setter
8
+- `ContainerPath()` / setter
9
+- `ReadOnly()` / setter
10
+
11
+```cpp
12
+ContainerVolume volume{ L"C:\\data", L"/workspace", false };
13
+volume.ReadOnly(true);
14
+volume.WindowsPath(L"C:\\data");
15
+volume.ContainerPath(L"/workspace");
16
+```
doc/docs/api-reference/cpp/data-classes/imageinfo.md
new
+20
@@ -0,0 +1,20 @@
1
+# ImageInfo
2
+
3
+Read-only wrapper created from `WslcImageInfo`.
4
+
5
+**Properties**
6
+- `Name()` → image name
7
+- `Sha256()` → 32-byte buffer
8
+- `Size()` → image size
9
+- `CreatedTimestamp()` → WinRT `DateTime`
10
+
11
+```cpp
12
+auto images = session.GetImages();
13
+for (auto const& image : images)
14
+{
15
+ auto name = image.Name();
16
+ auto hash = image.Sha256();
17
+ auto size = image.Size();
18
+ auto created = image.CreatedTimestamp();
19
+}
20
+```
doc/docs/api-reference/cpp/data-classes/imageprogress.md
new
+22
@@ -0,0 +1,22 @@
1
+# ImageProgress
2
+
3
+Progress item reported by image pull/import/load/push operations.
4
+
5
+**Properties**
6
+- `Id()`
7
+- `Status()`
8
+- `CurrentBytes()`
9
+- `TotalBytes()`
10
+
11
+```cpp
12
+auto op = session.LoadImageAsync(L"C:\\images\\demo.tar");
13
+op.Progress([](auto&&, ImageProgress const& p)
14
+{
15
+ printf("layer=%ws status=%d %llu/%llu\n",
16
+ p.Id().c_str(),
17
+ static_cast<int>(p.Status()),
18
+ p.CurrentBytes(),
19
+ p.TotalBytes());
20
+});
21
+co_await op;
22
+```
doc/docs/api-reference/cpp/data-classes/index.md
new
+12
@@ -0,0 +1,12 @@
1
+# Data Classes
2
+
3
+
4
+## Members
5
+
6
+- [ImageInfo](imageinfo.md)
7
+- [ImageProgress](imageprogress.md)
8
+- [InstallProgress](installprogress.md)
9
+- [ContainerPortMapping](containerportmapping.md)
10
+- [ContainerVolume](containervolume.md)
11
+- [ContainerNamedVolume](containernamedvolume.md)
12
+- [Referenced](referenced.md)
doc/docs/api-reference/cpp/data-classes/installprogress.md
new
+20
@@ -0,0 +1,20 @@
1
+# InstallProgress
2
+
3
+Progress item reported by `WslcService::InstallWithDependenciesAsync()`.
4
+
5
+**Properties**
6
+- `Component()`
7
+- `Progress()`
8
+- `Total()`
9
+
10
+```cpp
11
+auto install = WslcService::InstallWithDependenciesAsync();
12
+install.Progress([](auto&&, InstallProgress const& p)
13
+{
14
+ printf("component=%d step=%u/%u\n",
15
+ static_cast<int>(p.Component()),
16
+ p.Progress(),
17
+ p.Total());
18
+});
19
+co_await install;
20
+```
doc/docs/api-reference/cpp/data-classes/referenced.md
new
+30
@@ -0,0 +1,30 @@
1
+# Referenced
2
+
3
+- `Session::PullImageAsync(PullImageOptions)` forwards a struct whose C shape is `{ uri, progressCallback, progressCallbackContext, registryAuth }`.
4
+- `Session::PushImageAsync(PushImageOptions)` forwards a struct whose C shape is `{ image, registryAuth, progressCallback, progressCallbackContext }`.
5
+- `Session::TagImage(TagImageOptions)` forwards a struct whose C shape is `{ image, repo, tag }`.
6
+- `Session::CreateVhdVolume(VhdOptions)` and `SessionSettings::VhdRequirements(VhdOptions)` use `VhdOptions` properties `Name`, `Size`, `Type`, and `Owner`.
7
+- `WslcService::GetVersion()` returns a `ServiceVersion` created from C `major`, `minor`, and `revision` values.
8
+
9
+
10
+
11
+```cpp
12
+PullImageOptions pullOptions = /* construct using the wrapper available in your build */;
13
+auto pull = session.PullImageAsync(pullOptions);
14
+pull.Progress([](auto&&, ImageProgress const& p) { /* ... */ });
15
+co_await pull;
16
+
17
+PushImageOptions pushOptions = /* construct using the wrapper available in your build */;
18
+co_await session.PushImageAsync(pushOptions);
19
+
20
+TagImageOptions tagOptions = /* construct using the wrapper available in your build */;
21
+session.TagImage(tagOptions);
22
+
23
+VhdOptions vhdOptions = /* construct using the wrapper available in your build */;
24
+session.CreateVhdVolume(vhdOptions);
25
+
26
+auto version = WslcService::GetVersion();
27
+(void)version;
28
+```
29
+
30
+---
doc/docs/api-reference/cpp/delegates-and-events/.pages
new
+7
@@ -0,0 +1,7 @@
1
+title: Delegates and Events
2
+nav:
3
+ - index.md
4
+ - sessionterminationhandler.md
5
+ - processcrashhandler.md
6
+ - processoutputhandler.md
7
+ - processexithandler.md
doc/docs/api-reference/cpp/delegates-and-events/index.md
new
+9
@@ -0,0 +1,9 @@
1
+# Delegates and Events
2
+
3
+
4
+## Members
5
+
6
+- [SessionTerminationHandler](sessionterminationhandler.md)
7
+- [ProcessCrashHandler](processcrashhandler.md)
8
+- [ProcessOutputHandler](processoutputhandler.md)
9
+- [ProcessExitHandler](processexithandler.md)
doc/docs/api-reference/cpp/delegates-and-events/processcrashhandler.md
new
+11
@@ -0,0 +1,11 @@
1
+# ProcessCrashHandler
2
+
3
+Observed use:
4
+- `Session::ProcessCrashed` raises one `ProcessCrashInformation` argument.
5
+
6
+```cpp
7
+session.ProcessCrashed([](ProcessCrashInformation const& info)
8
+{
9
+ printf("process crashed: %ws\n", info.ProcessName().c_str());
10
+});
11
+```
doc/docs/api-reference/cpp/delegates-and-events/processexithandler.md
new
+13
@@ -0,0 +1,13 @@
1
+# ProcessExitHandler
2
+
3
+Observed use:
4
+- `Process::Exited` raises one `int32_t exitCode`.
5
+
6
+```cpp
7
+process.Exited([](int32_t exitCode)
8
+{
9
+ printf("exit code: %d\n", exitCode);
10
+});
11
+```
12
+
13
+---
doc/docs/api-reference/cpp/delegates-and-events/processoutputhandler.md
new
+13
@@ -0,0 +1,13 @@
1
+# ProcessOutputHandler
2
+
3
+Observed use:
4
+- `Process::OutputReceived` and `Process::ErrorReceived` raise one argument containing raw output bytes.
5
+- The wrapper forwards a `winrt::array_view<const uint8_t>` produced from the C callback buffer.
6
+
7
+```cpp
8
+process.OutputReceived([](auto const& data)
9
+{
10
+ std::string text(data.begin(), data.end());
11
+ printf("stdout: %s\n", text.c_str());
12
+});
13
+```
doc/docs/api-reference/cpp/delegates-and-events/sessionterminationhandler.md
new
+11
@@ -0,0 +1,11 @@
1
+# SessionTerminationHandler
2
+
3
+Observed use:
4
+- `Session::Terminated` raises one argument: `SessionTerminationReason reason`.
5
+
6
+```cpp
7
+session.Terminated([](SessionTerminationReason reason)
8
+{
9
+ printf("terminated: %d\n", static_cast<int>(reason));
10
+});
11
+```
doc/docs/api-reference/cpp/end-to-end-example.md
new
+106
@@ -0,0 +1,106 @@
1
+# End-to-End Example
2
+
3
+The example below shows one full lifecycle matching the C API example:
4
+
5
+1. Check prerequisites
6
+2. Print SDK version
7
+3. Create a session (4 CPUs, 4 GB RAM)
8
+4. Pull alpine:latest
9
+5. Configure an init process (`/bin/echo "Hello from WSL Container!"`)
10
+6. Create and start the container
11
+7. Wait for the init process to exit
12
+8. Print exit code
13
+9. Stop and delete the container
14
+10. Terminate the session
15
+
16
+```cpp
17
+#include <cstdio>
18
+#include <string>
19
+#include <chrono>
20
+#include <winrt/Microsoft.WSL.Containers.h>
21
+#include <winrt/Windows.Foundation.h>
22
+#include <winrt/Windows.Foundation.Collections.h>
23
+
24
+using namespace winrt;
25
+using namespace winrt::Microsoft::WSL::Containers;
26
+using namespace winrt::Windows::Foundation;
27
+using namespace winrt::Windows::Foundation::Collections;
28
+using namespace std::chrono_literals;
29
+
30
+int main()
31
+{
32
+ init_apartment();
33
+
34
+ // 0. Check prerequisites
35
+ auto missing = WslcService::GetMissingComponents();
36
+ if (missing != static_cast<Component>(0))
37
+ {
38
+ printf("WSL components are missing. Run: wsl --install\n");
39
+ return 1;
40
+ }
41
+
42
+ auto ver = WslcService::GetVersion();
43
+ printf("WSL version: %u.%u.%u\n", ver.Major(), ver.Minor(), ver.Revision());
44
+
45
+ // 1. Create a session
46
+ SessionSettings sessionSettings{ L"MyApp", L"C:\\WslcData" };
47
+ sessionSettings.CpuCount(4);
48
+ sessionSettings.MemorySizeInMB(4096);
49
+
50
+ Session session{ sessionSettings };
51
+ session.Start();
52
+
53
+ // 2. Pull an image
54
+ PullImageOptions pullOpts{ L"docker.io/library/alpine:latest" };
55
+ auto pullOp = session.PullImageAsync(pullOpts);
56
+ co_await pullOp;
57
+
58
+ // 3. Configure an init process
59
+ ProcessSettings initProcSettings;
60
+ initProcSettings.OutputMode(ProcessOutputMode::Event);
61
+ auto argv = single_threaded_vector<hstring>();
62
+ argv.Append(L"/bin/echo");
63
+ argv.Append(L"Hello from WSL Container!");
64
+ initProcSettings.CommandLine(argv);
65
+
66
+ // 4. Configure and create a container
67
+ ContainerSettings containerSettings{ L"alpine:latest" };
68
+ containerSettings.Name(L"hello-container");
69
+ containerSettings.InitProcess(initProcSettings);
70
+
71
+ auto container = session.CreateContainer(containerSettings);
72
+
73
+ // 5. Subscribe to init process events before starting
74
+ auto initProcess = container.InitProcess();
75
+ auto exitedEvent = handle{ CreateEvent(nullptr, TRUE, FALSE, nullptr) };
76
+ int32_t initExitCode = -1;
77
+
78
+ initProcess.OutputReceived([](auto const& data)
79
+ {
80
+ std::string text(data.begin(), data.end());
81
+ printf("%s", text.c_str());
82
+ });
83
+ initProcess.Exited([&](int32_t exitCode)
84
+ {
85
+ initExitCode = exitCode;
86
+ SetEvent(exitedEvent.get());
87
+ });
88
+
89
+ // 6. Start the container
90
+ container.Start();
91
+
92
+ // 7. Wait for the init process to exit (30-second timeout)
93
+ WaitForSingleObject(exitedEvent.get(), 30000);
94
+ printf("Process exited with code: %d\n", initExitCode);
95
+
96
+ // 8. Clean up
97
+ if (container.State() == ContainerState::Running)
98
+ {
99
+ container.Stop(Signal::SIGTERM, 10s);
100
+ }
101
+ container.Delete(DeleteContainerOption::None);
102
+ session.Terminate();
103
+
104
+ return 0;
105
+}
106
+```
doc/docs/api-reference/cpp/enumerations/.pages
new
+16
@@ -0,0 +1,16 @@
1
+title: Enumerations
2
+nav:
3
+ - index.md
4
+ - component.md
5
+ - deletecontaineroption.md
6
+ - error.md
7
+ - containernetworkingmode.md
8
+ - portprotocol.md
9
+ - containerstate.md
10
+ - signal.md
11
+ - processoutputhandle.md
12
+ - processoutputmode.md
13
+ - processstate.md
14
+ - vhdtype.md
15
+ - imageprogressstatus.md
16
+ - sessionterminationreason.md
doc/docs/api-reference/cpp/enumerations/component.md
new
+16
@@ -0,0 +1,16 @@
1
+# Component
2
+
3
+`WslcService::GetMissingComponents()` returns a `Component` bitmask.
4
+
5
+Underlying values:
6
+- `VirtualMachinePlatform = 1`
7
+- `WslPackage = 2`
8
+- `SdkNeedsUpdate = 4`
9
+
10
+```cpp
11
+auto missing = WslcService::GetMissingComponents();
12
+if (missing != static_cast<Component>(0))
13
+{
14
+ co_await WslcService::InstallWithDependenciesAsync();
15
+}
16
+```
doc/docs/api-reference/cpp/enumerations/containernetworkingmode.md
new
+13
@@ -0,0 +1,13 @@
1
+# ContainerNetworkingMode
2
+
3
+`winrt_ContainerSettings.cpp` explicitly validates only:
4
+- `None`
5
+- `Bridged`
6
+
7
+Underlying C values:
8
+- `None = 0`
9
+- `Bridged = 1`
10
+
11
+```cpp
12
+containerSettings.NetworkingMode(ContainerNetworkingMode::Bridged);
13
+```
doc/docs/api-reference/cpp/enumerations/containerstate.md
new
+18
@@ -0,0 +1,18 @@
1
+# ContainerState
2
+
3
+`Container::State()` casts directly from `WslcContainerState`.
4
+
5
+Underlying C values:
6
+- `Invalid = 0`
7
+- `Created = 1`
8
+- `Running = 2`
9
+- `Exited = 3`
10
+- `Deleted = 4`
11
+
12
+```cpp
13
+auto state = container.State();
14
+if (state == static_cast<ContainerState>(2))
15
+{
16
+ // running
17
+}
18
+```
doc/docs/api-reference/cpp/enumerations/deletecontaineroption.md
new
+11
@@ -0,0 +1,11 @@
1
+# DeleteContainerOption
2
+
3
+`Container::Delete()` takes `DeleteContainerOption`.
4
+
5
+Underlying values:
6
+- `None = 0`
7
+- `Force = 1`
8
+
9
+```cpp
10
+container.Delete(DeleteContainerOption::Force);
11
+```
doc/docs/api-reference/cpp/enumerations/error.md
new
+17
@@ -0,0 +1,17 @@
1
+# Error
2
+
3
+Underlying HRESULT values:
4
+- `ImageNotFound = -2147219967`
5
+- `ContainerPrefixAmbiguous = -2147219966`
6
+- `ContainerNotFound = -2147219965`
7
+- `VolumeNotFound = -2147219964`
8
+- `ContainerNotRunning = -2147219963`
9
+- `ContainerIsRunning = -2147219962`
10
+- `SessionReserved = -2147219961`
11
+- `InvalidSessionName = -2147219960`
12
+- `NetworkNotFound = -2147219959`
13
+- `WindowsUpdateSearchFailed = -2147219958`
14
+- `SdkUpdateNeeded = -2147219957`
15
+- `ContainerDisabled = -2147219956`
16
+- `RegistryBlockedByPolicy = -2147219955`
17
+- `VolumeNotAvailable = -2147219954`
doc/docs/api-reference/cpp/enumerations/imageprogressstatus.md
new
+20
@@ -0,0 +1,20 @@
1
+# ImageProgressStatus
2
+
3
+`ImageProgress` casts directly from `WslcImageProgressStatus`.
4
+
5
+Underlying C values:
6
+- `Unknown = 0`
7
+- `Pulling = 1`
8
+- `Waiting = 2`
9
+- `Downloading = 3`
10
+- `Verifying = 4`
11
+- `Extracting = 5`
12
+- `Complete = 6`
13
+
14
+```cpp
15
+auto status = progress.Status();
16
+if (status == static_cast<ImageProgressStatus>(6))
17
+{
18
+ // complete
19
+}
20
+```
doc/docs/api-reference/cpp/enumerations/index.md
new
+19
@@ -0,0 +1,19 @@
1
+# Enumerations
2
+
3
+For enums that are directly `static_cast` to/from the C API, the numeric values match the corresponding `Wslc*` enum in `wslcsdk.h`.
4
+
5
+## Members
6
+
7
+- [Component](component.md)
8
+- [DeleteContainerOption](deletecontaineroption.md)
9
+- [Error](error.md)
10
+- [ContainerNetworkingMode](containernetworkingmode.md)
11
+- [PortProtocol](portprotocol.md)
12
+- [ContainerState](containerstate.md)
13
+- [Signal](signal.md)
14
+- [ProcessOutputHandle](processoutputhandle.md)
15
+- [ProcessOutputMode](processoutputmode.md)
16
+- [ProcessState](processstate.md)
17
+- [VhdType](vhdtype.md)
18
+- [ImageProgressStatus](imageprogressstatus.md)
19
+- [SessionTerminationReason](sessionterminationreason.md)
doc/docs/api-reference/cpp/enumerations/portprotocol.md
new
+12
@@ -0,0 +1,12 @@
1
+# PortProtocol
2
+
3
+- `TCP` is the default in `winrt_ContainerPortMapping.h`.
4
+- The value is passed directly to `WslcContainerPortMapping::protocol`.
5
+
6
+Underlying C values:
7
+- `TCP = 0`
8
+- `UDP = 1`
9
+
10
+```cpp
11
+ContainerPortMapping mapping{ 8080, 80, PortProtocol::TCP };
12
+```
doc/docs/api-reference/cpp/enumerations/processoutputhandle.md
new
+9
@@ -0,0 +1,9 @@
1
+# ProcessOutputHandle
2
+
3
+`Process::GetOutputStream(ProcessOutputHandle)` accepts these values:
4
+- `StandardOutput = 1`
5
+- `StandardError = 2`
6
+
7
+```cpp
8
+auto stdoutStream = process.GetOutputStream(ProcessOutputHandle::StandardOutput);
9
+```
doc/docs/api-reference/cpp/enumerations/processoutputmode.md
new
+15
@@ -0,0 +1,15 @@
1
+# ProcessOutputMode
2
+
3
+Underlying values:
4
+- `Discard = 0`
5
+- `Stream = 1`
6
+- `Event = 2`
7
+
8
+Behavior:
9
+- `Discard`: no stdout/stderr events or output streams.
10
+- `Stream`: `GetOutputStream(...)` can be used.
11
+- `Event`: stdout/stderr are delivered by callbacks and `OutputReceived` / `ErrorReceived`.
12
+
13
+```cpp
14
+procSettings.OutputMode(ProcessOutputMode::Event);
15
+```
doc/docs/api-reference/cpp/enumerations/processstate.md
new
+16
@@ -0,0 +1,16 @@
1
+# ProcessState
2
+
3
+`Process::State()` casts directly from `WslcProcessState`.
4
+
5
+Underlying C values:
6
+- `Unknown = 0`
7
+- `Running = 1`
8
+- `Exited = 2`
9
+- `Signalled = 3`
10
+
11
+```cpp
12
+if (process.State() == static_cast<ProcessState>(1))
13
+{
14
+ // running
15
+}
16
+```
doc/docs/api-reference/cpp/enumerations/sessionterminationreason.md
new
+18
@@ -0,0 +1,18 @@
1
+# SessionTerminationReason
2
+
3
+`Session::OnTerminated` converts `WslcSessionTerminationReason` directly to the WinRT enum.
4
+
5
+Underlying C values:
6
+- `Unknown = 0`
7
+- `Shutdown = 1`
8
+- `Crashed = 2`
9
+
10
+```cpp
11
+session.Terminated([](SessionTerminationReason reason)
12
+{
13
+ if (reason == static_cast<SessionTerminationReason>(2))
14
+ {
15
+ // crashed
16
+ }
17
+});
18
+```
doc/docs/api-reference/cpp/enumerations/signal.md
new
+16
@@ -0,0 +1,16 @@
1
+# Signal
2
+
3
+`Container::Stop()` and `Process::Signal()` cast directly to `WslcSignal`.
4
+
5
+Underlying values:
6
+- `None = 0`
7
+- `SIGHUP = 1`
8
+- `SIGINT = 2`
9
+- `SIGQUIT = 3`
10
+- `SIGKILL = 9`
11
+- `SIGTERM = 15`
12
+
13
+```cpp
14
+process.Signal(Signal::SIGINT);
15
+container.Stop(Signal::SIGTERM, std::chrono::seconds(10));
16
+```
doc/docs/api-reference/cpp/enumerations/vhdtype.md
new
+9
@@ -0,0 +1,9 @@
1
+# VhdType
2
+
3
+Underlying values:
4
+- `Dynamic = 0`
5
+- `Fixed = 1`
6
+
7
+```cpp
8
+vhdOptions.Type(VhdType::Dynamic);
9
+```
doc/docs/api-reference/cpp/index.md
new
+24
@@ -0,0 +1,24 @@
1
+# WSL container API C++ reference
2
+
3
+This reference documents the **C++/WinRT projection** in `Microsoft::WSL::Containers`.
4
+
5
+> **Preview notice:** `wslcsdk.h` explicitly marks this API as **preview** and subject to breaking changes.
6
+>
7
+> **Header:** `#include <winrt/Microsoft.WSL.Containers.h>`
8
+>
9
+> **Namespace:** `winrt::Microsoft::WSL::Containers`
10
+
11
+The projection is layered as **Session → Container → Process**. Errors surface as `winrt::hresult_error`. Image and installation operations use `IAsyncActionWithProgress<T>`.
12
+
13
+---
14
+
15
+## In this reference
16
+
17
+- [Data Classes](data-classes/index.md)
18
+- [Settings Classes](settings-classes/index.md)
19
+- [Core Classes](core-classes/index.md)
20
+- [Service Class](service-class/index.md)
21
+- [Delegates and Events](delegates-and-events/index.md)
22
+- [Enumerations](enumerations/index.md)
23
+- [Not Yet Implemented and Known Gaps](not-yet-implemented-and-known-gaps.md)
24
+- [End-to-End Example](end-to-end-example.md)
doc/docs/api-reference/cpp/not-yet-implemented-and-known-gaps.md
new
+10
@@ -0,0 +1,10 @@
1
+# Not Yet Implemented and Known Gaps
2
+
3
+| Gap | Details |
4
+|---|---|
5
+| Handle-based image import/load | The C API exposes `WslcImportSessionImage` and `WslcLoadSessionImage` from a `HANDLE`; the WinRT metadata exposes path-based `ImportImage` / `ImportImageAsync` and `LoadImage` / `LoadImageAsync`. |
6
+| Explicit container start flags | `Container::Start()` takes no parameters. In `winrt_Container.cpp`, the wrapper automatically sets `WSLC_CONTAINER_START_FLAG_ATTACH` when the init process output mode is `Event` or `Stream`. |
7
+| Raw process callback plumbing | The C API exposes `WslcSetProcessSettingsCallbacks`, `WslcGetProcessExitEvent`, and raw I/O handles. The WinRT projection hides that behind `ProcessSettings::OutputMode`, `OutputReceived`, `ErrorReceived`, `Exited`, `GetInputStream`, and `GetOutputStream`. |
8
+| Missing wrapper source files in this drop | `winrt_CMakeLists.txt` references `PullImageOptions`, `PushImageOptions`, `TagImageOptions`, `VhdOptions`, and `ServiceVersion`|
9
+
10
+---
doc/docs/api-reference/cpp/service-class/.pages
new
+4
@@ -0,0 +1,4 @@
1
+title: Service Class
2
+nav:
3
+ - index.md
4
+ - wslcservice.md
doc/docs/api-reference/cpp/service-class/index.md
new
+6
@@ -0,0 +1,6 @@
1
+# Service Class
2
+
3
+
4
+## Members
5
+
6
+- [WslcService](wslcservice.md)
doc/docs/api-reference/cpp/service-class/wslcservice.md
new
+35
@@ -0,0 +1,35 @@
1
+# WslcService
2
+
3
+Static entry points over the service-level C API.
4
+
5
+**Methods**
6
+- `GetMissingComponents()`
7
+- `GetVersion()`
8
+- `InstallWithDependencies()`
9
+- `InstallWithDependenciesAsync()`
10
+
11
+**Behavior notes**
12
+- `GetMissingComponents()` returns a `Component` bitmask.
13
+- `GetVersion()` returns a `ServiceVersion` constructed from `major`, `minor`, and `revision`.
14
+- `InstallWithDependencies()` installs dependencies synchronously.
15
+- `InstallWithDependenciesAsync()` runs on a background thread and reports `InstallProgress`.
16
+
17
+```cpp
18
+auto missing = WslcService::GetMissingComponents();
19
+if (missing != static_cast<Component>(0))
20
+{
21
+ auto install = WslcService::InstallWithDependenciesAsync();
22
+ install.Progress([](auto&&, InstallProgress const& p)
23
+ {
24
+ printf("install %u/%u\n", p.Progress(), p.Total());
25
+ });
26
+ co_await install;
27
+}
28
+```
29
+
30
+```cpp
31
+auto version = WslcService::GetVersion();
32
+(void)version;
33
+```
34
+
35
+---
doc/docs/api-reference/cpp/settings-classes/.pages
new
+7
@@ -0,0 +1,7 @@
1
+title: Settings Classes
2
+nav:
3
+ - index.md
4
+ - sessionsettings.md
5
+ - containersettings.md
6
+ - processsettings.md
7
+ - vhdoptions.md
doc/docs/api-reference/cpp/settings-classes/containersettings.md
new
+50
@@ -0,0 +1,50 @@
1
+# ContainerSettings
2
+
3
+**Constructor**
4
+- `ContainerSettings(hstring imageName)`
5
+ - `imageName` must be non-empty.
6
+
7
+**Properties**
8
+- `ImageName()` / setter
9
+- `Name()` / setter
10
+- `InitProcess()` / setter
11
+- `NetworkingMode()` / setter (`None` and `Bridged` only)
12
+- `HostName()` / setter
13
+- `DomainName()` / setter
14
+- `EnableAutoRemove()` / setter
15
+- `EnableGpu()` / setter
16
+- `Privileged()` / setter
17
+- `PortMappings()` / setter
18
+- `Volumes()` / setter
19
+- `NamedVolumes()` / setter
20
+
21
+**Important notes**
22
+- Collection setters reject `nullptr`.
23
+- When converting to the C struct, null elements inside the collections are rejected.
24
+
25
+```cpp
26
+using namespace winrt::Windows::Foundation::Collections;
27
+
28
+ContainerSettings containerSettings{ L"demo-image:latest" };
29
+containerSettings.Name(L"demo-container");
30
+containerSettings.NetworkingMode(
31
+ winrt::box_value(ContainerNetworkingMode::Bridged)
32
+ .as<winrt::Windows::Foundation::IReference<ContainerNetworkingMode>>());
33
+containerSettings.HostName(L"demo-host");
34
+containerSettings.DomainName(L"localdomain");
35
+containerSettings.EnableAutoRemove(false);
36
+containerSettings.EnableGpu(false);
37
+containerSettings.Privileged(false);
38
+
39
+auto ports = single_threaded_vector<ContainerPortMapping>();
40
+ports.Append(ContainerPortMapping{ 8080, 80, PortProtocol::TCP });
41
+containerSettings.PortMappings(ports);
42
+
43
+auto volumes = single_threaded_vector<ContainerVolume>();
44
+volumes.Append(ContainerVolume{ L"C:\\src", L"/src", false });
45
+containerSettings.Volumes(volumes);
46
+
47
+auto namedVolumes = single_threaded_vector<ContainerNamedVolume>();
48
+namedVolumes.Append(ContainerNamedVolume{ L"cache", L"/cache", false });
49
+containerSettings.NamedVolumes(namedVolumes);
50
+```
doc/docs/api-reference/cpp/settings-classes/index.md
new
+10
@@ -0,0 +1,10 @@
1
+# Settings Classes
2
+
3
+Settings objects become effectively immutable after the wrapper materializes the underlying C struct.
4
+
5
+## Members
6
+
7
+- [SessionSettings](sessionsettings.md)
8
+- [ContainerSettings](containersettings.md)
9
+- [ProcessSettings](processsettings.md)
10
+- [VhdOptions](vhdoptions.md)
doc/docs/api-reference/cpp/settings-classes/processsettings.md
new
+32
@@ -0,0 +1,32 @@
1
+# ProcessSettings
2
+
3
+**Properties**
4
+- `WorkingDirectory()` / setter
5
+- `CommandLine()` / setter
6
+- `EnvironmentVariables()` / setter
7
+- `OutputMode()` / setter
8
+
9
+**Important notes**
10
+- `CommandLine(nullptr)` and `EnvironmentVariables(nullptr)` are rejected.
11
+- `Process::Start()` later requires a **non-empty** `CommandLine()`.
12
+- `ProcessOutputMode::Event` installs C callbacks; `ProcessOutputMode::Stream` expects stream access; `Discard` is the default.
13
+
14
+```cpp
15
+using namespace winrt::Windows::Foundation::Collections;
16
+
17
+ProcessSettings procSettings;
18
+procSettings.WorkingDirectory(L"/workspace");
19
+procSettings.OutputMode(ProcessOutputMode::Event);
20
+
21
+auto cmd = single_threaded_vector<hstring>();
22
+cmd.Append(L"/bin/sh");
23
+cmd.Append(L"-lc");
24
+cmd.Append(L"echo hello");
25
+procSettings.CommandLine(cmd);
26
+
27
+auto env = single_threaded_map<hstring, hstring>();
28
+env.Insert(L"DEMO", L"1");
29
+procSettings.EnvironmentVariables(env);
30
+```
31
+
32
+---
doc/docs/api-reference/cpp/settings-classes/sessionsettings.md
new
+37
@@ -0,0 +1,37 @@
1
+# SessionSettings
2
+
3
+**Constructor**
4
+- `SessionSettings(hstring name, hstring storagePath)`
5
+ - `name` must be non-empty.
6
+ - `storagePath` must be non-empty.
7
+
8
+**Properties**
9
+- `Name()` / setter
10
+- `StoragePath()` / setter
11
+- `CpuCount()` / setter (`0` rejected)
12
+- `MemorySizeInMB()` / setter (`0` rejected)
13
+- `Timeout()` / setter
14
+ - cannot be zero
15
+ - cannot be negative
16
+ - converted to **milliseconds** and must fit in `uint32_t`
17
+- `VhdRequirements()` / setter
18
+ - setter rejects `nullptr`
19
+- `EnableGpu()` / setter
20
+
21
+```cpp
22
+SessionSettings settings{ L"demo", L"C:\\WSLC\\demo" };
23
+settings.Name(L"demo");
24
+settings.StoragePath(L"C:\\WSLC\\demo");
25
+settings.CpuCount(winrt::box_value<uint32_t>(4).as<winrt::Windows::Foundation::IReference<uint32_t>>());
26
+settings.MemorySizeInMB(winrt::box_value<uint32_t>(4096).as<winrt::Windows::Foundation::IReference<uint32_t>>());
27
+settings.Timeout(winrt::box_value(winrt::Windows::Foundation::TimeSpan{ std::chrono::minutes(5) })
28
+ .as<winrt::Windows::Foundation::IReference<winrt::Windows::Foundation::TimeSpan>>());
29
+settings.EnableGpu(true);
30
+
31
+auto name = settings.Name();
32
+auto path = settings.StoragePath();
33
+auto cpu = settings.CpuCount();
34
+auto memory = settings.MemorySizeInMB();
35
+auto timeout = settings.Timeout();
36
+auto enableGpu = settings.EnableGpu();
37
+```
doc/docs/api-reference/cpp/settings-classes/vhdoptions.md
new
+15
@@ -0,0 +1,15 @@
1
+# VhdOptions
2
+
3
+**Properties**
4
+- `Name()` / setter
5
+- `Size()` / setter
6
+- `Type()` / setter
7
+- `Owner()` / setter
8
+
9
+```cpp
10
+VhdOptions options;
11
+options.Name(L"build-cache");
12
+options.Size(10ull * 1024 * 1024 * 1024);
13
+options.Type(VhdType::Dynamic);
14
+options.Owner({ 1000, 1000 });
15
+```
doc/docs/api-reference/csharp/.pages
new
+14
@@ -0,0 +1,14 @@
1
+title: C# API reference
2
+nav:
3
+ - index.md
4
+ - overview.md
5
+ - projected-namespace.md
6
+ - common-cswinrt-type-mappings.md
7
+ - data-classes
8
+ - settings-classes
9
+ - core-classes
10
+ - service-class
11
+ - delegates-and-events.md
12
+ - enumerations
13
+ - known-gaps.md
14
+ - end-to-end-example.md
doc/docs/api-reference/csharp/common-cswinrt-type-mappings.md
new
+19
@@ -0,0 +1,19 @@
1
+# Common CsWinRT Type Mappings
2
+
3
+| WinRT type | C# projection |
4
+|---|---|
5
+| `hstring` | `string` |
6
+| `Windows.Foundation.Uri` | `System.Uri` |
7
+| `Windows.Foundation.TimeSpan` | `System.TimeSpan` |
8
+| `IReference<uint32_t>` | `uint?` |
9
+| `IReference<TimeSpan>` | `TimeSpan?` |
10
+| `IReference<ContainerNetworkingMode>` | `ContainerNetworkingMode?` |
11
+| `IVector<T>` | `IList<T>` |
12
+| `IVectorView<T>` | `IReadOnlyList<T>` |
13
+| `IMap<string, string>` | `IDictionary<string, string>` |
14
+| `Windows.Foundation.DateTime` | `DateTimeOffset` |
15
+| `com_array<uint8_t>` event payload | `byte[]` |
16
+| `Windows.Networking.HostName` | `Windows.Networking.HostName` |
17
+| `IAsyncActionWithProgress<T>` | awaitable WinRT async operation |
18
+
19
+---
doc/docs/api-reference/csharp/core-classes/.pages
new
+6
@@ -0,0 +1,6 @@
1
+title: Core Classes
2
+nav:
3
+ - index.md
4
+ - session.md
5
+ - container.md
6
+ - process.md
doc/docs/api-reference/csharp/core-classes/container.md
new
+103
@@ -0,0 +1,103 @@
1
+# Container
2
+
3
+Represents a container inside a session.
4
+
5
+```csharp
6
+public sealed class Container : IDisposable
7
+{
8
+ public string Id { get; }
9
+ public Process InitProcess { get; }
10
+ public ContainerState State { get; }
11
+
12
+ public void Start();
13
+ public void Stop(Signal signal, TimeSpan timeout);
14
+ public void Delete(DeleteContainerOption option);
15
+ public Process CreateProcess(ProcessSettings newProcessSettings);
16
+ public string Inspect();
17
+ public void Dispose();
18
+}
19
+```
20
+
21
+Notes:
22
+- `Start()` has **no flags parameter**.
23
+- If `InitProcess.OutputMode` is `Event` or `Stream`, `Start()` automatically requests native attach.
24
+- `InitProcess` is only available when `ContainerSettings.InitProcess` was configured.
25
+
26
+## Container.Start()
27
+
28
+Starts the container and, if configured, attaches the init process handle.
29
+
30
+```csharp
31
+container.Start();
32
+```
33
+
34
+## Container.Stop(Signal, TimeSpan)
35
+
36
+Stops the container with a signal and timeout.
37
+
38
+```csharp
39
+container.Stop(Signal.SIGTERM, TimeSpan.FromSeconds(10));
40
+```
41
+
42
+## Container.Delete(DeleteContainerOption)
43
+
44
+Deletes the container.
45
+
46
+```csharp
47
+container.Delete(DeleteContainerOption.Force);
48
+```
49
+
50
+## Container.CreateProcess(ProcessSettings)
51
+
52
+Creates a secondary process object inside the container.
53
+
54
+```csharp
55
+var execSettings = new ProcessSettings
56
+{
57
+ CommandLine = new List<string> { "/bin/sh", "-c", "echo secondary process" },
58
+ OutputMode = ProcessOutputMode.Event
59
+};
60
+
61
+Process process = container.CreateProcess(execSettings);
62
+```
63
+
64
+## Container.Inspect()
65
+
66
+Returns the raw inspect payload as a string.
67
+
68
+```csharp
69
+string inspectJson = container.Inspect();
70
+Console.WriteLine(inspectJson);
71
+```
72
+
73
+## Container.Id
74
+
75
+Returns the container ID string.
76
+
77
+```csharp
78
+Console.WriteLine(container.Id);
79
+```
80
+
81
+## Container.InitProcess
82
+
83
+Gets the configured init process object.
84
+
85
+```csharp
86
+Process init = container.InitProcess;
87
+```
88
+
89
+## Container.State
90
+
91
+Gets the current container state.
92
+
93
+```csharp
94
+Console.WriteLine(container.State);
95
+```
96
+
97
+## Container.Dispose()
98
+
99
+Releases the underlying WinRT container object.
100
+
101
+```csharp
102
+container.Dispose();
103
+```
doc/docs/api-reference/csharp/core-classes/index.md
new
+8
@@ -0,0 +1,8 @@
1
+# Core Classes
2
+
3
+
4
+## Members
5
+
6
+- [Session](session.md)
7
+- [Container](container.md)
8
+- [Process](process.md)
doc/docs/api-reference/csharp/core-classes/process.md
new
+121
@@ -0,0 +1,121 @@
1
+# Process
2
+
3
+Represents a Linux process in a container.
4
+
5
+```csharp
6
+using Windows.Storage.Streams;
7
+
8
+public sealed class Process
9
+{
10
+ public uint Pid { get; }
11
+ public ProcessState State { get; }
12
+ public int ExitCode { get; }
13
+
14
+ public event ProcessOutputHandler OutputReceived;
15
+ public event ProcessOutputHandler ErrorReceived;
16
+ public event ProcessExitHandler Exited;
17
+
18
+ public void Start();
19
+ public void Signal(Signal signal);
20
+ public IInputStream GetOutputStream(ProcessOutputHandle outputHandle);
21
+ public IOutputStream GetInputStream();
22
+}
23
+```
24
+
25
+Notes:
26
+- Call `Start()` only for **secondary processes** created by `Container.CreateProcess(...)`.
27
+- The init process is started by `Container.Start()`.
28
+- `OutputReceived` and `ErrorReceived` require `OutputMode.Event`.
29
+- `GetOutputStream(...)` requires `OutputMode.Stream`.
30
+- `Exited` is available for all output modes.
31
+
32
+## Process.Start()
33
+
34
+Starts a secondary process.
35
+
36
+```csharp
37
+process.Start();
38
+```
39
+
40
+## Process.Signal(Signal)
41
+
42
+Signals the process.
43
+
44
+```csharp
45
+process.Signal(Signal.SIGTERM);
46
+```
47
+
48
+## Process.GetOutputStream(ProcessOutputHandle)
49
+
50
+Gets stdout or stderr as a WinRT input stream.
51
+
52
+```csharp
53
+using Windows.Storage.Streams;
54
+
55
+using IInputStream stdout = process.GetOutputStream(ProcessOutputHandle.StandardOutput);
56
+using var reader = new DataReader(stdout);
57
+await reader.LoadAsync(4096);
58
+string text = reader.ReadString(reader.UnconsumedBufferLength);
59
+Console.WriteLine(text);
60
+```
61
+
62
+## Process.GetInputStream()
63
+
64
+Gets stdin as a WinRT output stream.
65
+
66
+```csharp
67
+using Windows.Storage.Streams;
68
+
69
+using IOutputStream stdin = process.GetInputStream();
70
+using var writer = new DataWriter(stdin);
71
+writer.WriteString("hello from C#\n");
72
+await writer.StoreAsync();
73
+await writer.FlushAsync();
74
+```
75
+
76
+## Process.Pid
77
+
78
+```csharp
79
+Console.WriteLine($"PID: {process.Pid}");
80
+```
81
+
82
+## Process.State
83
+
84
+```csharp
85
+Console.WriteLine($"State: {process.State}");
86
+```
87
+
88
+## Process.ExitCode
89
+
90
+Valid after exit.
91
+
92
+```csharp
93
+Console.WriteLine($"Exit code: {process.ExitCode}");
94
+```
95
+
96
+## Process.OutputReceived event
97
+
98
+```csharp
99
+using System.Text;
100
+
101
+process.OutputReceived += data =>
102
+ Console.Write(Encoding.UTF8.GetString(data));
103
+```
104
+
105
+## Process.ErrorReceived event
106
+
107
+```csharp
108
+using System.Text;
109
+
110
+process.ErrorReceived += data =>
111
+ Console.Error.Write(Encoding.UTF8.GetString(data));
112
+```
113
+
114
+## Process.Exited event
115
+
116
+```csharp
117
+process.Exited += exitCode =>
118
+ Console.WriteLine($"Process exited with {exitCode}");
119
+```
120
+
121
+---
doc/docs/api-reference/csharp/core-classes/session.md
new
+222
@@ -0,0 +1,222 @@
1
+# Session
2
+
3
+Represents a WSL-backed container host session.
4
+
5
+```csharp
6
+public sealed class Session : IDisposable
7
+{
8
+ public Session(SessionSettings settings);
9
+
10
+ public event SessionTerminationHandler Terminated;
11
+ public event ProcessCrashHandler ProcessCrashed;
12
+
13
+ public void Start();
14
+ public void Terminate();
15
+ public Container CreateContainer(ContainerSettings containerSettings);
16
+ public void PullImage(PullImageOptions options);
17
+ public IAsyncActionWithProgress<ImageProgress> PullImageAsync(PullImageOptions options);
18
+ public void ImportImage(string path, string imageName);
19
+ public IAsyncActionWithProgress<ImageProgress> ImportImageAsync(string path, string imageName);
20
+ public void LoadImage(string path);
21
+ public IAsyncActionWithProgress<ImageProgress> LoadImageAsync(string path);
22
+ public void PushImage(PushImageOptions options);
23
+ public IAsyncActionWithProgress<ImageProgress> PushImageAsync(PushImageOptions options);
24
+ public void DeleteImage(string nameOrId);
25
+ public void TagImage(TagImageOptions options);
26
+ public void CreateVhdVolume(VhdOptions options);
27
+ public void DeleteVhdVolume(string name);
28
+ public string Authenticate(Uri serverAddress, string username, string password);
29
+ public IReadOnlyList<ImageInfo> GetImages();
30
+ public void Dispose();
31
+}
32
+```
33
+
34
+## Session constructor
35
+
36
+```csharp
37
+var session = new Session(sessionSettings);
38
+```
39
+
40
+## Session.Start()
41
+
42
+Starts the session VM and registers the internal termination wait.
43
+
44
+```csharp
45
+session.Start();
46
+```
47
+
48
+## Session.Terminate()
49
+
50
+Terminates the session.
51
+
52
+```csharp
53
+session.Terminate();
54
+```
55
+
56
+## Session.CreateContainer(ContainerSettings)
57
+
58
+Creates a container object owned by the session.
59
+
60
+```csharp
61
+Container container = session.CreateContainer(containerSettings);
62
+```
63
+
64
+## Session.PullImage(PullImageOptions)
65
+
66
+Synchronous image pull.
67
+
68
+```csharp
69
+session.PullImage(new PullImageOptions("docker.io/library/alpine:latest"));
70
+```
71
+
72
+## Session.PullImageAsync(PullImageOptions)
73
+
74
+Awaitable pull with progress.
75
+
76
+```csharp
77
+var pull = session.PullImageAsync(new PullImageOptions("docker.io/library/alpine:latest"));
78
+pull.Progress = (op, progress) =>
79
+ Console.WriteLine($"pull: {progress.Status} {progress.Id} {progress.CurrentBytes}/{progress.TotalBytes}");
80
+await pull;
81
+```
82
+
83
+## Session.ImportImage(string path, string imageName)
84
+
85
+Synchronous image import from a file path.
86
+
87
+```csharp
88
+session.ImportImage(@"C:\images\demo.tar", "demo:imported");
89
+```
90
+
91
+## Session.ImportImageAsync(string path, string imageName)
92
+
93
+Imports an image tarball from a file path.
94
+
95
+```csharp
96
+var importOp = session.ImportImageAsync(@"C:\images\demo.tar", "demo:imported");
97
+importOp.Progress = (op, progress) =>
98
+ Console.WriteLine($"import: {progress.Status} {progress.Id}");
99
+await importOp;
100
+```
101
+
102
+## Session.LoadImage(string path)
103
+
104
+Synchronous image load from disk.
105
+
106
+```csharp
107
+session.LoadImage(@"C:\images\docker-save.tar");
108
+```
109
+
110
+## Session.LoadImageAsync(string path)
111
+
112
+Loads an image archive from disk.
113
+
114
+```csharp
115
+var loadOp = session.LoadImageAsync(@"C:\images\docker-save.tar");
116
+loadOp.Progress = (op, progress) =>
117
+ Console.WriteLine($"load: {progress.Status} {progress.Id}");
118
+await loadOp;
119
+```
120
+
121
+## Session.PushImage(PushImageOptions)
122
+
123
+Synchronous image push to a registry.
124
+
125
+```csharp
126
+session.PushImage(new PushImageOptions("registry.example.com/demo:latest", authToken));
127
+```
128
+
129
+## Session.PushImageAsync(PushImageOptions)
130
+
131
+Pushes an image to a registry.
132
+
133
+```csharp
134
+var pushOp = session.PushImageAsync(new PushImageOptions("registry.example.com/demo:latest", authToken));
135
+pushOp.Progress = (op, progress) =>
136
+ Console.WriteLine($"push: {progress.Status} {progress.Id}");
137
+await pushOp;
138
+```
139
+
140
+## Session.DeleteImage(string nameOrId)
141
+
142
+Deletes an image by name or ID.
143
+
144
+```csharp
145
+session.DeleteImage("demo:old");
146
+```
147
+
148
+## Session.TagImage(TagImageOptions)
149
+
150
+Applies a new repository/tag to an existing image.
151
+
152
+```csharp
153
+session.TagImage(new TagImageOptions("alpine:latest", "registry.example.com/alpine", "v1"));
154
+```
155
+
156
+## Session.CreateVhdVolume(VhdOptions)
157
+
158
+Creates a named session VHD volume.
159
+
160
+```csharp
161
+var vhd = new VhdOptions("cache", 2UL * 1024 * 1024 * 1024, VhdType.Dynamic)
162
+{
163
+ Owner = new VhdOwner { Uid = 1000, Gid = 1000 }
164
+};
165
+session.CreateVhdVolume(vhd);
166
+```
167
+
168
+## Session.DeleteVhdVolume(string name)
169
+
170
+Deletes a named session VHD volume.
171
+
172
+```csharp
173
+session.DeleteVhdVolume("cache");
174
+```
175
+
176
+## Session.Authenticate(Uri, string, string)
177
+
178
+Authenticates to a registry and returns an identity token string.
179
+
180
+```csharp
181
+string token = session.Authenticate(
182
+ new Uri("https://registry.example.com"),
183
+ "user1",
184
+ "p@ssw0rd");
185
+```
186
+
187
+## Session.GetImages()
188
+
189
+Returns a snapshot of images known to the session.
190
+
191
+```csharp
192
+foreach (var image in session.GetImages())
193
+{
194
+ Console.WriteLine(image.Name);
195
+}
196
+```
197
+
198
+## Session.Terminated event
199
+
200
+Raised when the session termination event is signaled.
201
+
202
+```csharp
203
+session.Terminated += reason =>
204
+ Console.WriteLine($"Session terminated: {reason}");
205
+```
206
+
207
+## Session.ProcessCrashed event
208
+
209
+Raised when a process crash dump is reported.
210
+
211
+```csharp
212
+session.ProcessCrashed += information =>
213
+ Console.WriteLine($"Process crashed: {information.ProcessName} ({information.Pid})");
214
+```
215
+
216
+## Session.Dispose()
217
+
218
+Releases the underlying WinRT session object.
219
+
220
+```csharp
221
+session.Dispose();
222
+```
doc/docs/api-reference/csharp/data-classes/.pages
new
+12
@@ -0,0 +1,12 @@
1
+title: Data Classes
2
+nav:
3
+ - index.md
4
+ - containerportmapping.md
5
+ - containervolume.md
6
+ - containernamedvolume.md
7
+ - imageinfo.md
8
+ - imageprogress.md
9
+ - installprogress.md
10
+ - processcrashinformation.md
11
+ - serviceversion.md
12
+ - vhdowner.md
doc/docs/api-reference/csharp/data-classes/containernamedvolume.md
new
+20
@@ -0,0 +1,20 @@
1
+# ContainerNamedVolume
2
+
3
+Maps a session-managed named VHD volume into the container.
4
+
5
+```csharp
6
+public sealed class ContainerNamedVolume
7
+{
8
+ public ContainerNamedVolume(string name, string containerPath, bool readOnly);
9
+
10
+ public string Name { get; set; }
11
+ public string ContainerPath { get; set; }
12
+ public bool ReadOnly { get; set; }
13
+}
14
+```
15
+
16
+Example:
17
+
18
+```csharp
19
+var namedVolume = new ContainerNamedVolume("cache", "/var/cache/app", readOnly: false);
20
+```
doc/docs/api-reference/csharp/data-classes/containerportmapping.md
new
+34
@@ -0,0 +1,34 @@
1
+# ContainerPortMapping
2
+
3
+Represents a published port.
4
+
5
+```csharp
6
+using Windows.Networking;
7
+
8
+public sealed class ContainerPortMapping
9
+{
10
+ public ContainerPortMapping(ushort windowsPort, ushort containerPort, PortProtocol protocol);
11
+
12
+ public ushort WindowsPort { get; set; }
13
+ public ushort ContainerPort { get; set; }
14
+ public PortProtocol Protocol { get; set; }
15
+ public HostName WindowsAddress { get; set; }
16
+}
17
+```
18
+
19
+Notes:
20
+- `WindowsAddress` **is implemented**.
21
+- It accepts only `HostNameType.Ipv4` and `HostNameType.Ipv6` values.
22
+- DNS names are rejected.
23
+- `null` means the default host bind address.
24
+
25
+Example:
26
+
27
+```csharp
28
+using Windows.Networking;
29
+
30
+var mapping = new ContainerPortMapping(8080, 80, PortProtocol.TCP)
31
+{
32
+ WindowsAddress = new HostName("127.0.0.1")
33
+};
34
+```
doc/docs/api-reference/csharp/data-classes/containervolume.md
new
+20
@@ -0,0 +1,20 @@
1
+# ContainerVolume
2
+
3
+Maps a Windows path into the container.
4
+
5
+```csharp
6
+public sealed class ContainerVolume
7
+{
8
+ public ContainerVolume(string windowsPath, string containerPath, bool readOnly);
9
+
10
+ public string WindowsPath { get; set; }
11
+ public string ContainerPath { get; set; }
12
+ public bool ReadOnly { get; set; }
13
+}
14
+```
15
+
16
+Example:
17
+
18
+```csharp
19
+var volume = new ContainerVolume(@"C:\data", "/workspace/data", readOnly: false);
20
+```
doc/docs/api-reference/csharp/data-classes/imageinfo.md
new
+24
@@ -0,0 +1,24 @@
1
+# ImageInfo
2
+
3
+Metadata returned by `Session.GetImages()`.
4
+
5
+```csharp
6
+using Windows.Storage.Streams;
7
+
8
+public sealed class ImageInfo
9
+{
10
+ public string Name { get; }
11
+ public IBuffer Sha256 { get; }
12
+ public ulong Size { get; }
13
+ public DateTimeOffset CreatedTimestamp { get; }
14
+}
15
+```
16
+
17
+Example:
18
+
19
+```csharp
20
+foreach (var image in session.GetImages())
21
+{
22
+ Console.WriteLine($"{image.Name} ({image.Size / 1024 / 1024} MB)");
23
+}
24
+```
doc/docs/api-reference/csharp/data-classes/imageprogress.md
new
+20
@@ -0,0 +1,20 @@
1
+# ImageProgress
2
+
3
+Progress payload for pull/import/load/push operations.
4
+
5
+```csharp
6
+public sealed class ImageProgress
7
+{
8
+ public string Id { get; }
9
+ public ImageProgressStatus Status { get; }
10
+ public ulong CurrentBytes { get; }
11
+ public ulong TotalBytes { get; }
12
+}
13
+```
14
+
15
+Example:
16
+
17
+```csharp
18
+void PrintImageProgress(ImageProgress progress) =>
19
+ Console.WriteLine($"{progress.Status,-12} {progress.Id} {progress.CurrentBytes}/{progress.TotalBytes}");
20
+```
doc/docs/api-reference/csharp/data-classes/index.md
new
+14
@@ -0,0 +1,14 @@
1
+# Data Classes
2
+
3
+
4
+## Members
5
+
6
+- [ContainerPortMapping](containerportmapping.md)
7
+- [ContainerVolume](containervolume.md)
8
+- [ContainerNamedVolume](containernamedvolume.md)
9
+- [ImageInfo](imageinfo.md)
10
+- [ImageProgress](imageprogress.md)
11
+- [InstallProgress](installprogress.md)
12
+- [ProcessCrashInformation](processcrashinformation.md)
13
+- [ServiceVersion](serviceversion.md)
14
+- [VhdOwner](vhdowner.md)
doc/docs/api-reference/csharp/data-classes/installprogress.md
new
+19
@@ -0,0 +1,19 @@
1
+# InstallProgress
2
+
3
+Progress payload for dependency installation.
4
+
5
+```csharp
6
+public sealed class InstallProgress
7
+{
8
+ public Component Component { get; }
9
+ public uint Progress { get; }
10
+ public uint Total { get; }
11
+}
12
+```
13
+
14
+Example:
15
+
16
+```csharp
17
+void PrintInstallProgress(InstallProgress progress) =>
18
+ Console.WriteLine($"{progress.Component}: {progress.Progress}/{progress.Total}");
19
+```
doc/docs/api-reference/csharp/data-classes/processcrashinformation.md
new
+21
@@ -0,0 +1,21 @@
1
+# ProcessCrashInformation
2
+
3
+Crash information supplied by the `Session.ProcessCrashed` event.
4
+
5
+```csharp
6
+public sealed class ProcessCrashInformation
7
+{
8
+ public string DumpPath { get; }
9
+ public string ProcessName { get; }
10
+ public uint Pid { get; }
11
+ public uint Signal { get; }
12
+ public DateTimeOffset Timestamp { get; }
13
+}
14
+```
15
+
16
+Example:
17
+
18
+```csharp
19
+session.ProcessCrashed += information =>
20
+ Console.WriteLine($"{information.ProcessName} ({information.Pid}) crashed at {information.Timestamp}");
21
+```
doc/docs/api-reference/csharp/data-classes/serviceversion.md
new
+21
@@ -0,0 +1,21 @@
1
+# ServiceVersion
2
+
3
+WSL service version information.
4
+
5
+```csharp
6
+public sealed class ServiceVersion
7
+{
8
+ public uint Major { get; }
9
+ public uint Minor { get; }
10
+ public uint Revision { get; }
11
+}
12
+```
13
+
14
+Example:
15
+
16
+```csharp
17
+var version = WslcService.GetVersion();
18
+Console.WriteLine($"WSL service: {version.Major}.{version.Minor}.{version.Revision}");
19
+```
20
+
21
+---
doc/docs/api-reference/csharp/data-classes/vhdowner.md
new
+17
@@ -0,0 +1,17 @@
1
+# VhdOwner
2
+
3
+Owner uid/gid for a named VHD volume root inode.
4
+
5
+```csharp
6
+public struct VhdOwner
7
+{
8
+ public uint Uid;
9
+ public uint Gid;
10
+}
11
+```
12
+
13
+Example:
14
+
15
+```csharp
16
+var owner = new VhdOwner { Uid = 1000, Gid = 1000 };
17
+```
doc/docs/api-reference/csharp/delegates-and-events.md
new
+24
@@ -0,0 +1,24 @@
1
+# Delegates and Events
2
+
3
+The WinRT delegates project to normal C# delegates and are consumed as normal C# events.
4
+
5
+```csharp
6
+public delegate void SessionTerminationHandler(SessionTerminationReason reason);
7
+public delegate void ProcessCrashHandler(ProcessCrashInformation information);
8
+public delegate void ProcessOutputHandler(byte[] data);
9
+public delegate void ProcessExitHandler(int exitCode);
10
+```
11
+
12
+Typical event usage:
13
+
14
+```csharp
15
+using System.Text;
16
+
17
+session.Terminated += reason => Console.WriteLine($"Session ended: {reason}");
18
+session.ProcessCrashed += info => Console.WriteLine($"Process crashed: {info.ProcessName} ({info.Pid})");
19
+container.InitProcess.OutputReceived += data => Console.Write(Encoding.UTF8.GetString(data));
20
+container.InitProcess.ErrorReceived += data => Console.Error.Write(Encoding.UTF8.GetString(data));
21
+container.InitProcess.Exited += code => Console.WriteLine($"Init exited: {code}");
22
+```
23
+
24
+---
doc/docs/api-reference/csharp/end-to-end-example.md
new
+96
@@ -0,0 +1,96 @@
1
+# End-to-End Example
2
+
3
+The example below shows one full lifecycle matching the C API example:
4
+
5
+1. Check prerequisites
6
+2. Print SDK version
7
+3. Create a session (4 CPUs, 4 GB RAM)
8
+4. Pull alpine:latest
9
+5. Configure an init process (`/bin/echo "Hello from WSL Container!"`)
10
+6. Create and start the container
11
+7. Wait for the init process to exit
12
+8. Print exit code
13
+9. Stop and delete the container
14
+10. Terminate the session
15
+
16
+```csharp
17
+using Microsoft.WSL.Containers;
18
+using System;
19
+using System.Text;
20
+using System.Threading.Tasks;
21
+
22
+class Program
23
+{
24
+ static async Task<int> Main()
25
+ {
26
+ // 0. Check prerequisites
27
+ var missing = WslcService.GetMissingComponents();
28
+ if (missing.Count > 0)
29
+ {
30
+ Console.WriteLine("WSL components are missing. Run: wsl --install");
31
+ return 1;
32
+ }
33
+
34
+ var ver = WslcService.GetVersion();
35
+ Console.WriteLine($"WSL version: {ver.Major}.{ver.Minor}.{ver.Revision}");
36
+
37
+ // 1. Create a session
38
+ var sessionSettings = new SessionSettings("MyApp", @"C:\WslcData")
39
+ {
40
+ CpuCount = 4,
41
+ MemorySizeInMB = 4096
42
+ };
43
+
44
+ var session = new Session(sessionSettings);
45
+ session.Start();
46
+
47
+ // 2. Pull an image
48
+ var pullOp = session.PullImageAsync(new PullImageOptions("docker.io/library/alpine:latest"));
49
+ pullOp.Progress = (op, progress) =>
50
+ Console.WriteLine($"Pull: {progress.Status} {progress.CurrentBytes}/{progress.TotalBytes}");
51
+ await pullOp;
52
+
53
+ // 3. Configure an init process
54
+ var initProcSettings = new ProcessSettings
55
+ {
56
+ CommandLine = new[] { "/bin/echo", "Hello from WSL Container!" },
57
+ OutputMode = ProcessOutputMode.Event
58
+ };
59
+
60
+ // 4. Configure and create a container
61
+ var containerSettings = new ContainerSettings("alpine:latest")
62
+ {
63
+ Name = "hello-container",
64
+ InitProcess = initProcSettings
65
+ };
66
+
67
+ var container = session.CreateContainer(containerSettings);
68
+
69
+ // 5. Subscribe to init process events before starting
70
+ var exited = new TaskCompletionSource<int>(TaskCreationOptions.RunContinuationsAsynchronously);
71
+
72
+ container.InitProcess.OutputReceived += data =>
73
+ Console.Write(Encoding.UTF8.GetString(data));
74
+ container.InitProcess.Exited += code =>
75
+ exited.TrySetResult(code);
76
+
77
+ // 6. Start the container
78
+ container.Start();
79
+
80
+ // 7. Wait for the init process to exit (30-second timeout)
81
+ var completed = await Task.WhenAny(exited.Task, Task.Delay(TimeSpan.FromSeconds(30)));
82
+ int exitCode = completed == exited.Task ? exited.Task.Result : -1;
83
+ Console.WriteLine($"Process exited with code: {exitCode}");
84
+
85
+ // 8. Clean up
86
+ if (container.State == ContainerState.Running)
87
+ {
88
+ container.Stop(Signal.SIGTERM, TimeSpan.FromSeconds(10));
89
+ }
90
+ container.Delete(DeleteContainerOption.None);
91
+ session.Terminate();
92
+
93
+ return exitCode;
94
+ }
95
+}
96
+```
doc/docs/api-reference/csharp/enumerations/.pages
new
+16
@@ -0,0 +1,16 @@
1
+title: Enumerations
2
+nav:
3
+ - index.md
4
+ - component.md
5
+ - deletecontaineroption.md
6
+ - error.md
7
+ - containernetworkingmode.md
8
+ - portprotocol.md
9
+ - containerstate.md
10
+ - signal.md
11
+ - processoutputhandle.md
12
+ - processoutputmode.md
13
+ - processstate.md
14
+ - vhdtype.md
15
+ - imageprogressstatus.md
16
+ - sessionterminationreason.md
doc/docs/api-reference/csharp/enumerations/component.md
new
+10
@@ -0,0 +1,10 @@
1
+# Component
2
+
3
+```csharp
4
+public enum Component
5
+{
6
+ VirtualMachinePlatform = 1,
7
+ WslPackage = 2,
8
+ SdkNeedsUpdate = 4
9
+}
10
+```
doc/docs/api-reference/csharp/enumerations/containernetworkingmode.md
new
+9
@@ -0,0 +1,9 @@
1
+# ContainerNetworkingMode
2
+
3
+```csharp
4
+public enum ContainerNetworkingMode
5
+{
6
+ None = 0,
7
+ Bridged = 1
8
+}
9
+```
doc/docs/api-reference/csharp/enumerations/containerstate.md
new
+12
@@ -0,0 +1,12 @@
1
+# ContainerState
2
+
3
+```csharp
4
+public enum ContainerState
5
+{
6
+ Invalid = 0,
7
+ Created = 1,
8
+ Running = 2,
9
+ Exited = 3,
10
+ Deleted = 4
11
+}
12
+```
doc/docs/api-reference/csharp/enumerations/deletecontaineroption.md
new
+10
@@ -0,0 +1,10 @@
1
+# DeleteContainerOption
2
+
3
+```csharp
4
+[Flags]
5
+public enum DeleteContainerOption
6
+{
7
+ None = 0,
8
+ Force = 1
9
+}
10
+```
doc/docs/api-reference/csharp/enumerations/error.md
new
+21
@@ -0,0 +1,21 @@
1
+# Error
2
+
3
+```csharp
4
+public enum Error
5
+{
6
+ ImageNotFound = -2147219967,
7
+ ContainerPrefixAmbiguous = -2147219966,
8
+ ContainerNotFound = -2147219965,
9
+ VolumeNotFound = -2147219964,
10
+ ContainerNotRunning = -2147219963,
11
+ ContainerIsRunning = -2147219962,
12
+ SessionReserved = -2147219961,
13
+ InvalidSessionName = -2147219960,
14
+ NetworkNotFound = -2147219959,
15
+ WindowsUpdateSearchFailed = -2147219958,
16
+ SdkUpdateNeeded = -2147219957,
17
+ ContainerDisabled = -2147219956,
18
+ RegistryBlockedByPolicy = -2147219955,
19
+ VolumeNotAvailable = -2147219954
20
+}
21
+```
doc/docs/api-reference/csharp/enumerations/imageprogressstatus.md
new
+14
@@ -0,0 +1,14 @@
1
+# ImageProgressStatus
2
+
3
+```csharp
4
+public enum ImageProgressStatus
5
+{
6
+ Unknown = 0,
7
+ Pulling = 1,
8
+ Waiting = 2,
9
+ Downloading = 3,
10
+ Verifying = 4,
11
+ Extracting = 5,
12
+ Complete = 6
13
+}
14
+```
doc/docs/api-reference/csharp/enumerations/index.md
new
+18
@@ -0,0 +1,18 @@
1
+# Enumerations
2
+
3
+
4
+## Members
5
+
6
+- [Component](component.md)
7
+- [DeleteContainerOption](deletecontaineroption.md)
8
+- [Error](error.md)
9
+- [ContainerNetworkingMode](containernetworkingmode.md)
10
+- [PortProtocol](portprotocol.md)
11
+- [ContainerState](containerstate.md)
12
+- [Signal](signal.md)
13
+- [ProcessOutputHandle](processoutputhandle.md)
14
+- [ProcessOutputMode](processoutputmode.md)
15
+- [ProcessState](processstate.md)
16
+- [VhdType](vhdtype.md)
17
+- [ImageProgressStatus](imageprogressstatus.md)
18
+- [SessionTerminationReason](sessionterminationreason.md)
doc/docs/api-reference/csharp/enumerations/portprotocol.md
new
+9
@@ -0,0 +1,9 @@
1
+# PortProtocol
2
+
3
+```csharp
4
+public enum PortProtocol
5
+{
6
+ TCP = 0,
7
+ UDP = 1
8
+}
9
+```
doc/docs/api-reference/csharp/enumerations/processoutputhandle.md
new
+11
@@ -0,0 +1,11 @@
1
+# ProcessOutputHandle
2
+
3
+Only stdout/stderr are modeled here. Stdin is accessed through `Process.GetInputStream()`.
4
+
5
+```csharp
6
+public enum ProcessOutputHandle
7
+{
8
+ StandardOutput = 1,
9
+ StandardError = 2
10
+}
11
+```
doc/docs/api-reference/csharp/enumerations/processoutputmode.md
new
+10
@@ -0,0 +1,10 @@
1
+# ProcessOutputMode
2
+
3
+```csharp
4
+public enum ProcessOutputMode
5
+{
6
+ Discard = 0,
7
+ Stream = 1,
8
+ Event = 2
9
+}
10
+```
doc/docs/api-reference/csharp/enumerations/processstate.md
new
+11
@@ -0,0 +1,11 @@
1
+# ProcessState
2
+
3
+```csharp
4
+public enum ProcessState
5
+{
6
+ Unknown = 0,
7
+ Running = 1,
8
+ Exited = 2,
9
+ Signalled = 3
10
+}
11
+```
doc/docs/api-reference/csharp/enumerations/sessionterminationreason.md
new
+10
@@ -0,0 +1,10 @@
1
+# SessionTerminationReason
2
+
3
+```csharp
4
+public enum SessionTerminationReason
5
+{
6
+ Unknown = 0,
7
+ Shutdown = 1,
8
+ Crashed = 2
9
+}
10
+```
doc/docs/api-reference/csharp/enumerations/signal.md
new
+13
@@ -0,0 +1,13 @@
1
+# Signal
2
+
3
+```csharp
4
+public enum Signal
5
+{
6
+ None = 0,
7
+ SIGHUP = 1,
8
+ SIGINT = 2,
9
+ SIGQUIT = 3,
10
+ SIGKILL = 9,
11
+ SIGTERM = 15
12
+}
13
+```
doc/docs/api-reference/csharp/enumerations/vhdtype.md
new
+13
@@ -0,0 +1,13 @@
1
+# VhdType
2
+
3
+```csharp
4
+public enum VhdType
5
+{
6
+ Dynamic = 0,
7
+ Fixed = 1
8
+}
9
+```
10
+
11
+> `wslcsdk.h` notes that `Fixed` is only honored for `WslcCreateSessionVhdVolume`. Session boot-disk requirements use the same underlying struct, but owner flags are explicitly rejected there.
12
+
13
+---
doc/docs/api-reference/csharp/index.md
new
+19
@@ -0,0 +1,19 @@
1
+# WSL container API C# reference
2
+
3
+This document describes the **C# projection** in the `Microsoft.WSL.Containers` namespace.
4
+
5
+---
6
+
7
+## In this reference
8
+
9
+- [Overview](overview.md)
10
+- [Projected Namespace](projected-namespace.md)
11
+- [Common CsWinRT Type Mappings](common-cswinrt-type-mappings.md)
12
+- [Data Classes](data-classes/index.md)
13
+- [Settings Classes](settings-classes/index.md)
14
+- [Core Classes](core-classes/index.md)
15
+- [Service Class](service-class/index.md)
16
+- [Delegates and Events](delegates-and-events.md)
17
+- [Enumerations](enumerations/index.md)
18
+- [Known Gaps](known-gaps.md)
19
+- [End-to-End Example](end-to-end-example.md)
doc/docs/api-reference/csharp/known-gaps.md
new
+12
@@ -0,0 +1,12 @@
1
+# Known Gaps
2
+
3
+These C API features are **not** available through the WinRT/C# projection:
4
+
5
+| C API feature | C# status |
6
+|---|---|
7
+| `WslcImportSessionImage(...)` and `WslcLoadSessionImage(...)` overloads that take raw `HANDLE` + byte count | **Not projected.** C# exposes file-path-based `ImportImage(...)`, `ImportImageAsync(...)`, `LoadImage(...)`, and `LoadImageAsync(...)`. |
8
+| Raw native handles (`WslcGetSessionTerminationEvent`, `WslcGetProcessExitEvent`, `WslcGetProcessIOHandle`) | **Wrapped, not exposed directly.** Use C# events and WinRT streams instead. |
9
+| `WslcProcessCallbacks` registration surface | **Wrapped as events.** Use `OutputReceived`, `ErrorReceived`, and `Exited`. |
10
+| `WslcContainerStartFlags` | **Not exposed directly.** `Container.Start()` automatically sets `ATTACH` when the init process uses `ProcessOutputMode.Event` or `ProcessOutputMode.Stream`. |
11
+
12
+---
doc/docs/api-reference/csharp/overview.md
new
+5
@@ -0,0 +1,5 @@
1
+# Overview
2
+
3
+- The public C# surface mirrors the WinRT surface implemented by the `winrt_*.h` / `winrt_*.cpp` wrappers.
4
+
5
+---
doc/docs/api-reference/csharp/projected-namespace.md
new
+7
@@ -0,0 +1,7 @@
1
+# Projected Namespace
2
+
3
+```csharp
4
+using Microsoft.WSL.Containers;
5
+```
6
+
7
+---
doc/docs/api-reference/csharp/service-class/.pages
new
+4
@@ -0,0 +1,4 @@
1
+title: Service Class
2
+nav:
3
+ - index.md
4
+ - wslcservice.md
doc/docs/api-reference/csharp/service-class/index.md
new
+6
@@ -0,0 +1,6 @@
1
+# Service Class
2
+
3
+
4
+## Members
5
+
6
+- [WslcService](wslcservice.md)
doc/docs/api-reference/csharp/service-class/wslcservice.md
new
+51
@@ -0,0 +1,51 @@
1
+# WslcService
2
+
3
+Static entry point for service-level operations.
4
+
5
+```csharp
6
+public static class WslcService
7
+{
8
+ public static IReadOnlyList<Component> GetMissingComponents();
9
+ public static ServiceVersion GetVersion();
10
+ public static void InstallWithDependencies();
11
+ public static IAsyncActionWithProgress<InstallProgress> InstallWithDependenciesAsync();
12
+}
13
+```
14
+
15
+## WslcService.GetMissingComponents()
16
+
17
+```csharp
18
+IReadOnlyList<Component> missing = WslcService.GetMissingComponents();
19
+if (missing.Count == 0)
20
+{
21
+ Console.WriteLine("All required components are installed.");
22
+}
23
+else
24
+{
25
+ Console.WriteLine($"Missing: {string.Join(", ", missing)}");
26
+}
27
+```
28
+
29
+## WslcService.GetVersion()
30
+
31
+```csharp
32
+ServiceVersion version = WslcService.GetVersion();
33
+Console.WriteLine($"{version.Major}.{version.Minor}.{version.Revision}");
34
+```
35
+
36
+## WslcService.InstallWithDependencies()
37
+
38
+```csharp
39
+WslcService.InstallWithDependencies();
40
+```
41
+
42
+## WslcService.InstallWithDependenciesAsync()
43
+
44
+```csharp
45
+var install = WslcService.InstallWithDependenciesAsync();
46
+install.Progress = (op, progress) =>
47
+ Console.WriteLine($"install: {progress.Component} {progress.Progress}/{progress.Total}");
48
+await install;
49
+```
50
+
51
+---
doc/docs/api-reference/csharp/settings-classes/.pages
new
+10
@@ -0,0 +1,10 @@
1
+title: Settings Classes
2
+nav:
3
+ - index.md
4
+ - sessionsettings.md
5
+ - vhdoptions.md
6
+ - pullimageoptions.md
7
+ - pushimageoptions.md
8
+ - tagimageoptions.md
9
+ - containersettings.md
10
+ - processsettings.md
doc/docs/api-reference/csharp/settings-classes/containersettings.md
new
+58
@@ -0,0 +1,58 @@
1
+# ContainerSettings
2
+
3
+Configures a container before creation.
4
+
5
+```csharp
6
+public sealed class ContainerSettings
7
+{
8
+ public ContainerSettings(string imageName);
9
+
10
+ public string ImageName { get; set; }
11
+ public string Name { get; set; }
12
+ public ProcessSettings InitProcess { get; set; }
13
+ public ContainerNetworkingMode? NetworkingMode { get; set; }
14
+ public string HostName { get; set; }
15
+ public string DomainName { get; set; }
16
+ public bool EnableAutoRemove { get; set; }
17
+ public bool EnableGpu { get; set; }
18
+ public bool Privileged { get; set; }
19
+ public IList<ContainerPortMapping> PortMappings { get; set; }
20
+ public IList<ContainerVolume> Volumes { get; set; }
21
+ public IList<ContainerNamedVolume> NamedVolumes { get; set; }
22
+}
23
+```
24
+
25
+Notes:
26
+- `PortMappings`, `Volumes`, and `NamedVolumes` are mutable collections.
27
+- `InitProcess` is optional.
28
+- `NetworkingMode` is nullable; `null` means “leave default behavior”.
29
+
30
+Example:
31
+
32
+```csharp
33
+var init = new ProcessSettings
34
+{
35
+ CommandLine = new List<string> { "/bin/sh", "-c", "echo hello from init" },
36
+ OutputMode = ProcessOutputMode.Event
37
+};
38
+
39
+var containerSettings = new ContainerSettings("docker.io/library/alpine:latest")
40
+{
41
+ Name = "demo-container",
42
+ InitProcess = init,
43
+ NetworkingMode = ContainerNetworkingMode.Bridged,
44
+ EnableAutoRemove = true,
45
+ PortMappings = new List<ContainerPortMapping>
46
+ {
47
+ new(8080, 80, PortProtocol.TCP)
48
+ },
49
+ Volumes = new List<ContainerVolume>
50
+ {
51
+ new(@"C:\data", "/workspace/data", false)
52
+ },
53
+ NamedVolumes = new List<ContainerNamedVolume>
54
+ {
55
+ new("cache", "/var/cache/app", false)
56
+ }
57
+};
58
+```
doc/docs/api-reference/csharp/settings-classes/index.md
new
+12
@@ -0,0 +1,12 @@
1
+# Settings Classes
2
+
3
+
4
+## Members
5
+
6
+- [SessionSettings](sessionsettings.md)
7
+- [VhdOptions](vhdoptions.md)
8
+- [PullImageOptions](pullimageoptions.md)
9
+- [PushImageOptions](pushimageoptions.md)
10
+- [TagImageOptions](tagimageoptions.md)
11
+- [ContainerSettings](containersettings.md)
12
+- [ProcessSettings](processsettings.md)
doc/docs/api-reference/csharp/settings-classes/processsettings.md
new
+37
@@ -0,0 +1,37 @@
1
+# ProcessSettings
2
+
3
+Configures a process before start.
4
+
5
+```csharp
6
+public sealed class ProcessSettings
7
+{
8
+ public string WorkingDirectory { get; set; }
9
+ public IList<string> CommandLine { get; set; }
10
+ public IDictionary<string, string> EnvironmentVariables { get; set; }
11
+ public ProcessOutputMode OutputMode { get; set; }
12
+}
13
+```
14
+
15
+Notes:
16
+- `CommandLine` must be non-empty before calling `Process.Start()`.
17
+- The init process is started by `Container.Start()`, not by `Process.Start()`.
18
+- `OutputMode.Event` enables `OutputReceived` / `ErrorReceived`.
19
+- `OutputMode.Stream` enables `GetOutputStream(...)`.
20
+
21
+Example:
22
+
23
+```csharp
24
+var processSettings = new ProcessSettings
25
+{
26
+ WorkingDirectory = "/workspace",
27
+ CommandLine = new List<string> { "/bin/sh", "-c", "env | sort" },
28
+ EnvironmentVariables = new Dictionary<string, string>
29
+ {
30
+ ["DEMO"] = "1",
31
+ ["PATH"] = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
32
+ },
33
+ OutputMode = ProcessOutputMode.Event
34
+};
35
+```
36
+
37
+---
doc/docs/api-reference/csharp/settings-classes/pullimageoptions.md
new
+20
@@ -0,0 +1,20 @@
1
+# PullImageOptions
2
+
3
+```csharp
4
+public sealed class PullImageOptions
5
+{
6
+ public PullImageOptions(string uri);
7
+
8
+ public string Uri { get; set; }
9
+ public string RegistryAuth { get; set; }
10
+}
11
+```
12
+
13
+Example:
14
+
15
+```csharp
16
+var pullOptions = new PullImageOptions("docker.io/library/alpine:latest")
17
+{
18
+ RegistryAuth = string.Empty // optional for public registries
19
+};
20
+```
doc/docs/api-reference/csharp/settings-classes/pushimageoptions.md
new
+17
@@ -0,0 +1,17 @@
1
+# PushImageOptions
2
+
3
+```csharp
4
+public sealed class PushImageOptions
5
+{
6
+ public PushImageOptions(string image, string registryAuth);
7
+
8
+ public string Image { get; set; }
9
+ public string RegistryAuth { get; set; }
10
+}
11
+```
12
+
13
+Example:
14
+
15
+```csharp
16
+var pushOptions = new PushImageOptions("registry.example.com/demo:latest", authToken);
17
+```
doc/docs/api-reference/csharp/settings-classes/sessionsettings.md
new
+35
@@ -0,0 +1,35 @@
1
+# SessionSettings
2
+
3
+Configures a session before `Session.Start()`.
4
+
5
+```csharp
6
+public sealed class SessionSettings
7
+{
8
+ public SessionSettings(string name, string storagePath);
9
+
10
+ public string Name { get; set; }
11
+ public string StoragePath { get; set; }
12
+ public uint? CpuCount { get; set; }
13
+ public uint? MemorySizeInMB { get; set; }
14
+ public TimeSpan? Timeout { get; set; }
15
+ public VhdOptions VhdRequirements { get; set; }
16
+ public bool EnableGpu { get; set; }
17
+}
18
+```
19
+
20
+Notes:
21
+- `CpuCount`, `MemorySizeInMB`, and `Timeout` are optional nullable values.
22
+- `Timeout` must be positive and must fit in a `uint32` millisecond count.
23
+- `VhdRequirements` is optional.
24
+
25
+Example:
26
+
27
+```csharp
28
+var sessionSettings = new SessionSettings("demo-session", @"C:\WslcData")
29
+{
30
+ CpuCount = 4,
31
+ MemorySizeInMB = 4096,
32
+ Timeout = TimeSpan.FromMinutes(5),
33
+ EnableGpu = true
34
+};
35
+```
doc/docs/api-reference/csharp/settings-classes/tagimageoptions.md
new
+18
@@ -0,0 +1,18 @@
1
+# TagImageOptions
2
+
3
+```csharp
4
+public sealed class TagImageOptions
5
+{
6
+ public TagImageOptions(string image, string repository, string tag);
7
+
8
+ public string Image { get; set; }
9
+ public string Repository { get; set; }
10
+ public string Tag { get; set; }
11
+}
12
+```
13
+
14
+Example:
15
+
16
+```csharp
17
+var tagOptions = new TagImageOptions("alpine:latest", "registry.example.com/alpine", "v1");
18
+```
doc/docs/api-reference/csharp/settings-classes/vhdoptions.md
new
+29
@@ -0,0 +1,29 @@
1
+# VhdOptions
2
+
3
+Describes a session VHD requirement or a named session VHD volume.
4
+
5
+```csharp
6
+public sealed class VhdOptions
7
+{
8
+ public VhdOptions(string name, ulong size, VhdType type);
9
+
10
+ public string Name { get; set; }
11
+ public ulong Size { get; set; }
12
+ public VhdType Type { get; set; }
13
+ public VhdOwner? Owner { get; set; }
14
+}
15
+```
16
+
17
+Notes:
18
+- Use `SessionSettings.VhdRequirements` for session-level storage requirements.
19
+- Use `Session.CreateVhdVolume(...)` for named session volumes.
20
+- `Owner` is intended for named-volume creation and is rejected on `SessionSettings.VhdRequirements`.
21
+
22
+Example:
23
+
24
+```csharp
25
+var vhd = new VhdOptions("cache", 2UL * 1024 * 1024 * 1024, VhdType.Dynamic)
26
+{
27
+ Owner = new VhdOwner { Uid = 1000, Gid = 1000 }
28
+};
29
+```
doc/docs/api-reference/index.md
new
+23
@@ -0,0 +1,23 @@
1
+# WSL container API developer reference
2
+
3
+The WSL container API lets Windows app developers use Linux containers as part of their app logic. For an overview of the WSL container feature and the `wslc.exe` command-line interface, see [WSL container](https://learn.microsoft.com/windows/wsl/).
4
+
5
+!!! important
6
+
7
+ The WSL container API is currently in **preview** and may have breaking changes in future releases. Please use this preview to evaluate feasibility and then only deploy production grade code once this API goes to general availability in fall 2026.
8
+
9
+
10
+## API reference
11
+
12
+The API is available across the following language projections. Each reference documents the same underlying capabilities, layered as **Session → Container → Process**.
13
+
14
+| Language | Namespace / header | Reference |
15
+|---|---|---|
16
+| C | `wslcsdk.h` (`wslcsdk.lib` / `wslcsdk.dll`) | [C API reference](c/index.md) |
17
+| C# | `Microsoft.WSL.Containers` | [C# API reference](csharp/index.md) |
18
+| C++ | `Microsoft::WSL::Containers` | [C++ API reference](cpp/index.md) |
19
+
20
+## Related content
21
+
22
+- [WSL container](https://learn.microsoft.com/windows/wsl/)
23
+- [Get started with Linux containers](https://learn.microsoft.com/windows/wsl/)
doc/mkdocs.yml
+50
-4
@@ -1,4 +1,5 @@
1
site_name: WSL
2
+site_description: Windows Subsystem for Linux developer and architecture documentation
3
4
nav:
5
- 'Home': 'index.md'
@@ -19,20 +20,65 @@ nav:
20
- 'relay': technical-documentation/relay.md
21
- 'gns': technical-documentation/gns.md
22
- 'localhost': technical-documentation/localhost.md
22
- - 'plan9': technical-documentation/plan9.md
23
+ - 'plan9': technical-documentation/plan9.md
24
- 'Technical documentation':
25
- 'Boot process': technical-documentation/boot-process.md
26
- 'Interop': technical-documentation/interop.md
27
- 'Drvfs & Plan9': technical-documentation/drvfs.md
28
- 'Systemd': technical-documentation/systemd.md
28
-
29
-
29
+ # The API reference tree (docs/api-reference) is appended here; its
30
+ # navigation is driven by the per-folder .pages files (awesome-pages plugin).
31
+ - '...'
32
+
33
plugins:
34
- search
35
+ - awesome-pages
36
- mermaid2:
37
version: 11.4.1
38
arguments:
39
securityLevel: 'loose'
40
41
theme:
38
- name: readthedocs
42
+ name: material
43
+ features:
44
+ - navigation.tracking
45
+ - navigation.sections
46
+ - navigation.top
47
+ - navigation.indexes
48
+ - toc.follow
49
+ - content.code.copy
50
+ - search.suggest
51
+ - search.highlight
52
+ palette:
53
+ - media: "(prefers-color-scheme: light)"
54
+ scheme: default
55
+ primary: indigo
56
+ accent: indigo
57
+ toggle:
58
+ icon: material/weather-night
59
+ name: Switch to dark mode
60
+ - media: "(prefers-color-scheme: dark)"
61
+ scheme: slate
62
+ primary: indigo
63
+ accent: indigo
64
+ toggle:
65
+ icon: material/weather-sunny
66
+ name: Switch to light mode
67
+
68
+markdown_extensions:
69
+ - admonition
70
+ - attr_list
71
+ - md_in_html
72
+ - tables
73
+ - toc:
74
+ permalink: true
75
+ - pymdownx.highlight:
76
+ anchor_linenums: true
77
+ - pymdownx.inlinehilite
78
+ - pymdownx.snippets
79
+ - pymdownx.details
80
+ - pymdownx.superfences:
81
+ custom_fences:
82
+ - name: mermaid
83
+ class: mermaid
84
+ format: !!python/name:mermaid2.fence_mermaid_custom
doc/requirements.txt
new
+5
@@ -0,0 +1,5 @@
1
+# Documentation tooling.
2
+mkdocs>=1.6
3
+mkdocs-material>=9.5
4
+mkdocs-awesome-pages-plugin>=2.9
5
+mkdocs-mermaid2-plugin>=1.1