| 1 | /*++ |
| 2 | |
| 3 | Copyright (c) Microsoft Corporation. All rights reserved. |
| 4 | |
| 5 | Module Name: |
| 6 | |
| 7 | wslc.idl |
| 8 | |
| 9 | Abstract: |
| 10 | |
| 11 | This file contains the WSLC-related COM object definitions. |
| 12 | // N.B. ABI breaking changes in this file are OK, since both client & server always ship together. |
| 13 | // The WSLC SDK must not use this file, and instead use WSLCCompat.idl |
| 14 | |
| 15 | --*/ |
| 16 | |
| 17 | import "unknwn.idl"; |
| 18 | import "wtypes.idl"; |
| 19 | |
| 20 | // Enums and flags shared with the SDK-facing API (WSLCCompat.idl). |
| 21 | import "WSLCShared.idl"; |
| 22 | |
| 23 | cpp_quote("#ifdef __cplusplus") |
| 24 | cpp_quote("class DECLSPEC_UUID(\"a9b7a1b9-0671-405c-95f1-e0612cb4ce8f\") WSLCSessionManager;") |
| 25 | cpp_quote("class DECLSPEC_UUID(\"9fcd2067-9fc6-4efa-9eb0-698169ebf7d3\") WSLCSessionFactory;") |
| 26 | cpp_quote("#endif") |
| 27 | |
| 28 | #define WSLC_MAX_CONTAINER_NAME_LENGTH 255 |
| 29 | #define WSLC_MAX_IMAGE_NAME_LENGTH 255 |
| 30 | #define WSLC_MAX_VOLUME_NAME_LENGTH 255 |
| 31 | #define WSLC_MAX_VOLUME_DRIVER_LENGTH 255 |
| 32 | #define WSLC_MAX_NETWORK_NAME_LENGTH 255 |
| 33 | #define WSLC_MAX_IMAGE_ID_LENGTH 255 |
| 34 | #define WSLC_CONTAINER_ID_LENGTH 64 |
| 35 | #define WSLC_MAX_BINDING_ADDRESS_LENGTH 45 |
| 36 | #define WSLC_EPHEMERAL_PORT 0 |
| 37 | #define WSLC_MAX_SAVE_IMAGES_COUNT 256 |
| 38 | |
| 39 | cpp_quote("#define WSLC_MAX_CONTAINER_NAME_LENGTH 255") |
| 40 | cpp_quote("#define WSLC_MAX_IMAGE_NAME_LENGTH 255") |
| 41 | cpp_quote("#define WSLC_MAX_VOLUME_NAME_LENGTH 255") |
| 42 | cpp_quote("#define WSLC_MAX_VOLUME_DRIVER_LENGTH 255") |
| 43 | cpp_quote("#define WSLC_MAX_NETWORK_NAME_LENGTH 255") |
| 44 | cpp_quote("#define WSLC_MAX_IMAGE_ID_LENGTH 255") |
| 45 | cpp_quote("#define WSLC_CONTAINER_ID_LENGTH 64") |
| 46 | cpp_quote("#define WSLC_MAX_BINDING_ADDRESS_LENGTH 45") |
| 47 | cpp_quote("#define WSLC_MAX_SAVE_IMAGES_COUNT 256") |
| 48 | cpp_quote("#define WSLC_EPHEMERAL_PORT 0") |
| 49 | cpp_quote("#define WSLC_STOP_TIMEOUT_DEFAULT LONG_MIN") // Pass to Stop() to use the default container stop timeout |
| 50 | cpp_quote("#define WSLC_STOP_TIMEOUT_NONE -1") // Wait forever for the container to stop. |
| 51 | |
| 52 | typedef |
| 53 | struct _WSLCVersion { |
| 54 | ULONG Major; |
| 55 | ULONG Minor; |
| 56 | ULONG Revision; |
| 57 | } WSLCVersion; |
| 58 | |
| 59 | [ |
| 60 | uuid(8C5A7B14-9D26-4FAE-AB31-7E5BC23F4801), |
| 61 | pointer_default(unique), |
| 62 | object |
| 63 | ] |
| 64 | interface ICrashDumpCallback : IUnknown |
| 65 | { |
| 66 | HRESULT OnCrashDump( |
| 67 | [in, string] LPCWSTR DumpPath, |
| 68 | [in, unique, string] LPCSTR ProcessName, |
| 69 | [in] ULONG Pid, |
| 70 | [in] ULONG Signal, |
| 71 | [in] ULONGLONG Timestamp); |
| 72 | }; |
| 73 | |
| 74 | [ |
| 75 | uuid(5038842F-53DB-4F30-A6D0-A41B02C94AC1), |
| 76 | pointer_default(unique), |
| 77 | object |
| 78 | ] |
| 79 | interface IProgressCallback : IUnknown |
| 80 | { |
| 81 | HRESULT OnProgress(LPCSTR Status, LPCSTR Id, ULONGLONG Current, ULONGLONG Total); |
| 82 | }; |
| 83 | |
| 84 | [ |
| 85 | uuid(8153ED5D-8ABB-408B-ADBE-C0F3B13E07C3), |
| 86 | pointer_default(unique), |
| 87 | object |
| 88 | ] |
| 89 | interface IWarningCallback : IUnknown |
| 90 | { |
| 91 | HRESULT OnWarning([in, string] LPCWSTR Message); |
| 92 | }; |
| 93 | |
| 94 | typedef enum _EnumReferenceFormat |
| 95 | { |
| 96 | EnumReferenceFormatNone = 0, |
| 97 | EnumReferenceFormatTag = 1, |
| 98 | EnumReferenceFormatDigest = 2, |
| 99 | } EnumReferenceFormat; |
| 100 | |
| 101 | [ |
| 102 | uuid(7F3B62FD-E1C1-4F69-A8E2-853CAD9051BD), |
| 103 | pointer_default(unique), |
| 104 | object |
| 105 | ] |
| 106 | interface IImageLoadCallback : IUnknown |
| 107 | { |
| 108 | HRESULT OnImageLoaded([in, string] LPCSTR Image, [in] EnumReferenceFormat Format); |
| 109 | }; |
| 110 | |
| 111 | [ |
| 112 | uuid(F3E6D5B2-1D40-4E8B-9C39-7A45D1C0F8A2), |
| 113 | pointer_default(unique), |
| 114 | object |
| 115 | ] |
| 116 | interface IWSLCPluginNotifier : IUnknown |
| 117 | { |
| 118 | // 'InspectJson' follows the wslc_schema::InspectContainer format. |
| 119 | // Returning failure prevents the container creation. |
| 120 | HRESULT OnContainerStarted([in] LPCSTR InspectJson); |
| 121 | |
| 122 | // Called when a container is about to stop. 'ContainerId' is the container identifier. Errors are logged but ignored. |
| 123 | HRESULT OnContainerStopping([in] LPCSTR ContainerId); |
| 124 | |
| 125 | // 'InspectJson' follows the wslc_schema::InspectImage format. Errors are logged but ignored. |
| 126 | HRESULT OnImageCreated([in] LPCSTR InspectJson); |
| 127 | |
| 128 | // Called when an image is deleted. 'ImageId' is the image identifier. Errors are logged but ignored. |
| 129 | HRESULT OnImageDeleted([in] LPCSTR ImageId); |
| 130 | |
| 131 | // Called when the VM backing the session has started (first start or recreation after idle |
| 132 | // teardown). Errors are logged but ignored. |
| 133 | HRESULT OnVmStarted(); |
| 134 | |
| 135 | // Called when the VM backing the session is about to stop. The VM is still running, and is |
| 136 | // committed to stopping: session calls made from this callback are served by it, while any other |
| 137 | // caller waits for the teardown and is served by the next VM. Errors are logged but ignored. |
| 138 | HRESULT OnVmStopping(); |
| 139 | }; |
| 140 | |
| 141 | typedef struct _WSLCImageInformation |
| 142 | { |
| 143 | char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1]; |
| 144 | char Hash[WSLC_MAX_IMAGE_ID_LENGTH + 1]; |
| 145 | char Digest[256]; |
| 146 | LONGLONG Size; // Matches Docker's int64 image size |
| 147 | LONGLONG Created; // Unix timestamp |
| 148 | char ParentId[256]; |
| 149 | LONGLONG Containers; // Number of containers created from the image, or -1 if it wasn't requested |
| 150 | } WSLCImageInformation; |
| 151 | |
| 152 | typedef struct _KeyValuePairInformation |
| 153 | { |
| 154 | [string] LPSTR Key; |
| 155 | [string] LPSTR Value; |
| 156 | } KeyValuePairInformation; |
| 157 | |
| 158 | typedef struct _KeyValuePair |
| 159 | { |
| 160 | [string] LPCSTR Key; |
| 161 | [string] LPCSTR Value; |
| 162 | } KeyValuePair; |
| 163 | |
| 164 | typedef KeyValuePair WSLCLabel; |
| 165 | typedef KeyValuePair WSLCDriverOption; |
| 166 | typedef KeyValuePair WSLCFilter; |
| 167 | |
| 168 | typedef KeyValuePairInformation WSLCLabelInformation; |
| 169 | typedef KeyValuePairInformation WSLCDriverOptionInformation; |
| 170 | |
| 171 | typedef struct _WSLCListImagesOptions |
| 172 | { |
| 173 | DWORD Flags; // WSLCListImagesFlags (can combine with bitwise OR) |
| 174 | [unique, size_is(FiltersCount)] const WSLCFilter* Filters; |
| 175 | ULONG FiltersCount; |
| 176 | } WSLCListImagesOptions; |
| 177 | |
| 178 | typedef struct _WSLCStringArray |
| 179 | { |
| 180 | [unique, size_is(Count)] LPCSTR const* Values; |
| 181 | ULONG Count; |
| 182 | } WSLCStringArray; |
| 183 | |
| 184 | typedef struct _WSLCBuildSecret |
| 185 | { |
| 186 | [string] LPCSTR Id; // Value for docker's --secret id= field. |
| 187 | // For file (src=) secrets: the resolved absolute host path of the secret file. The server mounts the |
| 188 | // file's parent directory into the build VM read-only over virtiofs and references the file in place, |
| 189 | // so the secret bytes are never copied off their original (possibly EFS-encrypted) location. Null for |
| 190 | // env/in-memory secrets. |
| 191 | [string, unique] LPCWSTR SourcePath; |
| 192 | // For env/in-memory secrets: raw secret bytes (never cross into argv). Carried as a counted byte array |
| 193 | // so arbitrary binary content - including embedded NULs - round-trips losslessly; the server writes it |
| 194 | // to a host file exposed to the VM read-only over virtiofs and references it with docker's --secret |
| 195 | // src=. Null for file secrets. |
| 196 | [unique, size_is(ValueSize)] const byte* Value; |
| 197 | ULONG ValueSize; |
| 198 | } WSLCBuildSecret; |
| 199 | |
| 200 | typedef struct _WSLCBuildSecretArray |
| 201 | { |
| 202 | [unique, size_is(Count)] const WSLCBuildSecret* Values; |
| 203 | ULONG Count; |
| 204 | } WSLCBuildSecretArray; |
| 205 | |
| 206 | typedef struct _WSLCProcessOptions |
| 207 | { |
| 208 | [unique] LPCSTR CurrentDirectory; |
| 209 | [unique] LPCSTR User; |
| 210 | WSLCStringArray CommandLine; |
| 211 | WSLCStringArray Environment; |
| 212 | WSLCProcessFlags Flags; |
| 213 | } WSLCProcessOptions; |
| 214 | |
| 215 | typedef struct _WSLCProcessStartOptions |
| 216 | { |
| 217 | ULONG TtyRows; // Only needed when tty fd's are passed. |
| 218 | ULONG TtyColumns; |
| 219 | [unique, string] LPCSTR DetachKeys; |
| 220 | } WSLCProcessStartOptions; |
| 221 | |
| 222 | typedef struct _WSLCNamedVolume |
| 223 | { |
| 224 | LPCSTR Name; |
| 225 | LPCSTR ContainerPath; |
| 226 | BOOL ReadOnly; |
| 227 | } WSLCNamedVolume; |
| 228 | |
| 229 | typedef struct _WSLCVolume |
| 230 | { |
| 231 | LPCWSTR HostPath; |
| 232 | LPCSTR ContainerPath; |
| 233 | BOOL ReadOnly; |
| 234 | } WSLCVolume; |
| 235 | |
| 236 | typedef struct _WSLCPortMapping |
| 237 | { |
| 238 | USHORT HostPort; |
| 239 | USHORT ContainerPort; |
| 240 | int Family; |
| 241 | int Protocol; |
| 242 | char BindingAddress[WSLC_MAX_BINDING_ADDRESS_LENGTH + 1]; |
| 243 | } WSLCPortMapping; |
| 244 | |
| 245 | typedef struct _WSLCTmpfsMount |
| 246 | { |
| 247 | LPCSTR Destination; |
| 248 | [unique] LPCSTR Options; |
| 249 | } WSLCTmpfsMount; |
| 250 | |
| 251 | typedef enum _WSLCMountType |
| 252 | { |
| 253 | WSLCMountTypeBind, |
| 254 | WSLCMountTypeVolume, |
| 255 | WSLCMountTypeTmpfs, |
| 256 | } WSLCMountType; |
| 257 | |
| 258 | typedef enum _WSLCMountSpecFlags |
| 259 | { |
| 260 | WSLCMountSpecFlagsNone = 0, |
| 261 | WSLCMountSpecFlagsTmpfsSize = 1, |
| 262 | WSLCMountSpecFlagsTmpfsMode = 2, |
| 263 | WSLCMountSpecFlagsCreateSourceIfMissing = 4, |
| 264 | } WSLCMountSpecFlags; |
| 265 | |
| 266 | cpp_quote("#define WSLCMountSpecFlagsValid (WSLCMountSpecFlagsTmpfsSize | WSLCMountSpecFlagsTmpfsMode | WSLCMountSpecFlagsCreateSourceIfMissing)") |
| 267 | cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCMountSpecFlags);") |
| 268 | |
| 269 | typedef struct _WSLCMountSpec |
| 270 | { |
| 271 | WSLCMountType Type; |
| 272 | [unique, string] LPCWSTR Source; |
| 273 | [string] LPCSTR Target; |
| 274 | BOOL ReadOnly; |
| 275 | WSLCMountSpecFlags Flags; |
| 276 | LONGLONG TmpfsSizeBytes; |
| 277 | ULONG TmpfsMode; |
| 278 | [unique, string] LPCSTR TmpfsOptions; |
| 279 | } WSLCMountSpec; |
| 280 | |
| 281 | typedef struct _WSLCUlimit |
| 282 | { |
| 283 | [string] LPCSTR Name; |
| 284 | LONGLONG Soft; |
| 285 | LONGLONG Hard; |
| 286 | } WSLCUlimit; |
| 287 | |
| 288 | typedef struct _WSLCNetworkConnection |
| 289 | { |
| 290 | [string] LPCSTR NetworkName; |
| 291 | |
| 292 | // Settings for this endpoint. |
| 293 | // KVP-encoded; duplicate keys are allowed (e.g., multiple "Aliases" entries). |
| 294 | [unique, size_is(SettingsCount)] const KeyValuePair* Settings; |
| 295 | ULONG SettingsCount; |
| 296 | } WSLCNetworkConnection; |
| 297 | |
| 298 | // Options for IWSLCContainer::ConnectToNetwork. |
| 299 | typedef struct _WSLCNetworkConnectionOptions |
| 300 | { |
| 301 | [unique] LPCSTR NetworkName; |
| 302 | // Endpoint settings for the network connection (Aliases, IPAddress, Links, LinkLocalIPs, DriverOpts). |
| 303 | // KVP-encoded; duplicate keys are allowed (e.g., multiple "Aliases" entries). |
| 304 | [unique, size_is(SettingsCount)] const KeyValuePair* Settings; |
| 305 | ULONG SettingsCount; |
| 306 | } WSLCNetworkConnectionOptions; |
| 307 | |
| 308 | typedef struct _WSLCContainerNetwork |
| 309 | { |
| 310 | [unique, string] LPCSTR NetworkMode; |
| 311 | |
| 312 | [unique, size_is(NetworksCount)] const WSLCNetworkConnection* Networks; |
| 313 | ULONG NetworksCount; |
| 314 | |
| 315 | // Settings for the primary endpoint (the network identified by NetworkMode). |
| 316 | // KVP-encoded; duplicate keys are allowed (e.g., multiple "Aliases" entries). |
| 317 | [unique, size_is(SettingsCount)] const KeyValuePair* Settings; |
| 318 | ULONG SettingsCount; |
| 319 | } WSLCContainerNetwork; |
| 320 | |
| 321 | typedef struct _WSLCContainerOptions |
| 322 | { |
| 323 | LPCSTR Image; |
| 324 | [unique] LPCSTR Name; |
| 325 | WSLCStringArray Entrypoint; |
| 326 | WSLCProcessOptions InitProcessOptions; |
| 327 | [unique, size_is(VolumesCount)] WSLCVolume* Volumes; |
| 328 | ULONG VolumesCount; |
| 329 | [unique, size_is(PortsCount)] WSLCPortMapping* Ports; |
| 330 | ULONG PortsCount; |
| 331 | [unique, size_is(LabelsCount)] const WSLCLabel* Labels; |
| 332 | ULONG LabelsCount; |
| 333 | WSLCContainerFlags Flags; |
| 334 | WSLCSignal StopSignal; |
| 335 | // TODO: List specific GPU devices. |
| 336 | [unique] LPCSTR HostName; |
| 337 | [unique] LPCSTR DomainName; |
| 338 | |
| 339 | WSLCStringArray DnsServers; |
| 340 | WSLCStringArray DnsSearchDomains; |
| 341 | WSLCStringArray DnsOptions; |
| 342 | |
| 343 | LONGLONG ShmSize; // Matches Docker's int64 ShmSize; consistent with MemoryBytes/NanoCpus |
| 344 | WSLCContainerNetwork ContainerNetwork; |
| 345 | [unique, size_is(TmpfsCount)] const WSLCTmpfsMount* Tmpfs; |
| 346 | ULONG TmpfsCount; |
| 347 | |
| 348 | [unique, size_is(NamedVolumesCount)] WSLCNamedVolume* NamedVolumes; |
| 349 | ULONG NamedVolumesCount; |
| 350 | |
| 351 | LONGLONG MemoryBytes; |
| 352 | LONGLONG NanoCpus; |
| 353 | [unique, size_is(UlimitsCount)] const WSLCUlimit* Ulimits; |
| 354 | ULONG UlimitsCount; |
| 355 | |
| 356 | // Ignored unless WSLCContainerFlagsStopTimeout is set in Flags. |
| 357 | LONG StopTimeout; |
| 358 | |
| 359 | [unique] LPCSTR HealthCmd; |
| 360 | LONGLONG HealthIntervalNs; |
| 361 | LONGLONG HealthTimeoutNs; |
| 362 | LONGLONG HealthStartPeriodNs; |
| 363 | LONG HealthRetries; |
| 364 | |
| 365 | [unique, size_is(MountsCount)] const WSLCMountSpec* Mounts; |
| 366 | ULONG MountsCount; |
| 367 | } WSLCContainerOptions; |
| 368 | |
| 369 | typedef char WSLCContainerId[WSLC_CONTAINER_ID_LENGTH + 1] ; |
| 370 | |
| 371 | typedef struct _WSLCContainerEntry |
| 372 | { |
| 373 | char Name[WSLC_MAX_CONTAINER_NAME_LENGTH + 1]; |
| 374 | char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1]; |
| 375 | // The runtime imposes no bound on these values, so they are allocated by the callee and freed |
| 376 | // by the caller. Any of them may be null when the container reports no value. |
| 377 | [string] LPSTR Command; |
| 378 | [string] LPSTR Status; |
| 379 | [string] LPSTR Labels; |
| 380 | [string] LPSTR Networks; |
| 381 | [string] LPSTR Mounts; |
| 382 | WSLCContainerId Id; |
| 383 | LONGLONG StateChangedAt; |
| 384 | LONGLONG CreatedAt; |
| 385 | ULONG LocalVolumes; |
| 386 | WSLCContainerState State; |
| 387 | } WSLCContainerEntry; |
| 388 | |
| 389 | typedef struct _WSLCContainerPortMapping |
| 390 | { |
| 391 | WSLCContainerId Id; |
| 392 | WSLCPortMapping PortMapping; |
| 393 | } WSLCContainerPortMapping; |
| 394 | |
| 395 | typedef [system_handle(sh_file)] HANDLE FILE_HANDLE; |
| 396 | typedef [system_handle(sh_pipe)] HANDLE PIPE_HANDLE; |
| 397 | typedef [system_handle(sh_socket)] HANDLE SOCKET_HANDLE; |
| 398 | |
| 399 | typedef struct _WSLCHandle |
| 400 | { |
| 401 | WSLCHandleType Type; |
| 402 | |
| 403 | [switch_type(WSLCHandleType), switch_is(Type)] |
| 404 | union |
| 405 | { |
| 406 | [case(WSLCHandleTypeFile)] |
| 407 | FILE_HANDLE File; |
| 408 | [case(WSLCHandleTypePipe)] |
| 409 | PIPE_HANDLE Pipe; |
| 410 | [case(WSLCHandleTypeSocket)] |
| 411 | SOCKET_HANDLE Socket; |
| 412 | [default]; |
| 413 | } Handle; |
| 414 | } WSLCHandle; |
| 415 | |
| 416 | [ |
| 417 | uuid(1AD163CD-393D-4B33-83A2-8A3F3F23E608), |
| 418 | pointer_default(unique), |
| 419 | object |
| 420 | ] |
| 421 | interface IWSLCProcess : IUnknown |
| 422 | { |
| 423 | HRESULT Signal([in] int Signal); |
| 424 | HRESULT GetExitEvent([out, system_handle(sh_event)] HANDLE* EventHandle); |
| 425 | HRESULT GetStdHandle([in] WSLCFD Fd, [out] WSLCHandle* Handle); |
| 426 | HRESULT GetFlags([out] WSLCProcessFlags* Flags); |
| 427 | HRESULT GetPid([out] int* Pid); |
| 428 | HRESULT GetState([out] WSLCProcessState* State, [out] int* Code); |
| 429 | HRESULT ResizeTty([in] ULONG Rows, [in] ULONG Columns); |
| 430 | |
| 431 | // Note: the SDK can offer a convenience Wait() method, but that doesn't need to be part of the service API. |
| 432 | } |
| 433 | |
| 434 | // |
| 435 | // Values discovered from the guest kernel after the VM has booted, forwarded |
| 436 | // from wslcsession via IWSLCVirtualMachine::ApplyGuestCapabilities. Add new |
| 437 | // fields here instead of new IDL methods so the interface does not need a new |
| 438 | // IID for each kernel-published value. |
| 439 | // |
| 440 | typedef struct _WSLCGuestCapabilities |
| 441 | { |
| 442 | // (base, size) of the hv_pci swiotlb pool the kernel reserved and |
| 443 | // published under /sys/bus/vmbus/drivers/hv_pci/swiotlb_{base,size}. |
| 444 | // Both zero means the running kernel does not support hv_pci swiotlb. |
| 445 | UINT64 HvPciSwiotlbBase; |
| 446 | UINT64 HvPciSwiotlbSize; |
| 447 | } WSLCGuestCapabilities; |
| 448 | |
| 449 | // |
| 450 | // IWSLCVirtualMachine - Interface representing a single VM instance. |
| 451 | // Operations are scoped to this VM. The VM ID is stored internally, |
| 452 | // so only the holder of this interface can operate on the VM. |
| 453 | // |
| 454 | [ |
| 455 | uuid(B5E2D8F1-9A3C-4E6B-8D1F-7C4A2E9B6D3A), |
| 456 | pointer_default(unique), |
| 457 | object |
| 458 | ] |
| 459 | interface IWSLCVirtualMachine : IUnknown |
| 460 | { |
| 461 | // Gets the VM ID. |
| 462 | HRESULT GetId([out, retval] GUID* VmId); |
| 463 | |
| 464 | // Accepts a connect from mini_init in the VM. |
| 465 | HRESULT AcceptConnection([out, system_handle(sh_socket)] HANDLE* Socket); |
| 466 | |
| 467 | // Configures networking engine with sockets from the user process. |
| 468 | // GnsSocket is required; DnsSocket is optional (NULL if DNS tunneling is disabled). |
| 469 | // The service duplicates the socket handles. |
| 470 | HRESULT ConfigureNetworking( |
| 471 | [in, system_handle(sh_socket)] HANDLE GnsSocket, |
| 472 | [in, system_handle(sh_socket), unique] HANDLE* DnsSocket); |
| 473 | |
| 474 | // Attaches a VHD or VHDX disk to the VM. |
| 475 | // GrantVmAccess is called by the service before attaching. |
| 476 | // Returns the SCSI LUN assigned to the disk. |
| 477 | HRESULT AttachDisk([in] LPCWSTR Path, [in] BOOL ReadOnly, [out, retval] ULONG* Lun); |
| 478 | |
| 479 | // Detaches a previously attached disk from the VM. |
| 480 | HRESULT DetachDisk([in] ULONG Lun); |
| 481 | |
| 482 | // Adds a filesystem share (Plan9 or VirtioFS) accessible to the VM. |
| 483 | // Returns an instance GUID that can be used to remove the share. |
| 484 | HRESULT AddShare([in] LPCWSTR WindowsPath, [in] BOOL ReadOnly, [out, retval] GUID* ShareId); |
| 485 | |
| 486 | // Removes a previously added filesystem share. |
| 487 | HRESULT RemoveShare([in] REFGUID ShareId); |
| 488 | |
| 489 | // Configures the per-VM state discovered from the guest kernel after boot |
| 490 | // (currently the hv_pci swiotlb pool). Non-zero values are forwarded to |
| 491 | // wsldevicehost before virtiofs shares or Consomme networking devices are |
| 492 | // created. A capabilities struct whose fields are all zero means the guest |
| 493 | // kernel does not support the feature. |
| 494 | HRESULT ApplyGuestCapabilities([in] const WSLCGuestCapabilities* Capabilities); |
| 495 | |
| 496 | // Returns an event that is signaled when the VM exits (graceful or forced). |
| 497 | HRESULT GetTerminationEvent([out, system_handle(sh_event)] HANDLE* Event); |
| 498 | |
| 499 | HRESULT MapVirtioNetPort( |
| 500 | [in] USHORT HostPort, |
| 501 | [in] USHORT GuestPort, |
| 502 | [in] int Protocol, |
| 503 | [in] LPCSTR ListenAddress, |
| 504 | [out, retval] USHORT* AllocatedHostPort); |
| 505 | |
| 506 | // Unmaps a port previously mapped via MapVirtioNetPort. |
| 507 | HRESULT UnmapVirtioNetPort( |
| 508 | [in] USHORT HostPort, |
| 509 | [in] USHORT GuestPort, |
| 510 | [in] int Protocol, |
| 511 | [in] LPCSTR ListenAddress); |
| 512 | |
| 513 | // Returns the cached termination reason and details. These are only available after the |
| 514 | // termination event has been signaled; before that the call fails. |
| 515 | HRESULT GetTerminationReason([out] WSLCVirtualMachineTerminationReason* Reason, [out] LPWSTR* Details); |
| 516 | } |
| 517 | |
| 518 | // |
| 519 | // IWSLCVirtualMachineFactory - Creates VMs on demand for a session. |
| 520 | // |
| 521 | // Held by the per-user session process and implemented by the SYSTEM service. |
| 522 | // This lets the session create a fresh VM at any time (e.g. to recreate a VM that |
| 523 | // was idle-terminated when it had no running containers), instead of the service |
| 524 | // eagerly creating a single VM up front. Each successful call returns a new VM whose |
| 525 | // lifetime is owned by the caller: releasing the IWSLCVirtualMachine tears it down. |
| 526 | // |
| 527 | [ |
| 528 | uuid(2E3C9A41-7D58-4B6E-9F12-6C4A2E9B6D3B), |
| 529 | pointer_default(unique), |
| 530 | object |
| 531 | ] |
| 532 | interface IWSLCVirtualMachineFactory : IUnknown |
| 533 | { |
| 534 | // Creates a new VM using the settings captured at session creation time. |
| 535 | HRESULT CreateVirtualMachine([out] IWSLCVirtualMachine** Vm); |
| 536 | } |
| 537 | |
| 538 | // Settings for IWSLCSessionManager::CreateSession - full session configuration |
| 539 | typedef struct _WSLCSessionSettings { |
| 540 | LPCWSTR DisplayName; |
| 541 | LPCWSTR StoragePath; |
| 542 | ULONGLONG MaximumStorageSizeMb; |
| 543 | ULONG CpuCount; |
| 544 | ULONG MemoryMb; |
| 545 | ULONG BootTimeoutMs; |
| 546 | WSLCNetworkingMode NetworkingMode; |
| 547 | WSLCFeatureFlags FeatureFlags; |
| 548 | [unique] LPCSTR HostLoopback; |
| 549 | WSLCHandle DmesgOutput; |
| 550 | WSLCSessionStorageFlags StorageFlags; |
| 551 | ULONG IdleTimeoutSec; |
| 552 | |
| 553 | // Below options are used for debugging purposes only. |
| 554 | [unique] LPCWSTR RootVhdOverride; |
| 555 | [unique] LPCSTR RootVhdTypeOverride; |
| 556 | } WSLCSessionSettings; |
| 557 | |
| 558 | |
| 559 | [ |
| 560 | uuid(7577FE8D-DE85-471E-B870-11669986F332), |
| 561 | pointer_default(unique), |
| 562 | object |
| 563 | ] |
| 564 | interface IWSLCContainer : IUnknown |
| 565 | { |
| 566 | HRESULT Attach([in, unique] LPCSTR DetachKeys, [out] WSLCHandle* StdIn, [out] WSLCHandle* StdOut, [out] WSLCHandle* StdErr); |
| 567 | HRESULT Stop([in] WSLCSignal Signal, [in] LONG TimeoutSeconds); |
| 568 | HRESULT Start([in] WSLCContainerStartFlags Flags, [in, unique] const WSLCProcessStartOptions* StartOptions, [in, unique] IWarningCallback* WarningCallback); |
| 569 | HRESULT Delete([in] WSLCDeleteFlags Flags); |
| 570 | HRESULT Export([in] WSLCHandle TarHandle); |
| 571 | HRESULT GetState([out] WSLCContainerState* State); |
| 572 | HRESULT GetInitProcess([out] IWSLCProcess** Process); |
| 573 | HRESULT Exec([in, ref] const WSLCProcessOptions* Options, [in, unique] const WSLCProcessStartOptions* StartOptions, [out] IWSLCProcess** Process); |
| 574 | HRESULT Inspect([in] BOOL Size, [out] LPSTR* Output); |
| 575 | HRESULT Logs([in] WSLCLogsFlags Flags, [out] WSLCHandle* Stdout, [out] WSLCHandle* Stderr, [in] LONGLONG Since, [in] LONGLONG Until, [in] ULONGLONG Tail); |
| 576 | HRESULT GetId([out, string] WSLCContainerId Id); |
| 577 | HRESULT GetName([out, string] LPSTR* Name); |
| 578 | HRESULT GetLabels([out, size_is(, *Count)] WSLCLabelInformation** Labels, [out] ULONG* Count); |
| 579 | HRESULT Kill([in] WSLCSignal Signal); |
| 580 | HRESULT Stats([out] LPSTR* Output); |
| 581 | HRESULT ConnectToNetwork([in] const WSLCNetworkConnectionOptions* Options); |
| 582 | HRESULT DisconnectFromNetwork([in] LPCSTR NetworkName); |
| 583 | HRESULT UploadArchive([in] WSLCHandle TarHandle, [in, string] LPCSTR DestPath, [in] ULONGLONG ContentSize); |
| 584 | HRESULT DownloadArchive([in, string] LPCSTR SrcPath, [in] WSLCHandle OutHandle); |
| 585 | HRESULT Restart([in] WSLCSignal Signal, [in] LONG TimeoutSeconds, [in, unique] IWarningCallback* WarningCallback); |
| 586 | } |
| 587 | |
| 588 | typedef struct _WSLCDeletedImageInformation |
| 589 | { |
| 590 | char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1]; |
| 591 | WSLCDeletedImageType Type; |
| 592 | } WSLCDeletedImageInformation; |
| 593 | |
| 594 | typedef struct _WSLCDeleteImageOptions |
| 595 | { |
| 596 | LPCSTR Image; // Image can be ID or Repo:Tag. |
| 597 | DWORD Flags; // WSLCDeleteImageFlags |
| 598 | // TODO: Platforms: a json array of OCI platform strings. |
| 599 | } WSLCDeleteImageOptions; |
| 600 | |
| 601 | typedef struct _WSLCBuildImageOptions |
| 602 | { |
| 603 | LPCWSTR ContextPath; |
| 604 | WSLCHandle DockerfileHandle; |
| 605 | WSLCStringArray Tags; |
| 606 | WSLCStringArray BuildArgs; // KEY=VALUE pairs passed as --build-arg to docker. |
| 607 | LPCSTR Target; // Target build stage name passed as --target to docker. |
| 608 | WSLCBuildImageFlags Flags; // WSLCBuildImageFlags |
| 609 | WSLCStringArray Labels; // KEY=VALUE pairs passed as --label to docker. |
| 610 | WSLCBuildSecretArray Secrets; // --secret entries; the server writes each secret's bytes to a host file exposed to the VM read-only over virtiofs and emits the corresponding id=...,src=... spec. |
| 611 | [unique, string] LPCSTR Output; // buildx exporter spec passed as --output to docker build (e.g. type=tar, type=oci). The client omits dest= for exporters with a client destination; the server rewrites it to a VM temp path (streamed back over OutputHandle) or into the OutputMountPath mount (single-file exporters with a real destination). Directory exporters (type=local, or oci/docker with tar=false) are not supported. |
| 612 | WSLCHandle OutputHandle; // When Type != WSLCHandleTypeUnknown, the server streams the single-file exporter output (a tar/oci/docker tarball, or dest=- stdout) to this handle after a successful build. |
| 613 | [unique, string] LPCWSTR OutputMountPath; // When set, the server mounts this Windows directory read-write into the VM and points the exporter's dest at it (plus OutputMountFile). Used for single-file exporters with a real destination; mutually exclusive with OutputHandle. |
| 614 | [unique, string] LPCWSTR OutputMountFile; // Leaf filename within OutputMountPath that a single-file exporter writes to. |
| 615 | [unique, string] LPCWSTR IidFilePath; // Absolute path of the client's --iidfile destination. The server mounts its parent directory read-write into the VM and passes --iidfile pointing at it, so buildx writes the image ID straight to the destination. |
| 616 | } WSLCBuildImageOptions; |
| 617 | |
| 618 | typedef struct _WSLCTagImageOptions |
| 619 | { |
| 620 | LPCSTR Image; // Source image name or ID. |
| 621 | LPCSTR Repo; // Target repository name. |
| 622 | LPCSTR Tag; // Target tag name. |
| 623 | } WSLCTagImageOptions; |
| 624 | |
| 625 | typedef struct _WSLCVolumeOptions |
| 626 | { |
| 627 | [unique] LPCSTR Name; |
| 628 | [unique] LPCSTR Driver; |
| 629 | [unique, size_is(DriverOptsCount)] const WSLCDriverOption* DriverOpts; |
| 630 | ULONG DriverOptsCount; |
| 631 | [unique, size_is(LabelsCount)] const WSLCLabel* Labels; |
| 632 | ULONG LabelsCount; |
| 633 | } WSLCVolumeOptions; |
| 634 | |
| 635 | typedef char WSLCVolumeName[WSLC_MAX_VOLUME_NAME_LENGTH + 1]; |
| 636 | |
| 637 | typedef struct _WSLCVolumeInformation |
| 638 | { |
| 639 | WSLCVolumeName Name; |
| 640 | char Driver[WSLC_MAX_VOLUME_DRIVER_LENGTH + 1]; |
| 641 | } WSLCVolumeInformation; |
| 642 | |
| 643 | typedef struct _WSLCNetworkOptions |
| 644 | { |
| 645 | LPCSTR Name; |
| 646 | [unique] LPCSTR Driver; |
| 647 | [unique, size_is(DriverOptsCount)] const WSLCDriverOption* DriverOpts; |
| 648 | ULONG DriverOptsCount; |
| 649 | [unique, size_is(LabelsCount)] const WSLCLabel* Labels; |
| 650 | ULONG LabelsCount; |
| 651 | BOOL Internal; |
| 652 | [unique] LPCSTR Subnet; |
| 653 | [unique] LPCSTR Gateway; |
| 654 | [unique] LPCSTR IpRange; |
| 655 | } WSLCNetworkOptions; |
| 656 | |
| 657 | typedef char WSLCNetworkName[WSLC_MAX_NETWORK_NAME_LENGTH + 1]; |
| 658 | |
| 659 | typedef struct _WSLCPruneContainersResults |
| 660 | { |
| 661 | [unique, size_is(ContainersCount)] WSLCContainerId* Containers; |
| 662 | ULONG ContainersCount; |
| 663 | ULONGLONG SpaceReclaimed; |
| 664 | } WSLCPruneContainersResults; |
| 665 | |
| 666 | typedef struct _WSLCListContainersOptions |
| 667 | { |
| 668 | DWORD Flags; // WSLCListContainersFlags |
| 669 | LONG Limit; |
| 670 | |
| 671 | [unique, size_is(FiltersCount)] const WSLCFilter* Filters; |
| 672 | ULONG FiltersCount; |
| 673 | } WSLCListContainersOptions; |
| 674 | |
| 675 | [ |
| 676 | uuid(7EC66D3B-D098-4D48-B69E-69166F6C4745), |
| 677 | pointer_default(unique), |
| 678 | object |
| 679 | ] |
| 680 | interface IWSLCEventStream : IUnknown |
| 681 | { |
| 682 | // Blocks until the next matching event, the until-time is reached, or the session terminates, |
| 683 | // then returns the event as a JSON object following the wslc_schema::Event format. |
| 684 | HRESULT GetNext([out, string] LPSTR* EventJson); |
| 685 | } |
| 686 | |
| 687 | // Settings for IWSLCSession::Initialize - passed from service to per-user process |
| 688 | typedef struct _WSLCSessionInitSettings |
| 689 | { |
| 690 | ULONG SessionId; |
| 691 | [unique] LPCWSTR CreatorProcessName; |
| 692 | LPCWSTR DisplayName; |
| 693 | LPCWSTR StoragePath; |
| 694 | WSLCSessionStorageFlags StorageFlags; |
| 695 | ULONGLONG MaximumStorageSizeMb; |
| 696 | ULONG SwapSizeMb; |
| 697 | ULONG BootTimeoutMs; |
| 698 | WSLCNetworkingMode NetworkingMode; |
| 699 | WSLCFeatureFlags FeatureFlags; |
| 700 | [unique] LPCSTR RootVhdTypeOverride; |
| 701 | ULONG IdleTimeoutSec; |
| 702 | } WSLCSessionInitSettings; |
| 703 | |
| 704 | [ |
| 705 | uuid(EF0661E4-6364-40EA-B433-E2FDF11F3519), |
| 706 | pointer_default(unique), |
| 707 | object |
| 708 | ] |
| 709 | interface IWSLCSession : IUnknown |
| 710 | { |
| 711 | HRESULT GetId([out] ULONG* Id); |
| 712 | HRESULT GetDisplayName([out] LPWSTR* DisplayName); |
| 713 | HRESULT GetState([out] WSLCSessionState* State); |
| 714 | |
| 715 | // Returns a one-off event that is signaled when the session terminates, whether due to an |
| 716 | // explicit Terminate() call or an unexpected VM exit. The returned handle is owned by the |
| 717 | // caller and remains valid (and observes the signaled state) even after the session is released. |
| 718 | HRESULT GetTerminationEvent([out, system_handle(sh_event)] HANDLE* Event); |
| 719 | |
| 720 | // Returns the cached termination reason and details. These are only available after the |
| 721 | // termination event has been signaled; before that the call fails. |
| 722 | HRESULT GetTerminationReason([out] WSLCVirtualMachineTerminationReason* Reason, [out] LPWSTR* Details); |
| 723 | |
| 724 | // Opens an event stream that mirrors `docker events`. The window and filters are captured by the |
| 725 | // returned stream object; events are then pulled one at a time via IWSLCEventStream::GetNext. |
| 726 | // SinceTime / UntilTime bound the window by event time, in seconds since the Unix epoch. SinceTime |
| 727 | // is inclusive and UntilTime is exclusive. 0 means unbounded on that end. |
| 728 | // Filters are key/value pairs. Values sharing a key are OR'd, distinct keys are AND'd. |
| 729 | HRESULT GetEvents( |
| 730 | [in] LONGLONG SinceTime, |
| 731 | [in] LONGLONG UntilTime, |
| 732 | [in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, |
| 733 | [in] ULONG FiltersCount, |
| 734 | [out] IWSLCEventStream** Stream); |
| 735 | |
| 736 | // Image management. |
| 737 | HRESULT PullImage([in] LPCSTR Image, [in, unique] LPCSTR RegistryAuthenticationInformation, [in, unique] IProgressCallback* ProgressCallback, [in, unique] IWarningCallback* WarningCallback); |
| 738 | HRESULT BuildImage([in] const WSLCBuildImageOptions* Options, [in, unique] IProgressCallback* ProgressCallback, [in, unique, system_handle(sh_event)] HANDLE CancelEvent); |
| 739 | HRESULT LoadImage([in] WSLCHandle ImageHandle, [in] ULONGLONG ContentLength, [in, unique] IWarningCallback* WarningCallback, [in, unique] IImageLoadCallback* LoadCallback); |
| 740 | HRESULT ImportImage([in] WSLCHandle ImageHandle, [in, unique] LPCSTR ImageName, [in] ULONGLONG ContentLength, [in, unique] IWarningCallback* WarningCallback, [out] LPSTR* ImageId); |
| 741 | HRESULT SaveImage([in] WSLCHandle OutputHandle, [in] LPCSTR ImageNameOrID, [in, unique] IProgressCallback * ProgressCallback, [in, unique, system_handle(sh_event)] HANDLE CancelEvent); |
| 742 | HRESULT SaveImages([in] WSLCHandle OutputHandle, [in] const WSLCStringArray* ImageNames, [in, unique] IProgressCallback * ProgressCallback, [in, unique, system_handle(sh_event)] HANDLE CancelEvent); |
| 743 | HRESULT ListImages([in, unique] const WSLCListImagesOptions* Options, [out, size_is(, *Count)] WSLCImageInformation** Images, [out] ULONG* Count); |
| 744 | HRESULT DeleteImage([in] const WSLCDeleteImageOptions* Options, [out, size_is(, *Count)] WSLCDeletedImageInformation** DeletedImages, [out] ULONG* Count); |
| 745 | HRESULT TagImage([in] const WSLCTagImageOptions* Options); |
| 746 | HRESULT InspectImage([in] LPCSTR ImageNameOrId, [out] LPSTR* Output); |
| 747 | HRESULT PruneImages([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out, size_is(, *DeletedImagesCount)] WSLCDeletedImageInformation** DeletedImages, [out] ULONG* DeletedImagesCount, [out] ULONGLONG* SpaceReclaimed); |
| 748 | |
| 749 | // Container management. |
| 750 | HRESULT CreateContainer([in] const WSLCContainerOptions* Options, [in, unique] IWarningCallback* WarningCallback, [out] IWSLCContainer** Container); |
| 751 | HRESULT OpenContainer([in, ref] LPCSTR Id, [out] IWSLCContainer** Container); |
| 752 | HRESULT ListContainers([in, unique] const WSLCListContainersOptions* Options,[out, size_is(, *Count)] WSLCContainerEntry** Containers,[out] ULONG* Count, [out, size_is(, *PortsCount)] WSLCContainerPortMapping** Ports, [out] ULONG* PortsCount); |
| 753 | HRESULT PruneContainers([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out] WSLCPruneContainersResults* Result); |
| 754 | |
| 755 | // Create a process at the VM level. This is meant for debugging. |
| 756 | // 'AcquireVmLease' controls whether the call may bring a VM up. TRUE is the normal client |
| 757 | // behaviour: start the VM if there is none, and wait out an announced stop so the call is served |
| 758 | // by a fresh VM. FALSE is what the service passes for plugin-originated calls: the call is served |
| 759 | // by whatever VM is already running -- including one committed to stopping, which is what lets a |
| 760 | // plugin do last-minute work from its OnVmStopping handler without deadlocking against the |
| 761 | // teardown it is blocking -- and fails with WSLC_E_VM_NOT_RUNNING when there is no VM. |
| 762 | HRESULT CreateRootNamespaceProcess([in, ref] LPCSTR Executable, [in, ref] const WSLCProcessOptions* Options, [in] ULONG TtyRows, [in] ULONG TtyColumns, [in] BOOL AcquireVmLease, [out] IWSLCProcess** Process, [out] int* Errno); |
| 763 | |
| 764 | // TODO: an OpenProcess() method can be added later if needed. |
| 765 | |
| 766 | // Disk management. |
| 767 | HRESULT FormatVirtualDisk([in, ref] LPCWSTR Path); |
| 768 | |
| 769 | // Terminate the VM and containers. |
| 770 | HRESULT Terminate(); |
| 771 | |
| 772 | // Used only for testing (and by the plugin API). TODO: Think about moving them to a dedicated |
| 773 | // testing-only interface. See CreateRootNamespaceProcess for 'AcquireVmLease'. |
| 774 | HRESULT MountWindowsFolder([in, ref] LPCWSTR WindowsPath, [in, ref] LPCSTR LinuxPath, [in] BOOL ReadOnly, [in] BOOL AcquireVmLease); |
| 775 | HRESULT UnmountWindowsFolder([in, ref] LPCSTR LinuxPath, [in] BOOL AcquireVmLease); |
| 776 | HRESULT MapVmPort([in] int Family, [in] unsigned short WindowsPort, [in] unsigned short LinuxPort); |
| 777 | HRESULT UnmapVmPort([in] int Family, [in] unsigned short WindowsPort, [in] unsigned short LinuxPort); |
| 778 | |
| 779 | // Session initialization - called by SYSTEM service after launching per-user process. |
| 780 | // Returns a handle to this COM server process (used to add to job object). |
| 781 | HRESULT GetProcessHandle([out, system_handle(sh_process)] HANDLE* ProcessHandle); |
| 782 | |
| 783 | // Initializes the session with a VM factory. VMs are created through the factory. |
| 784 | HRESULT Initialize( |
| 785 | [in] const WSLCSessionInitSettings* Settings, |
| 786 | [in] IWSLCVirtualMachineFactory* VmFactory, |
| 787 | [in] IWSLCPluginNotifier* PluginNotifier, |
| 788 | [in, unique] IWarningCallback* WarningCallback); |
| 789 | |
| 790 | // Volume management. |
| 791 | HRESULT CreateVolume([in] const WSLCVolumeOptions* Options, [out] WSLCVolumeInformation* VolumeInfo); |
| 792 | HRESULT DeleteVolume([in] LPCSTR Name); |
| 793 | HRESULT ListVolumes([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out] LPSTR* Output); |
| 794 | HRESULT InspectVolume([in] LPCSTR Name, [out] LPSTR* Output); |
| 795 | |
| 796 | HRESULT Authenticate([in] LPCSTR ServerAddress, [in] LPCSTR Username, [in] LPCSTR Password, [out] LPSTR* IdentityToken); |
| 797 | HRESULT PushImage([in] LPCSTR Image, [in] LPCSTR RegistryAuthenticationInformation, [in, unique] IProgressCallback* ProgressCallback, [in, unique] IWarningCallback* WarningCallback); |
| 798 | HRESULT PruneVolumes([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [in, unique] IWarningCallback* WarningCallback, [out, size_is(, *VolumesCount)] WSLCVolumeName** Volumes, [out] ULONG* VolumesCount, [out] ULONGLONG* SpaceReclaimed); |
| 799 | |
| 800 | // Network management. |
| 801 | HRESULT CreateNetwork([in] const WSLCNetworkOptions* Options, [in, unique] IWarningCallback* WarningCallback); |
| 802 | HRESULT DeleteNetwork([in] LPCSTR Name); |
| 803 | // Returns a JSON array of wslc_schema::NetworkListEntry objects describing the session's networks. |
| 804 | HRESULT ListNetworks([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out] LPSTR* Output); |
| 805 | HRESULT InspectNetwork([in] LPCSTR Name, [out] LPSTR* Output); |
| 806 | HRESULT PruneNetworks([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out, size_is(, *NetworksCount)] WSLCNetworkName** Networks, [out] ULONG* NetworksCount); |
| 807 | |
| 808 | HRESULT RegisterCrashDumpCallback([in] ICrashDumpCallback* Callback, [out] IUnknown** Subscription); |
| 809 | |
| 810 | // Used only for testing. Synchronously runs the idle-termination teardown path. The production |
| 811 | // activity-count and persistent-storage guards are honored, so an active container keeps the VM |
| 812 | // alive and a tmpfs-backed session is never torn down. |
| 813 | // WasAlreadyIdle is TRUE when the VM was not running. |
| 814 | HRESULT TriggerIdleTermination([out] BOOL* WasAlreadyIdle); |
| 815 | |
| 816 | // Keeps the VM alive for the duration of a client-side container operation. The CLI performs |
| 817 | // each mutation as two round-trips (OpenContainer followed by the operation) and may stream |
| 818 | // output afterwards. With on-demand VM idle-termination the VM could otherwise tear down |
| 819 | // between those calls, disconnecting the container wrapper and failing the second call with |
| 820 | // RPC_E_DISCONNECTED. The client holds the returned token for the whole operation; releasing |
| 821 | // it (or the client exiting) lets the VM idle-terminate again. |
| 822 | HRESULT BeginContainerOperation([out] IUnknown** Operation); |
| 823 | } |
| 824 | |
| 825 | // |
| 826 | // IWSLCSessionReference - Weak reference to a session held by the SYSTEM service. |
| 827 | // Stored in per-user process, allows service to check liveness and terminate sessions. |
| 828 | // Session metadata (ID, name, etc.) is stored service-side in SessionEntry. |
| 829 | // |
| 830 | [ |
| 831 | uuid(B3A72F48-9D15-4E8A-A621-7C3E84F09B52), |
| 832 | pointer_default(unique), |
| 833 | object |
| 834 | ] |
| 835 | interface IWSLCSessionReference : IUnknown |
| 836 | { |
| 837 | // Try to open the session. Fails if session was released or terminated. |
| 838 | // Returns S_OK and a valid session if still alive. |
| 839 | HRESULT OpenSession([out] IWSLCSession** Session); |
| 840 | |
| 841 | // Terminate the session if still alive. |
| 842 | HRESULT Terminate(); |
| 843 | } |
| 844 | |
| 845 | // |
| 846 | // IWSLCSessionFactory - Creates sessions in the per-user COM server process. |
| 847 | // Called by the SYSTEM service via CoCreateInstanceAsUser. |
| 848 | // |
| 849 | [ |
| 850 | uuid(C4E8F291-3B5D-4A7C-9E12-8F6A4D2B7C91), |
| 851 | pointer_default(unique), |
| 852 | object |
| 853 | ] |
| 854 | interface IWSLCSessionFactory : IUnknown |
| 855 | { |
| 856 | // Creates a new session and returns both the session interface and a service reference. |
| 857 | HRESULT CreateSession( |
| 858 | [in] const WSLCSessionInitSettings* Settings, |
| 859 | [in] IWSLCVirtualMachineFactory* VmFactory, |
| 860 | [in] IWSLCPluginNotifier* PluginNotifier, |
| 861 | [in, unique] IWarningCallback* WarningCallback, |
| 862 | [out] IWSLCSession** Session, |
| 863 | [out] IWSLCSessionReference** ServiceRef); |
| 864 | |
| 865 | // Gets the process handle for adding to job object. |
| 866 | HRESULT GetProcessHandle([out, system_handle(sh_process)] HANDLE* ProcessHandle); |
| 867 | } |
| 868 | |
| 869 | typedef struct _WSLCSessionListEntry |
| 870 | { |
| 871 | ULONG SessionId; |
| 872 | DWORD CreatorPid; |
| 873 | wchar_t DisplayName[256]; |
| 874 | wchar_t Sid[256 + 1]; // MAX_SID_SIZE = 256 |
| 875 | } WSLCSessionListEntry; |
| 876 | |
| 877 | [ |
| 878 | uuid(82A7ABC8-6B50-43FC-AB96-15FBBE7E8760), |
| 879 | pointer_default(unique), |
| 880 | object |
| 881 | ] |
| 882 | interface IWSLCSessionManager : IUnknown |
| 883 | { |
| 884 | HRESULT GetVersion([out] WSLCVersion* Version); |
| 885 | // Session management. |
| 886 | HRESULT CreateSession([in, unique] const WSLCSessionSettings* Settings, WSLCSessionFlags Flags, [in, unique] IWarningCallback* WarningCallback, [out] IWSLCSession** Session); |
| 887 | HRESULT EnterSession([in, ref] LPCWSTR DisplayName, [in, ref] LPCWSTR StoragePath, [in, unique] IWarningCallback* WarningCallback, [out] IWSLCSession** Session); |
| 888 | HRESULT ListSessions([out, size_is(, *SessionsCount)] WSLCSessionListEntry** Sessions, [out] ULONG* SessionsCount); |
| 889 | HRESULT OpenSession([in] ULONG Id, [out] IWSLCSession** Session); |
| 890 | HRESULT OpenSessionByName([in, unique] LPCWSTR DisplayName, [out] IWSLCSession** Session); |
| 891 | } |
| 892 | |
| 893 | // Ensure wslcsdk.h and wslcsdk.idl are also updated. |
| 894 | cpp_quote("#define WSLC_E_BASE (0x0600)") |
| 895 | cpp_quote("#define WSLC_E_IMAGE_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 1) /* 0x80040601 */") |
| 896 | cpp_quote("#define WSLC_E_CONTAINER_PREFIX_AMBIGUOUS MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 2) /* 0x80040602 */") |
| 897 | cpp_quote("#define WSLC_E_CONTAINER_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 3) /* 0x80040603 */") |
| 898 | cpp_quote("#define WSLC_E_VOLUME_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 4) /* 0x80040604 */") |
| 899 | cpp_quote("#define WSLC_E_CONTAINER_NOT_RUNNING MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 5) /* 0x80040605 */") |
| 900 | cpp_quote("#define WSLC_E_CONTAINER_IS_RUNNING MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 6) /* 0x80040606 */") |
| 901 | cpp_quote("#define WSLC_E_SESSION_RESERVED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 7) /* 0x80040607 */") |
| 902 | cpp_quote("#define WSLC_E_INVALID_SESSION_NAME MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 8) /* 0x80040608 */") |
| 903 | cpp_quote("#define WSLC_E_NETWORK_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 9) /* 0x80040609 */") |
| 904 | cpp_quote("#define WSLC_E_WU_SEARCH_FAILED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 10) /* 0x8004060A */") |
| 905 | cpp_quote("#define WSLC_E_SDK_UPDATE_NEEDED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 11) /* 0x8004060B */") |
| 906 | cpp_quote("#define WSLC_E_CONTAINER_DISABLED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 12) /* 0x8004060C */") |
| 907 | cpp_quote("#define WSLC_E_REGISTRY_BLOCKED_BY_POLICY MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 13) /* 0x8004060D */") |
| 908 | cpp_quote("#define WSLC_E_VOLUME_NOT_AVAILABLE MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 14) /* 0x8004060E */") |
| 909 | cpp_quote("#define WSLC_E_SESSION_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 15) /* 0x8004060F */") |
| 910 | // N.B. WSLC_E_VM_NOT_RUNNING is part of the plugin API contract and is also defined in WslPluginApi.h. |
| 911 | // The two definitions must stay in sync. |
| 912 | cpp_quote("#define WSLC_E_VM_NOT_RUNNING MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 16) /* 0x80040610 */") |
| 913 | cpp_quote("#define WSLC_E_EVENTS_LOST MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 17) /* 0x80040611 */") |
| 914 | cpp_quote("#define WSLC_E_EVENT_STREAM_FINISHED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 18) /* 0x80040612 */") |
| 915 | cpp_quote("#define WSLC_E_CONTAINER_DELETED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 19) /* 0x80040613 */") |