wslc.idl

/*++

Copyright (c) Microsoft Corporation.  All rights reserved.

Module Name:

    wslc.idl

Abstract:

    This file contains the WSLC-related COM object definitions.

--*/

import "unknwn.idl";
import "wtypes.idl";

cpp_quote("#ifdef __cplusplus")
cpp_quote("class DECLSPEC_UUID(\"a9b7a1b9-0671-405c-95f1-e0612cb4ce8f\") WSLCSessionManager;")
cpp_quote("class DECLSPEC_UUID(\"9FCD2067-9FC6-4EFA-9EB0-698169EBF7D3\") WSLCSessionFactory;")
cpp_quote("#endif")

#define WSLC_MAX_CONTAINER_NAME_LENGTH 255
#define WSLC_MAX_IMAGE_NAME_LENGTH 255
#define WSLC_MAX_VOLUME_NAME_LENGTH 255
#define WSLC_CONTAINER_ID_LENGTH 64
#define WSLC_MAX_BINDING_ADDRESS_LENGTH 45
#define WSLC_EPHEMERAL_PORT 0

cpp_quote("#define WSLC_MAX_CONTAINER_NAME_LENGTH 255")
cpp_quote("#define WSLC_MAX_IMAGE_NAME_LENGTH 255")
cpp_quote("#define WSLC_MAX_VOLUME_NAME_LENGTH 255")
cpp_quote("#define WSLC_CONTAINER_ID_LENGTH 64")
cpp_quote("#define WSLC_MAX_BINDING_ADDRESS_LENGTH 45")
cpp_quote("#define WSLC_EPHEMERAL_PORT 0")

typedef
struct _WSLCVersion {
    ULONG Major;
    ULONG Minor;
    ULONG Revision;
} WSLCVersion;

typedef enum _WSLCVirtualMachineTerminationReason
{
    WSLCVirtualMachineTerminationReasonUnknown,
    WSLCVirtualMachineTerminationReasonShutdown,
    WSLCVirtualMachineTerminationReasonCrashed,
} WSLCVirtualMachineTerminationReason;

typedef enum _WSLCFD
{
    WSLCFDStdin = 0,
    WSLCFDStdout = 1,
    WSLCFDStderr = 2,
    WSLCFDTty = 3,
} WSLCFD;

typedef enum _WSLCSignal
{
    WSLCSignalNone = 0,
    WSLCSignalSIGHUP = 1,
    WSLCSignalSIGINT = 2,
    WSLCSignalSIGQUIT = 3,
    WSLCSignalSIGILL = 4,
    WSLCSignalSIGTRAP = 5,
    WSLCSignalSIGABRT = 6,
    WSLCSignalSIGIOT = 6, // SIGABRT and SIGIOT are equivalent.
    WSLCSignalSIGBUS = 7,
    WSLCSignalSIGFPE = 8,
    WSLCSignalSIGKILL = 9,
    WSLCSignalSIGUSR1 = 10,
    WSLCSignalSIGSEGV = 11,
    WSLCSignalSIGUSR2 = 12,
    WSLCSignalSIGPIPE = 13,
    WSLCSignalSIGALRM = 14,
    WSLCSignalSIGTERM = 15,
    WSLCSignalSIGTKFLT = 16,
    WSLCSignalSIGCHLD = 17,
    WSLCSignalSIGCONT = 18,
    WSLCSignalSIGSTOP = 19,
    WSLCSignalSIGTSTP = 20,
    WSLCSignalSIGTTIN = 21,
    WSLCSignalSIGTTOU = 22,
    WSLCSignalSIGURG = 23,
    WSLCSignalSIGXCPU = 24,
    WSLCSignalSIGXFSZ = 25,
    WSLCSignalSIGVTALRM = 26,
    WSLCSignalSIGPROF = 27,
    WSLCSignalSIGWINCH = 28,
    WSLCSignalSIGIO = 29,
    WSLCSignalSIGPOLL = 29, // SIGIO and SIGPOLL are equivalent.
    WSLCSignalSIGPWR = 30,
    WSLCSignalSIGSYS = 31
} WSLCSignal;

