@samitouri / QOSAMI-WSL-1
Code Commits Issues Pulls Sessions CI/CD
master
master
idl 386 lines 10.1 KB
Raw
1 /*++
2
3 Copyright (c) Microsoft. All rights reserved.
4
5 Module Name:
6
7 wslcsdk.idl
8
9 Abstract:
10
11 This file contains the definition of a WinRT projection of the WSL Container SDK API.
12
13 --*/
14
15 namespace Microsoft.WSL.Containers
16 {
17 enum SessionTerminationReason
18 {
19 Unknown = 0,
20 Shutdown = 1,
21 Crashed = 2,
22 };
23
24 delegate void SessionTerminationHandler(SessionTerminationReason reason);
25
26 runtimeclass ProcessCrashInformation
27 {
28 String DumpPath { get; };
29 String ProcessName { get; };
30 UInt32 Pid { get; };
31 UInt32 Signal { get; };
32 Windows.Foundation.DateTime Timestamp { get; };
33 };
34
35 delegate void ProcessCrashHandler(ProcessCrashInformation information);
36
37 enum IdentityTokenType
38 {
39 Unknown = 0,
40 Token = 1,
41 Credentials = 2,
42 };
43
44 runtimeclass AuthenticateResult
45 {
46 String IdentityToken { get; };
47 IdentityTokenType TokenType { get; };
48 };
49
50 runtimeclass SessionSettings
51 {
52 SessionSettings(String name, String storagePath);
53
54 String Name;
55 String StoragePath;
56
57 Windows.Foundation.IReference<UInt32> CpuCount;
58 Windows.Foundation.IReference<UInt32> MemorySizeInMB;
59 Windows.Foundation.IReference<Windows.Foundation.TimeSpan> Timeout;
60 VhdOptions VhdRequirements;
61 Boolean EnableGpu;
62 };
63
64 runtimeclass Session : Windows.Foundation.IClosable
65 {
66 Session(SessionSettings settings);
67
68 void Start();
69 void Terminate();
70
71 Container CreateContainer(ContainerSettings containerSettings);
72 Container OpenContainer(String nameOrId, ProcessOutputMode initProcessOutputMode);
73
74 void PullImage(PullImageOptions options);
75 Windows.Foundation.IAsyncActionWithProgress<ImageProgress> PullImageAsync(PullImageOptions options);
76 // TODO: Explore additional overloads for other types of input streams
77 void ImportImage(String path, String imageName);
78 Windows.Foundation.IAsyncActionWithProgress<ImageProgress> ImportImageAsync(String path, String imageName);
79 void LoadImage(String path);
80 Windows.Foundation.IAsyncActionWithProgress<ImageProgress> LoadImageAsync(String path);
81 void PushImage(PushImageOptions options);
82 Windows.Foundation.IAsyncActionWithProgress<ImageProgress> PushImageAsync(PushImageOptions options);
83
84 void DeleteImage(String nameOrId);
85 void TagImage(TagImageOptions options);
86
87 void CreateVhdVolume(VhdOptions options);
88 void DeleteVhdVolume(String name);
89
90 AuthenticateResult Authenticate(Windows.Foundation.Uri serverAddress, String username, String password);
91
92 IVectorView<ImageInfo> GetImages();
93
94 event SessionTerminationHandler Terminated;
95 event ProcessCrashHandler ProcessCrashed;
96 };
97
98
99 enum ContainerNetworkingMode
100 {
101 None = 0,
102 Bridged = 1,
103 };
104
105 enum PortProtocol
106 {
107 TCP = 0,
108 UDP = 1,
109 };
110
111 runtimeclass ContainerPortMapping
112 {
113 ContainerPortMapping(UInt16 windowsPort, UInt16 containerPort, PortProtocol protocol);
114
115 UInt16 WindowsPort;
116 UInt16 ContainerPort;
117 PortProtocol Protocol;
118
119 Windows.Networking.HostName WindowsAddress;
120 };
121
122 runtimeclass ContainerVolume
123 {
124 ContainerVolume(String windowsPath, String containerPath, Boolean readOnly);
125
126 String WindowsPath;
127 String ContainerPath;
128 Boolean ReadOnly;
129 };
130
131 runtimeclass ContainerNamedVolume
132 {
133 ContainerNamedVolume(String name, String containerPath, Boolean readOnly);
134
135 String Name;
136 String ContainerPath;
137 Boolean ReadOnly;
138 };
139
140 enum ContainerState
141 {
142 Invalid = 0,
143 Created = 1,
144 Running = 2,
145 Exited = 3,
146 Deleted = 4,
147 };
148
149 [flags]
150 enum DeleteContainerOption
151 {
152 None = 0,
153 Force = 0x00000001
154 };
155
156 runtimeclass ContainerSettings
157 {
158 ContainerSettings(String imageName);
159
160 String ImageName;
161
162 String Name;
163 ProcessSettings InitProcess;
164 Windows.Foundation.IReference<ContainerNetworkingMode> NetworkingMode;
165 String HostName;
166 String DomainName;
167 Boolean EnableAutoRemove;
168 Boolean EnableGpu;
169 Boolean Privileged;
170 IVector<ContainerPortMapping> PortMappings;
171 IVector<ContainerVolume> Volumes;
172 IVector<ContainerNamedVolume> NamedVolumes;
173 };
174
175 enum Signal
176 {
177 None = 0, // No signal; reserved for future use
178 SIGHUP = 1, // SIGHUP: reload / hangup
179 SIGINT = 2, // SIGINT: interrupt (Ctrl-C)
180 SIGQUIT = 3, // SIGQUIT: quit with core dump
181 SIGKILL = 9, // SIGKILL: immediate termination
182 SIGTERM = 15, // SIGTERM: graceful shutdown
183 };
184
185 runtimeclass Container : Windows.Foundation.IClosable
186 {
187 void Start();
188 void Stop(Signal signal, Windows.Foundation.TimeSpan timeout);
189 void Delete(DeleteContainerOption flags);
190
191 Process CreateProcess(ProcessSettings newProcessSettings);
192
193 // JSON response schema at: https://docs.docker.com/reference/api/engine/version/v1.53/#tag/Container/operation/ContainerInspect
194 String Inspect();
195
196 String Id { get; };
197 Process InitProcess { get; };
198 ContainerState State { get; };
199 };
200
201 enum ProcessOutputHandle
202 {
203 StandardOutput = 1,
204 StandardError = 2,
205 };
206
207 enum ProcessOutputMode
208 {
209 Discard = 0,
210 Stream = 1,
211 Event = 2,
212 };
213
214 runtimeclass ProcessSettings
215 {
216 ProcessSettings();
217
218 String WorkingDirectory;
219 IVector<String> CommandLine;
220 IMap<String, String> EnvironmentVariables;
221 ProcessOutputMode OutputMode;
222 };
223
224 enum ProcessState
225 {
226 Unknown = 0,
227 Running = 1,
228 Exited = 2,
229 Signalled = 3,
230 };
231
232 delegate void ProcessOutputHandler(UInt8[] data);
233 delegate void ProcessExitHandler(Int32 exitCode);
234
235 runtimeclass Process : Windows.Foundation.IClosable
236 {
237 void Start();
238
239 void Signal(Signal signal);
240 Windows.Storage.Streams.IInputStream GetOutputStream(ProcessOutputHandle outputHandle);
241 Windows.Storage.Streams.IOutputStream GetInputStream();
242
243 UInt32 Pid { get; };
244 ProcessState State { get; };
245 Int32 ExitCode { get; };
246
247 event ProcessOutputHandler OutputReceived;
248 event ProcessOutputHandler ErrorReceived;
249 event ProcessExitHandler Exited;
250 };
251
252 enum Component
253 {
254 VirtualMachinePlatform = 1,
255 WslPackage = 2,
256 SdkNeedsUpdate = 4,
257 };
258
259 runtimeclass ServiceVersion
260 {
261 UInt32 Major { get; };
262 UInt32 Minor { get; };
263 UInt32 Revision { get; };
264 };
265
266 runtimeclass InstallOptions
267 {
268 InstallOptions();
269
270 IVectorView<Component> Components;
271 Boolean Repair;
272 };
273
274 runtimeclass InstallProgress
275 {
276 Component Component { get; };
277 UInt32 Progress { get; };
278 UInt32 Total { get; };
279 };
280
281 runtimeclass WslcService
282 {
283 static IVectorView<Component> GetMissingComponents();
284 static ServiceVersion GetVersion();
285 static void InstallWithDependencies(InstallOptions options);
286 static Windows.Foundation.IAsyncActionWithProgress<InstallProgress> InstallWithDependenciesAsync(InstallOptions options);
287 };
288
289 enum VhdType
290 {
291 Dynamic = 0,
292 Fixed = 1,
293 };
294
295 struct VhdOwner
296 {
297 UInt32 Uid;
298 UInt32 Gid;
299 };
300
301 runtimeclass VhdOptions
302 {
303 VhdOptions(String name, UInt64 size, VhdType type);
304
305 String Name;
306 UInt64 Size;
307 VhdType Type;
308
309 // Owner uid/gid on the volume root inode at mkfs time. Only
310 // supported on named volumes; setting this on a SessionSettings
311 // VhdOptions fails at property-set time with E_INVALIDARG.
312 Windows.Foundation.IReference<VhdOwner> Owner;
313 };
314
315 enum ImageProgressStatus
316 {
317 Unknown = 0,
318 Pulling = 1,
319 Waiting = 2,
320 Downloading = 3,
321 Verifying = 4,
322 Extracting = 5,
323 Complete = 6,
324 };
325
326 runtimeclass ImageProgress
327 {
328 String Id { get; };
329 ImageProgressStatus Status { get; };
330 UInt64 CurrentBytes { get; };
331 UInt64 TotalBytes { get; };
332 };
333
334 runtimeclass PullImageOptions
335 {
336 PullImageOptions(String uri);
337
338 String Uri;
339 String RegistryAuth;
340 };
341
342 runtimeclass PushImageOptions
343 {
344 PushImageOptions(String image, String registryAuth);
345
346 String Image;
347 String RegistryAuth;
348 };
349
350 runtimeclass TagImageOptions
351 {
352 TagImageOptions(String image, String repository, String tag);
353
354 String Image;
355 String Repository;
356 String Tag;
357 };
358
359 runtimeclass ImageInfo
360 {
361 String Name { get; };
362 Windows.Storage.Streams.IBuffer Sha256 { get; };
363 UInt64 Size { get; };
364 Windows.Foundation.DateTime CreatedTimestamp { get; };
365 };
366
367 // Ensure wslcsdk.h and wslc.idl are also updated.
368 enum Error
369 {
370 ImageNotFound = 0x80040601,
371 ContainerPrefixAmbiguous = 0x80040602,
372 ContainerNotFound = 0x80040603,
373 VolumeNotFound = 0x80040604,
374 ContainerNotRunning = 0x80040605,
375 ContainerIsRunning = 0x80040606,
376 SessionReserved = 0x80040607,
377 InvalidSessionName = 0x80040608,
378 NetworkNotFound = 0x80040609,
379 WindowsUpdateSearchFailed = 0x8004060A,
380 SdkUpdateNeeded = 0x8004060B,
381 ContainerDisabled = 0x8004060C,
382 RegistryBlockedByPolicy = 0x8004060D,
383 VolumeNotAvailable = 0x8004060E,
384 ContainerDeleted = 0x80040613,
385 };
386 }