wslcsdk_sys/
types.rs

1//! Microsoft.WSL.Containers 3.0.1 原始数据结构、枚举与回调函数定义
2
3use core::ffi::c_void;
4use windows_sys::Win32::Foundation::{BOOL, HANDLE};
5use windows_sys::Win32::Networking::WinSock::SOCKADDR_STORAGE;
6use windows_sys::core::HRESULT;
7
8// ==================== 缓冲区尺寸常量 ====================
9
10/// 会话配置不透明结构体字节大小
11pub const WSLC_SESSION_OPTIONS_SIZE: usize = 72;
12/// 会话配置对齐边界
13pub const WSLC_SESSION_OPTIONS_ALIGNMENT: usize = 8;
14
15/// 容器配置不透明结构体字节大小
16pub const WSLC_CONTAINER_OPTIONS_SIZE: usize = 104;
17/// 容器配置对齐边界
18pub const WSLC_CONTAINER_OPTIONS_ALIGNMENT: usize = 8;
19
20/// 进程配置不透明结构体字节大小
21pub const WSLC_CONTAINER_PROCESS_OPTIONS_SIZE: usize = 72;
22/// 进程配置对齐边界
23pub const WSLC_CONTAINER_PROCESS_OPTIONS_ALIGNMENT: usize = 8;
24
25/// 容器 ID 缓冲区长度 (64 字符十六进制 + 空终止符)
26pub const WSLC_CONTAINER_ID_BUFFER_SIZE: usize = 65;
27
28/// 镜像名称最大长度 (255 字符 + 空终止符)
29pub const WSLC_IMAGE_NAME_LENGTH: usize = 256;
30
31// ==================== 不透明句柄与配置结构体 ====================
32
33/// WSLC 会话不透明句柄
34///
35/// 采用 `#[repr(transparent)]` Newtype 包装 `HANDLE`，
36/// 确保与 C ABI 布局完全一致，同时在编译期阻止不同类型句柄的混淆传递。
37#[repr(transparent)]
38#[derive(Copy, Clone, Debug, PartialEq, Eq)]
39pub struct WslcSession(pub HANDLE);
40
41impl WslcSession {
42    /// 空句柄常量
43    pub const NULL: Self = Self(core::ptr::null_mut());
44
45    /// 检查句柄是否为空
46    pub fn is_null(&self) -> bool {
47        self.0.is_null()
48    }
49}
50
51impl Default for WslcSession {
52    fn default() -> Self {
53        Self::NULL
54    }
55}
56
57/// WSLC 容器不透明句柄
58#[repr(transparent)]
59#[derive(Copy, Clone, Debug, PartialEq, Eq)]
60pub struct WslcContainer(pub HANDLE);
61
62impl WslcContainer {
63    /// 空句柄常量
64    pub const NULL: Self = Self(core::ptr::null_mut());
65
66    /// 检查句柄是否为空
67    pub fn is_null(&self) -> bool {
68        self.0.is_null()
69    }
70}
71
72impl Default for WslcContainer {
73    fn default() -> Self {
74        Self::NULL
75    }
76}
77
78/// WSLC 进程不透明句柄
79#[repr(transparent)]
80#[derive(Copy, Clone, Debug, PartialEq, Eq)]
81pub struct WslcProcess(pub HANDLE);
82
83impl WslcProcess {
84    /// 空句柄常量
85    pub const NULL: Self = Self(core::ptr::null_mut());
86
87    /// 检查句柄是否为空
88    pub fn is_null(&self) -> bool {
89        self.0.is_null()
90    }
91}
92
93impl Default for WslcProcess {
94    fn default() -> Self {
95        Self::NULL
96    }
97}
98
99/// 崩溃转储回调订阅不透明句柄
100#[repr(transparent)]
101#[derive(Copy, Clone, Debug, PartialEq, Eq)]
102pub struct WslcCrashDumpSubscription(pub HANDLE);
103
104impl WslcCrashDumpSubscription {
105    /// 空句柄常量
106    pub const NULL: Self = Self(core::ptr::null_mut());
107
108    /// 检查句柄是否为空
109    pub fn is_null(&self) -> bool {
110        self.0.is_null()
111    }
112}
113
114impl Default for WslcCrashDumpSubscription {
115    fn default() -> Self {
116        Self::NULL
117    }
118}
119
120/// 会话初始化配置结构体 (72 字节，8 字节对齐)
121#[repr(C, align(8))]
122#[derive(Copy, Clone, Debug)]
123pub struct WslcSessionSettings {
124    pub(crate) _opaque: [u8; WSLC_SESSION_OPTIONS_SIZE],
125}
126
127impl Default for WslcSessionSettings {
128    fn default() -> Self {
129        Self {
130            _opaque: [0u8; WSLC_SESSION_OPTIONS_SIZE],
131        }
132    }
133}
134
135/// 容器初始化配置结构体 (104 字节，8 字节对齐)
136#[repr(C, align(8))]
137#[derive(Copy, Clone, Debug)]
138pub struct WslcContainerSettings {
139    pub(crate) _opaque: [u8; WSLC_CONTAINER_OPTIONS_SIZE],
140}
141
142impl Default for WslcContainerSettings {
143    fn default() -> Self {
144        Self {
145            _opaque: [0u8; WSLC_CONTAINER_OPTIONS_SIZE],
146        }
147    }
148}
149
150/// 进程初始化配置结构体 (72 字节，8 字节对齐)
151#[repr(C, align(8))]
152#[derive(Copy, Clone, Debug)]
153pub struct WslcProcessSettings {
154    pub(crate) _opaque: [u8; WSLC_CONTAINER_PROCESS_OPTIONS_SIZE],
155}
156
157impl Default for WslcProcessSettings {
158    fn default() -> Self {
159        Self {
160            _opaque: [0u8; WSLC_CONTAINER_PROCESS_OPTIONS_SIZE],
161        }
162    }
163}
164
165// ==================== 枚举定义 ====================
166
167/// 容器网络模式
168#[repr(C)]
169#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
170pub enum WslcContainerNetworkingMode {
171    #[default]
172    None = 0,
173    Bridged = 1,
174}
175
176/// VHD 虚拟磁盘分配类型
177#[repr(C)]
178#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
179pub enum WslcVhdType {
180    #[default]
181    Dynamic = 0,
182    Fixed = 1,
183}
184
185/// VHD 要求标志位
186pub type WslcVhdRequirementsFlags = u32;
187pub const WSLC_VHD_REQ_FLAG_NONE: WslcVhdRequirementsFlags = 0x00000000;
188pub const WSLC_VHD_REQ_FLAG_OWNER: WslcVhdRequirementsFlags = 0x00000001;
189
190/// 会话特性标志位
191pub type WslcSessionFeatureFlags = u32;
192pub const WSLC_SESSION_FEATURE_FLAG_NONE: WslcSessionFeatureFlags = 0x00000000;
193pub const WSLC_SESSION_FEATURE_FLAG_ENABLE_GPU: WslcSessionFeatureFlags = 0x00000004;
194
195/// 会话退出原因枚举
196#[repr(C)]
197#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
198pub enum WslcSessionTerminationReason {
199    #[default]
200    Unknown = 0,
201    Shutdown = 1,
202    Crashed = 2,
203}
204
205/// 端口映射协议类型
206#[repr(C)]
207#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
208pub enum WslcPortProtocol {
209    #[default]
210    Tcp = 0,
211    Udp = 1,
212}
213
214/// 容器特性标志位
215pub type WslcContainerFlags = u32;
216pub const WSLC_CONTAINER_FLAG_NONE: WslcContainerFlags = 0x00000000;
217pub const WSLC_CONTAINER_FLAG_AUTO_REMOVE: WslcContainerFlags = 0x00000001;
218pub const WSLC_CONTAINER_FLAG_ENABLE_GPU: WslcContainerFlags = 0x00000002;
219pub const WSLC_CONTAINER_FLAG_PRIVILEGED: WslcContainerFlags = 0x00000004;
220
221/// 容器启动标志位
222pub type WslcContainerStartFlags = u32;
223pub const WSLC_CONTAINER_START_FLAG_NONE: WslcContainerStartFlags = 0x00000000;
224pub const WSLC_CONTAINER_START_FLAG_ATTACH: WslcContainerStartFlags = 0x00000001;
225
226/// 容器删除标志位
227pub type WslcDeleteContainerFlags = u32;
228pub const WSLC_DELETE_CONTAINER_FLAG_NONE: WslcDeleteContainerFlags = 0x00000000;
229pub const WSLC_DELETE_CONTAINER_FLAG_FORCE: WslcDeleteContainerFlags = 0x00000001;
230
231/// 容器运行状态
232#[repr(C)]
233#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
234pub enum WslcContainerState {
235    #[default]
236    Invalid = 0,
237    Created = 1,
238    Running = 2,
239    Exited = 3,
240    Deleted = 4,
241}
242
243/// Linux 信号枚举
244#[repr(C)]
245#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
246pub enum WslcSignal {
247    #[default]
248    None = 0,
249    Sighup = 1,
250    Sigint = 2,
251    Sigquit = 3,
252    Sigkill = 9,
253    Sigterm = 15,
254}
255
256/// 进程选项标志位
257pub type WslcProcessFlags = u32;
258pub const WSLC_PROCESS_FLAG_NONE: WslcProcessFlags = 0x00000000;
259pub const WSLC_PROCESS_FLAG_STDIN: WslcProcessFlags = 0x00000001;
260
261/// 进程标准 IO 流类型
262#[repr(C)]
263#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
264pub enum WslcProcessIOHandle {
265    #[default]
266    Stdin = 0,
267    Stdout = 1,
268    Stderr = 2,
269}
270
271/// 进程运行状态
272#[repr(C)]
273#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
274pub enum WslcProcessState {
275    #[default]
276    Unknown = 0,
277    Running = 1,
278    Exited = 2,
279    Signalled = 3,
280}
281
282/// 镜像拉取进度阶段状态
283#[repr(C)]
284#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
285pub enum WslcImageProgressStatus {
286    #[default]
287    Unknown = 0,
288    Pulling = 1,
289    Waiting = 2,
290    Downloading = 3,
291    Verifying = 4,
292    Extracting = 5,
293    Complete = 6,
294}
295
296/// 身份认证令牌返回类型
297#[repr(C)]
298#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
299pub enum WslcIdentityTokenType {
300    #[default]
301    Unknown = 0,
302    Token = 1,
303    Credentials = 2,
304}
305
306/// 系统缺失组件标志位
307pub type WslcComponentFlags = u32;
308pub const WSLC_COMPONENT_FLAG_NONE: WslcComponentFlags = 0;
309pub const WSLC_COMPONENT_FLAG_VIRTUAL_MACHINE_PLATFORM: WslcComponentFlags = 1;
310pub const WSLC_COMPONENT_FLAG_WSL_PACKAGE: WslcComponentFlags = 2;
311pub const WSLC_COMPONENT_FLAG_SDK_NEEDS_UPDATE: WslcComponentFlags = 4;
312
313/// 组件安装选项标志位
314pub type WslcInstallOptions = u32;
315pub const WSLC_INSTALL_OPTION_NONE: WslcInstallOptions = 0;
316pub const WSLC_INSTALL_OPTION_REPAIR: WslcInstallOptions = 1;
317
318// ==================== 复合结构体 ====================
319
320/// VHD 规格要求
321#[repr(C)]
322#[derive(Copy, Clone, Debug)]
323pub struct WslcVhdRequirements {
324    pub name: *const i8,
325    pub size_bytes: u64,
326    pub vhd_type: WslcVhdType,
327    pub flags: WslcVhdRequirementsFlags,
328    pub uid: u32,
329    pub gid: u32,
330}
331
332/// 会话崩溃转储信息
333#[repr(C)]
334#[derive(Copy, Clone, Debug)]
335pub struct WslcSessionCrashDumpInfo {
336    pub dump_path: *const u16,
337    pub process_name: *const i8,
338    pub pid: u32,
339    pub signal: u32,
340    pub timestamp: u64,
341}
342
343/// 容器端口映射配置
344#[repr(C)]
345#[derive(Copy, Clone, Debug)]
346pub struct WslcContainerPortMapping {
347    pub windows_port: u16,
348    pub container_port: u16,
349    pub protocol: WslcPortProtocol,
350    pub windows_address: *mut SOCKADDR_STORAGE,
351}
352
353/// 容器目录卷挂载
354#[repr(C)]
355#[derive(Copy, Clone, Debug)]
356pub struct WslcContainerVolume {
357    pub windows_path: *const u16,
358    pub container_path: *const i8,
359    pub read_only: BOOL,
360}
361
362/// 容器具名 VHD 卷挂载
363#[repr(C)]
364#[derive(Copy, Clone, Debug)]
365pub struct WslcContainerNamedVolume {
366    pub name: *const i8,
367    pub container_path: *const i8,
368    pub read_only: BOOL,
369}
370
371/// 镜像拉取字节进度明细
372#[repr(C)]
373#[derive(Copy, Clone, Debug, Default)]
374pub struct WslcImageProgressDetail {
375    pub current_bytes: u64,
376    pub total_bytes: u64,
377}
378
379/// 镜像拉取进度单条消息
380#[repr(C)]
381#[derive(Copy, Clone, Debug)]
382pub struct WslcImageProgressMessage {
383    pub id: *const i8,
384    pub status: WslcImageProgressStatus,
385    pub detail: WslcImageProgressDetail,
386}
387
388/// 镜像元数据信息
389#[repr(C)]
390#[derive(Copy, Clone, Debug)]
391pub struct WslcImageInfo {
392    pub name: [u8; WSLC_IMAGE_NAME_LENGTH],
393    pub sha256: [u8; 32],
394    pub size_bytes: i64,
395    pub created_unix_time: u64,
396}
397
398/// WSLC 系统版本号
399#[repr(C)]
400#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
401pub struct WslcVersion {
402    pub major: u32,
403    pub minor: u32,
404    pub revision: u32,
405}
406
407// ==================== 回调函数指针类型 ====================
408
409/// 会话崩溃转储回调
410pub type WslcSessionCrashDumpCallback =
411    Option<unsafe extern "system" fn(info: *const WslcSessionCrashDumpInfo, context: *mut c_void)>;
412
413/// 进程标准输出/错误读取回调
414pub type WslcStdIOCallback = Option<
415    unsafe extern "system" fn(
416        io_handle: WslcProcessIOHandle,
417        data: *const u8,
418        data_bytes: u32,
419        context: *mut c_void,
420    ),
421>;
422
423/// 进程退出通知回调
424pub type WslcProcessExitCallback =
425    Option<unsafe extern "system" fn(exit_code: i32, context: *mut c_void)>;
426
427/// 进程回调函数集合
428#[repr(C)]
429#[derive(Copy, Clone, Debug, Default)]
430pub struct WslcProcessCallbacks {
431    pub on_stdout: WslcStdIOCallback,
432    pub on_stderr: WslcStdIOCallback,
433    pub on_exit: WslcProcessExitCallback,
434}
435
436/// 镜像拉取/载入进度回调
437pub type WslcContainerImageProgressCallback = Option<
438    unsafe extern "system" fn(
439        progress: *const WslcImageProgressMessage,
440        context: *mut c_void,
441    ) -> HRESULT,
442>;
443
444/// 镜像拉取配置选项
445#[repr(C)]
446#[derive(Copy, Clone, Debug)]
447pub struct WslcPullImageOptions {
448    pub uri: *const i8,
449    pub progress_callback: WslcContainerImageProgressCallback,
450    pub progress_callback_context: *mut c_void,
451    pub registry_auth: *const i8,
452}
453
454/// 镜像导入配置选项
455#[repr(C)]
456#[derive(Copy, Clone, Debug, Default)]
457pub struct WslcImportImageOptions {
458    pub progress_callback: WslcContainerImageProgressCallback,
459    pub progress_callback_context: *mut c_void,
460}
461
462/// 镜像载入配置选项
463#[repr(C)]
464#[derive(Copy, Clone, Debug, Default)]
465pub struct WslcLoadImageOptions {
466    pub progress_callback: WslcContainerImageProgressCallback,
467    pub progress_callback_context: *mut c_void,
468}
469
470/// 镜像打标签配置选项
471#[repr(C)]
472#[derive(Copy, Clone, Debug)]
473pub struct WslcTagImageOptions {
474    pub image: *const i8,
475    pub repo: *const i8,
476    pub tag: *const i8,
477}
478
479/// 镜像推送配置选项
480#[repr(C)]
481#[derive(Copy, Clone, Debug)]
482pub struct WslcPushImageOptions {
483    pub image: *const i8,
484    pub registry_auth: *const i8,
485    pub progress_callback: WslcContainerImageProgressCallback,
486    pub progress_callback_context: *mut c_void,
487}
488
489/// 组件依赖安装进度回调
490pub type WslcInstallCallback = Option<
491    unsafe extern "system" fn(
492        component: WslcComponentFlags,
493        progress_steps: u32,
494        total_steps: u32,
495        context: *mut c_void,
496    ),
497>;
wslcsdk_sys/types.rs

wslcsdk_sys/
types.rs