[
    uuid(7BC4E198-6531-4FA6-ADE2-5EF3D2A04DFE),
    pointer_default(unique),
    object
]
interface ITerminationCallback : IUnknown
{
    HRESULT OnTermination(WSLCVirtualMachineTerminationReason Reason, LPCWSTR Details);
};

[
    uuid(5038842F-53DB-4F30-A6D0-A41B02C94AC1),
    pointer_default(unique),
    object
]
interface IProgressCallback : IUnknown
{
    HRESULT OnProgress(LPCSTR Status, LPCSTR Id, ULONGLONG Current, ULONGLONG Total);
};

typedef struct _WSLCImageInformation
{
    char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1];
    char Hash[256];
    char Digest[256];
    ULONGLONG Size;
    LONGLONG Created; // Unix timestamp
    char ParentId[256];
} WSLCImageInformation;

typedef enum _WSLCListImagesFlags
{
    WSLCListImagesFlagsNone = 0,
    WSLCListImagesFlagsAll = 1,           // Show all images (default hides intermediate images)
    WSLCListImagesFlagsDigests = 2,       // Include digest information
    WSLCListImagesFlagsDanglingTrue = 4,  // Show only dangling images (untagged)
    WSLCListImagesFlagsDanglingFalse = 8, // Show only non-dangling images (tagged)
    // Note: If neither dangling flag is set, no dangling filter is passed (default: both).
} WSLCListImagesFlags;

cpp_quote("#define WSLCListImagesFlagsValid (WSLCListImagesFlagsAll | WSLCListImagesFlagsDigests | WSLCListImagesFlagsDanglingTrue | WSLCListImagesFlagsDanglingFalse)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCListImagesFlags);")

typedef struct _WSLCLabelInformation
{
    [string] LPSTR Key;
    [string] LPSTR Value;
} WSLCLabelInformation;

typedef struct _WSLCLabel
{
    [string] LPCSTR Key;
    [string] LPCSTR Value;
} WSLCLabel;

typedef struct _WSLCListImageOptions
{
    DWORD Flags; // WSLCListImagesFlags (can combine with bitwise OR)
    [unique] LPCSTR Reference; // Filter by reference (name[:tag])
    [unique] LPCSTR Before; // Filter: show images created before this image
    [unique] LPCSTR Since; // Filter: show images created since this image
    [unique, size_is(LabelsCount)] const WSLCLabel* Labels;
    ULONG LabelsCount;
} WSLCListImageOptions;

typedef enum _WSLCProcessFlags
{
    WSLCProcessFlagsNone = 0,
    WSLCProcessFlagsStdin = 1,
    WSLCProcessFlagsTty = 2
} WSLCProcessFlags;

cpp_quote("#define WSLCProcessFlagsValid (WSLCProcessFlagsStdin | WSLCProcessFlagsTty)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCProcessFlags);")

typedef struct _WSLCStringArray
{
    [unique, size_is(Count)] LPCSTR const* Values;
    ULONG Count;
} WSLCStringArray;

typedef struct _WSLCProcessOptions
{
    [unique] LPCSTR CurrentDirectory;
    [unique] LPCSTR User;
    WSLCStringArray CommandLine;
    WSLCStringArray Environment;
    WSLCProcessFlags Flags;
    ULONG TtyRows; // Only needed when tty fd's are passed.
    ULONG TtyColumns;
} WSLCProcessOptions;

typedef struct _WSLCNamedVolume
{
    LPCSTR Name;
    LPCSTR ContainerPath;
    BOOL ReadOnly;
} WSLCNamedVolume;

typedef struct _WSLCVolume
{
    LPCWSTR HostPath;
    LPCSTR ContainerPath;
    BOOL ReadOnly;
} WSLCVolume;

typedef struct _WSLCPortMapping
{
    USHORT HostPort;
    USHORT ContainerPort;
    int Family;
    int Protocol;
    char BindingAddress[WSLC_MAX_BINDING_ADDRESS_LENGTH + 1];
} WSLCPortMapping;

typedef struct _WSLCTmpfsMount
{
    LPCSTR Destination;
    [unique] LPCSTR Options;
} WSLCTmpfsMount;

typedef enum _WSLCContainerNetworkType
{
    WSLCContainerNetworkTypeNone = 0,
    WSLCContainerNetworkTypeHost = 1,
    WSLCContainerNetworkTypeBridged = 2,
    // WSLCContainerNetworkTypeCustom = 3 // TODO: Implement when implementing custom networks
} WSLCContainerNetworkType;

typedef struct _WSLCContainerNetwork
{
    WSLCContainerNetworkType ContainerNetworkType;
    LPCSTR ContainerNetworkName;
} WSLCContainerNetwork;

typedef enum _WSLCContainerFlags
{
    WSLCContainerFlagsNone = 0,
    WSLCContainerFlagsRm = 1, // Delete the container when it exits. TODO: Implement.
    WSLCContainerFlagsGpu = 2, // Enable GPU access. TODO: implement.
    WSLCContainerFlagsInit = 4, // Run the container under an init process.
} WSLCContainerFlags;

cpp_quote("#define WSLCContainerFlagsValid (WSLCContainerFlagsRm | WSLCContainerFlagsGpu | WSLCContainerFlagsInit)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCContainerFlags);")


typedef enum _WSLCContainerStartFlags
{
    WSLCContainerStartFlagsNone = 0,
    WSLCContainerStartFlagsAttach = 1, // Attach stdio handles on start.
} WSLCContainerStartFlags;

cpp_quote("#define WSLCContainerStartFlagsValid (WSLCContainerStartFlagsAttach)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCContainerStartFlags);")

typedef struct _WSLCContainerOptions
{
    LPCSTR Image;
    [unique] LPCSTR Name;
    WSLCStringArray Entrypoint;
    WSLCProcessOptions InitProcessOptions;
    [unique, size_is(VolumesCount)] WSLCVolume* Volumes;
    ULONG VolumesCount;
    [unique, size_is(PortsCount)] WSLCPortMapping* Ports;
    ULONG PortsCount;
    [unique, size_is(LabelsCount)] const WSLCLabel* Labels;
    ULONG LabelsCount;
    WSLCContainerFlags Flags;
    WSLCSignal StopSignal;
    // TODO: List specific GPU devices.
    [unique] LPCSTR HostName;
    [unique] LPCSTR DomainName;

    WSLCStringArray DnsServers;
    WSLCStringArray DnsSearchDomains;
    WSLCStringArray DnsOptions;

    ULONGLONG ShmSize;
    WSLCContainerNetwork ContainerNetwork;
    [unique, size_is(TmpfsCount)] const WSLCTmpfsMount* Tmpfs;
    ULONG TmpfsCount;

    [unique, size_is(NamedVolumesCount)] WSLCNamedVolume* NamedVolumes;
    ULONG NamedVolumesCount;
} WSLCContainerOptions;

typedef enum _WSLCContainerState
{
    WslcContainerStateInvalid = 0,
    WslcContainerStateCreated = 1,
    WslcContainerStateRunning = 2,
    WslcContainerStateExited = 3,
    WslcContainerStateDeleted = 4,
} WSLCContainerState;

typedef char WSLCContainerId[WSLC_CONTAINER_ID_LENGTH + 1] ;

typedef struct _WSLCContainerEntry
{
    char Name[WSLC_MAX_CONTAINER_NAME_LENGTH + 1];
    char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1];
    WSLCContainerId Id;
    ULONGLONG StateChangedAt;
    ULONGLONG CreatedAt;
    WSLCContainerState State;
} WSLCContainerEntry;

typedef struct _WSLCContainerPortMapping
{
    WSLCContainerId Id;
    WSLCPortMapping PortMapping;
} WSLCContainerPortMapping;

typedef [system_handle(sh_file)] HANDLE FILE_HANDLE;
typedef [system_handle(sh_pipe)] HANDLE PIPE_HANDLE;
typedef [system_handle(sh_socket)] HANDLE SOCKET_HANDLE;

typedef enum _WSLCHandleType
{
    WSLCHandleTypeUnknown = 0,
    WSLCHandleTypeFile = 1,
    WSLCHandleTypePipe = 2,
    WSLCHandleTypeSocket = 3
} WSLCHandleType;

typedef struct _WSLCHandle
{
    WSLCHandleType Type;

    [switch_type(WSLCHandleType), switch_is(Type)]
    union
    {
        [case(WSLCHandleTypeFile)]
        FILE_HANDLE File;
        [case(WSLCHandleTypePipe)]
        PIPE_HANDLE Pipe;
        [case(WSLCHandleTypeSocket)]
        SOCKET_HANDLE Socket;
        [default];
    } Handle;
} WSLCHandle;

typedef enum _WSLCProcessState
{
    WslcProcessStateUnknown = 0,
    WslcProcessStateRunning = 1,
    WslcProcessStateExited = 2,
    WslcProcessStateSignalled = 3
} WSLCProcessState;

[
    uuid(1AD163CD-393D-4B33-83A2-8A3F3F23E608),
    pointer_default(unique),
    object
]
interface IWSLCProcess : IUnknown
{
    HRESULT Signal([in] int Signal);
    HRESULT GetExitEvent([out, system_handle(sh_event)] HANDLE* EventHandle);
    HRESULT GetStdHandle([in] WSLCFD Fd, [out] WSLCHandle* Handle);
    HRESULT GetFlags([out] WSLCProcessFlags* Flags);
    HRESULT GetPid([out] int* Pid);
    HRESULT GetState([out] WSLCProcessState* State, [out] int* Code);
    HRESULT ResizeTty([in] ULONG Rows, [in] ULONG Columns);

    // Note: the SDK can offer a convenience Wait() method, but that doesn't need to be part of the service API.
}

typedef enum _WSLCNetworkingMode
{
    WSLCNetworkingModeNone,
    WSLCNetworkingModeNAT,
    WSLCNetworkingModeVirtioProxy
} WSLCNetworkingMode;

typedef enum _WSLCFeatureFlags
{
    WslcFeatureFlagsNone = 0,
    WslcFeatureFlagsDnsTunneling = 1,
    WslcFeatureFlagsEarlyBootDmesg = 2,
    WslcFeatureFlagsGPU = 4,
    WslcFeatureFlagsVirtioFs = 8,
    WslcFeatureFlagsDebug = 16,
} WSLCFeatureFlags;

cpp_quote("#define WSLCFeatureFlagsValid (WslcFeatureFlagsDnsTunneling | WslcFeatureFlagsEarlyBootDmesg | WslcFeatureFlagsGPU | WslcFeatureFlagsVirtioFs | WslcFeatureFlagsDebug)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCFeatureFlags);")

//
// IWSLCVirtualMachine - Interface representing a single VM instance.
// Operations are scoped to this VM. The VM ID is stored internally,
// so only the holder of this interface can operate on the VM.
//
[
    uuid(B5E2D8F1-9A3C-4E6B-8D1F-7C4A2E9B6D3A),
    pointer_default(unique),
    object
]
interface IWSLCVirtualMachine : IUnknown
{
    // Gets the VM ID.
    HRESULT GetId([out, retval] GUID* VmId);

    // Accepts a connect from mini_init in the VM.
    HRESULT AcceptConnection([out, system_handle(sh_socket)] HANDLE* Socket);

    // Configures networking engine with sockets from the user process.
    // GnsSocket is required; DnsSocket is optional (NULL if DNS tunneling is disabled).
    // The service duplicates the socket handles.
    HRESULT ConfigureNetworking(
        [in, system_handle(sh_socket)] HANDLE GnsSocket,
        [in, system_handle(sh_socket), unique] HANDLE* DnsSocket);

    // Attaches a VHD or VHDX disk to the VM.
    // GrantVmAccess is called by the service before attaching.
    // Returns the SCSI LUN assigned to the disk.
    HRESULT AttachDisk([in] LPCWSTR Path, [in] BOOL ReadOnly, [out, retval] ULONG* Lun);

    // Detaches a previously attached disk from the VM.
    HRESULT DetachDisk([in] ULONG Lun);

    // Adds a filesystem share (Plan9 or VirtioFS) accessible to the VM.
    // Returns an instance GUID that can be used to remove the share.
    HRESULT AddShare([in] LPCWSTR WindowsPath, [in] BOOL ReadOnly, [out, retval] GUID* ShareId);

    // Removes a previously added filesystem share.
    HRESULT RemoveShare([in] REFGUID ShareId);

    // Maps a port via VirtioNetworking.
    // For anonymous binds (HostPort == WSLC_EPHEMERAL_PORT), the networking engine allocates a host port
    // and returns it in AllocatedHostPort.
    // Protocol must be IPPROTO_TCP or IPPROTO_UDP.
    // ListenAddress is the IP address to bind on (e.g. "127.0.0.1", "0.0.0.0", "::1").
    HRESULT MapVirtioNetPort(
        [in] USHORT HostPort,
        [in] USHORT GuestPort,
        [in] int Protocol,
        [in] LPCSTR ListenAddress,
        [out, retval] USHORT* AllocatedHostPort);

    // Unmaps a port previously mapped via MapVirtioNetPort.
    HRESULT UnmapVirtioNetPort(
        [in] USHORT HostPort,
        [in] USHORT GuestPort,
        [in] int Protocol,
        [in] LPCSTR ListenAddress);
}

typedef enum _WSLCSessionStorageFlags
{
    WSLCSessionStorageFlagsNone = 0,
    WSLCSessionStorageFlagsNoCreate = 1, // Open an existing storage path, but don't create a new one.
    WSLCSessionStorageFlagsValid = WSLCSessionStorageFlagsNoCreate
} WSLCSessionStorageFlags;

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCSessionStorageFlags);")

// Settings for IWSLCSessionManager::CreateSession - full session configuration
typedef struct _WSLCSessionSettings {
    LPCWSTR DisplayName;
    LPCWSTR StoragePath;
    ULONGLONG MaximumStorageSizeMb;
    ULONG CpuCount;
    ULONG MemoryMb;
    ULONG BootTimeoutMs;
    WSLCNetworkingMode NetworkingMode;
    [unique] ITerminationCallback* TerminationCallback;
    WSLCFeatureFlags FeatureFlags;
    WSLCHandle DmesgOutput;
    WSLCSessionStorageFlags StorageFlags;

    // Below options are used for debugging purposes only.
    [unique] LPCWSTR RootVhdOverride;
    [unique] LPCSTR RootVhdTypeOverride;
} WSLCSessionSettings;

typedef enum _WSLCLogsFlags
{
    WSLCLogsFlagsNone = 0,
    WSLCLogsFlagsFollow = 1,
    WSLCLogsFlagsTimestamps = 2,
} WSLCLogsFlags;

cpp_quote("#define WSLCLogsFlagsValid (WSLCLogsFlagsFollow | WSLCLogsFlagsTimestamps)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCLogsFlags);")

typedef enum _WSLCDeleteFlags
{
    WSLCDeleteFlagsNone = 0,
    WSLCDeleteFlagsForce = 1,
    // TODO: Flags to remove anonymous volumes, bridge links, etc.
} WSLCDeleteFlags;

cpp_quote("#define WSLCDeleteFlagsValid (WSLCDeleteFlagsForce)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCDeleteFlags);")


[
    uuid(7577FE8D-DE85-471E-B870-11669986F332),
    pointer_default(unique),
    object
]
interface IWSLCContainer : IUnknown
{
    HRESULT Attach([in, unique] LPCSTR DetachKeys, [out] WSLCHandle* StdIn, [out] WSLCHandle* StdOut, [out] WSLCHandle* StdErr);
    HRESULT Stop([in] WSLCSignal Signal, [in] LONG TimeoutSeconds);
    HRESULT Start([in] WSLCContainerStartFlags Flags, [in, unique] LPCSTR DetachKeys);
    HRESULT Delete([in] WSLCDeleteFlags Flags);
    HRESULT Export([in] WSLCHandle TarHandle);
    HRESULT GetState([out] WSLCContainerState* State);
    HRESULT GetInitProcess([out] IWSLCProcess** Process);
    HRESULT Exec([in, ref] const WSLCProcessOptions* Options, [in, unique] LPCSTR DetachKeys, [out] IWSLCProcess** Process);
    HRESULT Inspect([out] LPSTR* Output);
    HRESULT Logs([in] WSLCLogsFlags Flags, [out] WSLCHandle* Stdout, [out] WSLCHandle* Stderr, [in] ULONGLONG Since, [in] ULONGLONG Until, [in] ULONGLONG Tail);
    HRESULT GetId([out, string] WSLCContainerId Id);
    HRESULT GetName([out, string] LPSTR* Name);
    HRESULT GetLabels([out, size_is(, *Count)] WSLCLabelInformation** Labels, [out] ULONG* Count);
    HRESULT Kill([in] WSLCSignal Signal);
}

typedef enum _WSLCDeletedImageType
{
    WSLCDeletedImageTypeDeleted = 0,
    WSLCDeletedImageTypeUntagged = 1
} WSLCDeletedImageType;

typedef struct _WSLCDeletedImageInformation
{
    char Image[WSLC_MAX_IMAGE_NAME_LENGTH + 1];
    WSLCDeletedImageType Type;
} WSLCDeletedImageInformation;

typedef enum _WSLCDeleteImageFlags
{
    WSLCDeleteImageFlagsNone = 0,
    WSLCDeleteImageFlagsForce = 1,
    WSLCDeleteImageFlagsNoPrune = 2,
} WSLCDeleteImageFlags;

cpp_quote("#define WSLCDeleteImageFlagsValid (WSLCDeleteImageFlagsForce | WSLCDeleteImageFlagsNoPrune)")

cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCDeleteImageFlags);")

typedef struct _WSLCDeleteImageOptions
{
    LPCSTR Image; // Image can be ID or Repo:Tag.
    DWORD Flags; // WSLCDeleteImageFlags
    // TODO: Platforms: a json array of OCI platform strings.
} WSLCDeleteImageOptions;

typedef struct _WSLCBuildImageOptions
{
    LPCWSTR ContextPath;
    WSLCHandle DockerfileHandle;
    WSLCStringArray Tags;
    WSLCStringArray BuildArgs; // KEY=VALUE pairs passed as --build-arg to docker.
    BOOL Verbose; // Show all build progress including internal steps and all statuses.
} WSLCBuildImageOptions;

typedef struct _WSLCTagImageOptions
{
    LPCSTR Image; // Source image name or ID.
    LPCSTR Repo;  // Target repository name.
    LPCSTR Tag;   // Target tag name.
} WSLCTagImageOptions;

typedef struct _WSLCVolumeOptions
{
    LPCSTR Name;
    LPCSTR Type;
    [unique] LPCSTR Options;
} WSLCVolumeOptions;

typedef struct _WSLCVolumeInformation
{
    char Name[WSLC_MAX_VOLUME_NAME_LENGTH + 1];
    char Type[64];
} WSLCVolumeInformation;

typedef struct _WSLCContainerPruneFilter
{
    LPCSTR Key;
    [unique] LPCSTR Value;
    BOOL Present;
} WSLCContainerPruneFilter;

typedef struct _WSLCPruneContainersResults
{
    [unique, size_is(ContainersCount)] WSLCContainerId* Containers;
    ULONG ContainersCount;
    ULONGLONG SpaceReclaimed;
} WSLCPruneContainersResults;

typedef enum _WSLCSessionState
{
    WSLCSessionStateRunning = 0,
    WSLCSessionStateTerminated = 1
} WSLCSessionState;

// Settings for IWSLCSession::Initialize - passed from service to per-user process
typedef struct _WSLCSessionInitSettings
{
    ULONG SessionId;
    ULONG CreatorPid;
    LPCWSTR DisplayName;
    LPCWSTR StoragePath;
    WSLCSessionStorageFlags StorageFlags;
    ULONGLONG MaximumStorageSizeMb;
    ULONG BootTimeoutMs;
    WSLCNetworkingMode NetworkingMode;
    WSLCFeatureFlags FeatureFlags;
    [unique] LPCSTR RootVhdTypeOverride;
} WSLCSessionInitSettings;

[
    uuid(EF0661E4-6364-40EA-B433-E2FDF11F3519),
    pointer_default(unique),
    object
]
interface IWSLCSession : IUnknown
{
    HRESULT GetId([out] ULONG* Id);
    HRESULT GetState([out] WSLCSessionState* State);

    // Image management.
    HRESULT PullImage([in] LPCSTR Image, [in, unique] LPCSTR RegistryAuthenticationInformation, [in, unique] IProgressCallback* ProgressCallback);
    HRESULT BuildImage([in] const WSLCBuildImageOptions* Options, [in, unique] IProgressCallback* ProgressCallback, [in, unique, system_handle(sh_event)] HANDLE CancelEvent);
    HRESULT LoadImage([in] WSLCHandle ImageHandle, [in, unique] IProgressCallback* ProgressCallback, [in] ULONGLONG ContentLength);
    HRESULT ImportImage([in] WSLCHandle ImageHandle, [in] LPCSTR ImageName, [in, unique] IProgressCallback* ProgressCallback, [in] ULONGLONG ContentLength);
    HRESULT SaveImage([in] WSLCHandle OutputHandle, [in] LPCSTR ImageNameOrID, [in, unique] IProgressCallback * ProgressCallback, [in, unique, system_handle(sh_event)] HANDLE CancelEvent);
    HRESULT ListImages([in, unique] const WSLCListImageOptions* Options, [out, size_is(, *Count)] WSLCImageInformation** Images, [out] ULONG* Count);
    HRESULT DeleteImage([in] const WSLCDeleteImageOptions* Options, [out, size_is(, *Count)] WSLCDeletedImageInformation** DeletedImages, [out] ULONG* Count);
    HRESULT TagImage([in] const WSLCTagImageOptions* Options);
    HRESULT InspectImage([in] LPCSTR ImageNameOrId, [out] LPSTR* Output);

    // Container management.
    HRESULT CreateContainer([in] const WSLCContainerOptions* Options, [out] IWSLCContainer** Container);
    HRESULT OpenContainer([in, ref] LPCSTR Id, [out] IWSLCContainer** Container);
    HRESULT ListContainers([out, size_is(, *Count)] WSLCContainerEntry** Containers,
                                            [out] ULONG* Count,
                                            [out, size_is(, *PortsCount)] WSLCContainerPortMapping** Ports,
                                            [out] ULONG* PortsCount);
    HRESULT PruneContainers([in, unique, size_is(FiltersCount)] WSLCContainerPruneFilter* Filters, [in] DWORD FiltersCount, [in] ULONGLONG Until, [out] WSLCPruneContainersResults* Result);

    // Create a process at the VM level. This is meant for debugging.
    HRESULT CreateRootNamespaceProcess([in, ref] LPCSTR Executable, [in, ref] const WSLCProcessOptions* Options, [out] IWSLCProcess** Process, [out] int* Errno);

    // TODO: an OpenProcess() method can be added later if needed.

    // Disk management.
    HRESULT FormatVirtualDisk([in, ref] LPCWSTR Path);

    // Terminate the VM and containers.
    HRESULT Terminate();

    // Used only for testing. TODO: Think about moving them to a dedicated testing-only interface.
    HRESULT MountWindowsFolder([in, ref] LPCWSTR WindowsPath, [in, ref] LPCSTR LinuxPath, [in] BOOL ReadOnly);
    HRESULT UnmountWindowsFolder([in, ref] LPCSTR LinuxPath);
    HRESULT MapVmPort([in] int Family, [in] unsigned short WindowsPort, [in] unsigned short LinuxPort);
    HRESULT UnmapVmPort([in] int Family, [in] unsigned short WindowsPort, [in] unsigned short LinuxPort);

    // Session initialization - called by SYSTEM service after launching per-user process.
    // Returns a handle to this COM server process (used to add to job object).
    HRESULT GetProcessHandle([out, system_handle(sh_process)] HANDLE* ProcessHandle);

    // Initializes the session with a pre-created VM.
    HRESULT Initialize(
        [in] const WSLCSessionInitSettings* Settings,
        [in] IWSLCVirtualMachine* Vm);

    // Volume management.
    HRESULT CreateVolume([in] const WSLCVolumeOptions* Options);
    HRESULT DeleteVolume([in] LPCSTR Name);
    HRESULT ListVolumes([out, size_is(, *Count)] WSLCVolumeInformation** Volumes, [out] ULONG* Count);
    HRESULT InspectVolume([in] LPCSTR Name, [out] LPSTR* Output);
}

//
// IWSLCSessionReference - Weak reference to a session held by the SYSTEM service.
// Stored in per-user process, allows service to check liveness and terminate sessions.
// Session metadata (ID, name, etc.) is stored service-side in SessionEntry.
//
[
    uuid(B3A72F48-9D15-4E8A-A621-7C3E84F09B52),
    pointer_default(unique),
    object
]
interface IWSLCSessionReference : IUnknown
{
    // Try to open the session. Fails if session was released or terminated.
    // Returns S_OK and a valid session if still alive.
    HRESULT OpenSession([out] IWSLCSession** Session);

    // Terminate the session if still alive.
    HRESULT Terminate();
}

//
// IWSLCSessionFactory - Creates sessions in the per-user COM server process.
// Called by the SYSTEM service via CoCreateInstanceAsUser.
//
[
    uuid(C4E8F291-3B5D-4A7C-9E12-8F6A4D2B7C91),
    pointer_default(unique),
    object
]
interface IWSLCSessionFactory : IUnknown
{
    // Creates a new session and returns both the session interface and a service reference.
    HRESULT CreateSession(
        [in] const WSLCSessionInitSettings* Settings,
        [in] IWSLCVirtualMachine* Vm,
        [out] IWSLCSession** Session,
        [out] IWSLCSessionReference** ServiceRef);

    // Gets the process handle for adding to job object.
    HRESULT GetProcessHandle([out, system_handle(sh_process)] HANDLE* ProcessHandle);
}

typedef struct _WSLCSessionInformation
{
    ULONG SessionId;
    DWORD CreatorPid;
    wchar_t DisplayName[256];
    wchar_t Sid[256 + 1]; // MAX_SID_SIZE = 256
} WSLCSessionInformation;

typedef enum _WSLCSessionFlags
{
    WSLCSessionFlagsNone = 0,
    WSLCSessionFlagsPersistent = 1, // Session remains active after its COM reference is released.
    WSLCSessionFlagsOpenExisting = 2, // Open an existing session if the name is in use.
} WSLCSessionFlags;

cpp_quote("#define WSLCSessionFlagsValid (WSLCSessionFlagsPersistent | WSLCSessionFlagsOpenExisting)")
cpp_quote("DEFINE_ENUM_FLAG_OPERATORS(WSLCSessionFlags);")

[
    uuid(82A7ABC8-6B50-43FC-AB96-15FBBE7E8760),
    pointer_default(unique),
    object
]
interface IWSLCSessionManager : IUnknown
{
    HRESULT GetVersion([out] WSLCVersion* Version);

    // Session management.
    HRESULT CreateSession([in, ref] const WSLCSessionSettings* Settings, WSLCSessionFlags Flags, [out] IWSLCSession** Session);
    HRESULT ListSessions([out, size_is(, *SessionsCount)] WSLCSessionInformation** Sessions, [out] ULONG* SessionsCount);
    HRESULT OpenSession([in] ULONG Id, [out] IWSLCSession** Session);
    HRESULT OpenSessionByName([in, ref] LPCWSTR DisplayName, [out] IWSLCSession** Session);
}

cpp_quote("#define WSLC_E_BASE (0x0600)")
cpp_quote("#define WSLC_E_IMAGE_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 1) /* 0x80040601 */")
cpp_quote("#define WSLC_E_CONTAINER_PREFIX_AMBIGUOUS MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 2) /* 0x80040602 */")
cpp_quote("#define WSLC_E_CONTAINER_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 3) /* 0x80040603 */")
cpp_quote("#define WSLC_E_VOLUME_NOT_FOUND MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 4) /* 0x80040604 */")