objc2_virtualization/generated/VZVirtualMachine.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5#[cfg(feature = "dispatch2")]
6use dispatch2::*;
7use objc2::__framework_prelude::*;
8use objc2_foundation::*;
9
10use crate::*;
11
12/// Execution state of the virtual machine.
13///
14/// See also [Apple's documentation](https://developer.apple.com/documentation/virtualization/vzvirtualmachinestate?language=objc)
15// NS_ENUM
16#[repr(transparent)]
17#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
18pub struct VZVirtualMachineState(pub NSInteger);
19impl VZVirtualMachineState {
20 /// Initial state before the virtual machine is started.
21 #[doc(alias = "VZVirtualMachineStateStopped")]
22 pub const Stopped: Self = Self(0);
23 /// Running virtual machine.
24 #[doc(alias = "VZVirtualMachineStateRunning")]
25 pub const Running: Self = Self(1);
26 /// A started virtual machine is paused. This state can only be transitioned from VZVirtualMachineStatePausing.
27 #[doc(alias = "VZVirtualMachineStatePaused")]
28 pub const Paused: Self = Self(2);
29 /// The virtual machine has encountered an internal error.
30 #[doc(alias = "VZVirtualMachineStateError")]
31 pub const Error: Self = Self(3);
32 /// The virtual machine is configuring the hardware and starting.
33 #[doc(alias = "VZVirtualMachineStateStarting")]
34 pub const Starting: Self = Self(4);
35 /// The virtual machine is being paused. This is the intermediate state between VZVirtualMachineStateRunning and VZVirtualMachineStatePaused.
36 #[doc(alias = "VZVirtualMachineStatePausing")]
37 pub const Pausing: Self = Self(5);
38 /// The virtual machine is being resumed. This is the intermediate state between VZVirtualMachineStatePaused and VZVirtualMachineStateRunning.
39 #[doc(alias = "VZVirtualMachineStateResuming")]
40 pub const Resuming: Self = Self(6);
41 /// The virtual machine is being stopped. This is the intermediate state between VZVirtualMachineStateRunning and VZVirtualMachineStateStop.
42 #[doc(alias = "VZVirtualMachineStateStopping")]
43 pub const Stopping: Self = Self(7);
44 /// The virtual machine is being saved. This is the intermediate state between VZVirtualMachineStatePaused and VZVirtualMachineStatePaused.
45 #[doc(alias = "VZVirtualMachineStateSaving")]
46 pub const Saving: Self = Self(8);
47 /// The virtual machine is being restored. This is the intermediate state between VZVirtualMachineStateStopped and either VZVirtualMachineStatePaused on success or VZVirtualMachineStateStopped on failure.
48 #[doc(alias = "VZVirtualMachineStateRestoring")]
49 pub const Restoring: Self = Self(9);
50}
51
52unsafe impl Encode for VZVirtualMachineState {
53 const ENCODING: Encoding = NSInteger::ENCODING;
54}
55
56unsafe impl RefEncode for VZVirtualMachineState {
57 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
58}
59
60extern_class!(
61 /// VZVirtualMachine represents the entire state of a single virtual machine.
62 ///
63 /// A Virtual Machine is the emulation of a complete hardware machine of the same architecture as the real hardware machine.
64 /// When executing the Virtual Machine, the Virtualization framework uses certain hardware resources and emulates others to provide isolation
65 /// and great performance.
66 ///
67 /// The definition of a virtual machine starts with its configuration. This is done by setting up a VZVirtualMachineConfiguration object.
68 /// Once configured, the virtual machine can be started with [VZVirtualMachine startWithCompletionHandler:].
69 ///
70 /// To install macOS on a virtual machine, configure a new virtual machine with a suitable VZMacPlatformConfiguration, then use a VZMacOSInstaller
71 /// to install the restore image on it.
72 ///
73 /// Creating a virtual machine using the Virtualization framework requires the app to have the "com.apple.security.virtualization" entitlement.
74 ///
75 /// See also: VZVirtualMachineConfiguration
76 ///
77 /// See also: VZMacOSInstaller
78 ///
79 /// See also [Apple's documentation](https://developer.apple.com/documentation/virtualization/vzvirtualmachine?language=objc)
80 #[unsafe(super(NSObject))]
81 #[derive(Debug, PartialEq, Eq, Hash)]
82 pub struct VZVirtualMachine;
83);
84
85extern_conformance!(
86 unsafe impl NSObjectProtocol for VZVirtualMachine {}
87);
88
89impl VZVirtualMachine {
90 extern_methods!(
91 #[unsafe(method(new))]
92 #[unsafe(method_family = new)]
93 pub unsafe fn new() -> Retained<Self>;
94
95 #[unsafe(method(init))]
96 #[unsafe(method_family = init)]
97 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
98
99 #[cfg(feature = "VZVirtualMachineConfiguration")]
100 /// Initialize the virtual machine.
101 ///
102 /// This initializer uses the main queue to operate the virtual machine. Every call must be done on the main queue and the callbacks are invoked
103 /// on the main queue.
104 ///
105 /// Parameter `configuration`: The configuration of the virtual machine.
106 /// The configuration must be valid. Validation can be performed at runtime with [VZVirtualMachineConfiguration validateWithError:].
107 /// The configuration is copied by the initializer.
108 #[unsafe(method(initWithConfiguration:))]
109 #[unsafe(method_family = init)]
110 pub unsafe fn initWithConfiguration(
111 this: Allocated<Self>,
112 configuration: &VZVirtualMachineConfiguration,
113 ) -> Retained<Self>;
114
115 #[cfg(all(feature = "VZVirtualMachineConfiguration", feature = "dispatch2"))]
116 /// Initialize the virtual machine.
117 ///
118 /// Parameter `configuration`: The configuration of the virtual machine.
119 /// The configuration must be valid. Validation can be performed at runtime with [VZVirtualMachineConfiguration validateWithError:].
120 /// The configuration is copied by the initializer.
121 ///
122 /// Parameter `queue`: The serial queue on which the virtual machine operates.
123 /// Every operation on the virtual machine must be done on that queue. The callbacks and delegate methods are invoked on that queue.
124 /// If the queue is not serial, the behavior is undefined.
125 #[unsafe(method(initWithConfiguration:queue:))]
126 #[unsafe(method_family = init)]
127 pub unsafe fn initWithConfiguration_queue(
128 this: Allocated<Self>,
129 configuration: &VZVirtualMachineConfiguration,
130 queue: &DispatchQueue,
131 ) -> Retained<Self>;
132
133 /// Indicate whether or not virtualization is available.
134 ///
135 /// If virtualization is unavailable, no VZVirtualMachineConfiguration will validate.
136 /// The validation error of the VZVirtualMachineConfiguration provides more information about why virtualization is unavailable.
137 #[unsafe(method(isSupported))]
138 #[unsafe(method_family = none)]
139 pub unsafe fn isSupported() -> bool;
140
141 /// Execution state of the virtual machine.
142 #[unsafe(method(state))]
143 #[unsafe(method_family = none)]
144 pub unsafe fn state(&self) -> VZVirtualMachineState;
145
146 #[cfg(feature = "VZVirtualMachineDelegate")]
147 /// The virtual machine delegate.
148 #[unsafe(method(delegate))]
149 #[unsafe(method_family = none)]
150 pub unsafe fn delegate(
151 &self,
152 ) -> Option<Retained<ProtocolObject<dyn VZVirtualMachineDelegate>>>;
153
154 #[cfg(feature = "VZVirtualMachineDelegate")]
155 /// This is a [weak property][objc2::topics::weak_property].
156 /// Setter for [`delegate`][Self::delegate].
157 #[unsafe(method(setDelegate:))]
158 #[unsafe(method_family = none)]
159 pub unsafe fn setDelegate(
160 &self,
161 delegate: Option<&ProtocolObject<dyn VZVirtualMachineDelegate>>,
162 );
163
164 /// Return YES if the machine is in a state that can be started.
165 ///
166 /// See: -[VZVirtualMachine startWithCompletionHandler:].
167 ///
168 /// See: -[VZVirtualMachine state]
169 #[unsafe(method(canStart))]
170 #[unsafe(method_family = none)]
171 pub unsafe fn canStart(&self) -> bool;
172
173 /// Return YES if the machine is in a state that can be stopped.
174 ///
175 /// See: -[VZVirtualMachine stopWithCompletionHandler:]
176 ///
177 /// See: -[VZVirtualMachine state]
178 #[unsafe(method(canStop))]
179 #[unsafe(method_family = none)]
180 pub unsafe fn canStop(&self) -> bool;
181
182 /// Return YES if the machine is in a state that can be paused.
183 ///
184 /// See: -[VZVirtualMachine pauseWithCompletionHandler:]
185 ///
186 /// See: -[VZVirtualMachine state]
187 #[unsafe(method(canPause))]
188 #[unsafe(method_family = none)]
189 pub unsafe fn canPause(&self) -> bool;
190
191 /// Return YES if the machine is in a state that can be resumed.
192 ///
193 /// See: -[VZVirtualMachine resumeWithCompletionHandler:]
194 ///
195 /// See: -[VZVirtualMachine state]
196 #[unsafe(method(canResume))]
197 #[unsafe(method_family = none)]
198 pub unsafe fn canResume(&self) -> bool;
199
200 /// Returns whether the machine is in a state where the guest can be asked to stop.
201 ///
202 /// See: -[VZVirtualMachine requestStopWithError:]
203 ///
204 /// See: -[VZVirtualMachine state]
205 #[unsafe(method(canRequestStop))]
206 #[unsafe(method_family = none)]
207 pub unsafe fn canRequestStop(&self) -> bool;
208
209 #[cfg(feature = "VZConsoleDevice")]
210 /// Return the list of console devices configured on this virtual machine. Return an empty array if no console device is configured.
211 ///
212 /// See: VZVirtioConsoleDeviceConfiguration
213 ///
214 /// See: VZVirtualMachineConfiguration
215 #[unsafe(method(consoleDevices))]
216 #[unsafe(method_family = none)]
217 pub unsafe fn consoleDevices(&self) -> Retained<NSArray<VZConsoleDevice>>;
218
219 #[cfg(feature = "VZDirectorySharingDevice")]
220 /// Return the list of directory sharing devices configured on this virtual machine. Return an empty array if no directory sharing device is configured.
221 ///
222 /// See: VZVirtioFileSystemDeviceConfiguration
223 ///
224 /// See: VZVirtualMachineConfiguration
225 #[unsafe(method(directorySharingDevices))]
226 #[unsafe(method_family = none)]
227 pub unsafe fn directorySharingDevices(&self)
228 -> Retained<NSArray<VZDirectorySharingDevice>>;
229
230 #[cfg(feature = "VZGraphicsDevice")]
231 /// Return the list of graphics devices configured on this virtual machine. Return an empty array if no graphics device is configured.
232 ///
233 /// See: VZGraphicsDeviceConfiguration
234 ///
235 /// See: VZVirtualMachineConfiguration
236 #[unsafe(method(graphicsDevices))]
237 #[unsafe(method_family = none)]
238 pub unsafe fn graphicsDevices(&self) -> Retained<NSArray<VZGraphicsDevice>>;
239
240 #[cfg(feature = "VZMemoryBalloonDevice")]
241 /// Return the list of memory balloon devices configured on this virtual machine. Return an empty array if no memory balloon device is configured.
242 ///
243 /// See: VZVirtioTraditionalMemoryBalloonDeviceConfiguration
244 ///
245 /// See: VZVirtualMachineConfiguration
246 #[unsafe(method(memoryBalloonDevices))]
247 #[unsafe(method_family = none)]
248 pub unsafe fn memoryBalloonDevices(&self) -> Retained<NSArray<VZMemoryBalloonDevice>>;
249
250 #[cfg(feature = "VZNetworkDevice")]
251 /// Return the list of network devices configured on this virtual machine. Return an empty array if no network device is configured.
252 ///
253 /// See: VZVirtioNetworkDeviceConfiguration
254 ///
255 /// See: VZVirtualMachineConfiguration
256 #[unsafe(method(networkDevices))]
257 #[unsafe(method_family = none)]
258 pub unsafe fn networkDevices(&self) -> Retained<NSArray<VZNetworkDevice>>;
259
260 #[cfg(feature = "VZSocketDevice")]
261 /// Return the list of socket devices configured on this virtual machine. Return an empty array if no socket device is configured.
262 ///
263 /// See: VZVirtioSocketDeviceConfiguration
264 ///
265 /// See: VZVirtualMachineConfiguration
266 #[unsafe(method(socketDevices))]
267 #[unsafe(method_family = none)]
268 pub unsafe fn socketDevices(&self) -> Retained<NSArray<VZSocketDevice>>;
269
270 #[cfg(feature = "VZUSBController")]
271 /// Return the list of USB controllers configured on this virtual machine. Return an empty array if no USB controller is configured.
272 ///
273 /// See: VZUSBControllerConfiguration
274 ///
275 /// See: VZVirtualMachineConfiguration
276 #[unsafe(method(usbControllers))]
277 #[unsafe(method_family = none)]
278 pub unsafe fn usbControllers(&self) -> Retained<NSArray<VZUSBController>>;
279
280 #[cfg(feature = "block2")]
281 /// Start a virtual machine.
282 ///
283 /// Start a virtual machine that is in either Stopped or Error state.
284 ///
285 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully started or on error.
286 /// The error parameter passed to the block is nil if the start was successful.
287 #[unsafe(method(startWithCompletionHandler:))]
288 #[unsafe(method_family = none)]
289 pub unsafe fn startWithCompletionHandler(
290 &self,
291 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
292 );
293
294 #[cfg(all(feature = "VZVirtualMachineStartOptions", feature = "block2"))]
295 /// Start a virtual machine with options.
296 ///
297 /// Start a virtual machine that is in either Stopped or Error state.
298 ///
299 /// Parameter `options`: Options used to control how the virtual machine is started.
300 ///
301 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully started or on error.
302 /// The error parameter passed to the block is nil if the start was successful.
303 ///
304 /// See also: VZMacOSVirtualMachineStartOptions
305 #[unsafe(method(startWithOptions:completionHandler:))]
306 #[unsafe(method_family = none)]
307 pub unsafe fn startWithOptions_completionHandler(
308 &self,
309 options: &VZVirtualMachineStartOptions,
310 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
311 );
312
313 #[cfg(feature = "block2")]
314 /// Stop a virtual machine.
315 ///
316 /// Stop a virtual machine that is in either Running or Paused state.
317 ///
318 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully stopped or on error.
319 /// The error parameter passed to the block is nil if the stop was successful.
320 ///
321 /// This is a destructive operation. It stops the virtual machine without giving the guest a chance to stop cleanly.
322 ///
323 /// See also: -[VZVirtualMachine requestStopWithError:]
324 #[unsafe(method(stopWithCompletionHandler:))]
325 #[unsafe(method_family = none)]
326 pub unsafe fn stopWithCompletionHandler(
327 &self,
328 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
329 );
330
331 #[cfg(feature = "block2")]
332 /// Pause a virtual machine.
333 ///
334 /// Pause a virtual machine that is in Running state.
335 ///
336 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully paused or on error.
337 /// The error parameter passed to the block is nil if the pause was successful.
338 #[unsafe(method(pauseWithCompletionHandler:))]
339 #[unsafe(method_family = none)]
340 pub unsafe fn pauseWithCompletionHandler(
341 &self,
342 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
343 );
344
345 #[cfg(feature = "block2")]
346 /// Resume a virtual machine.
347 ///
348 /// Resume a virtual machine that is in the Paused state.
349 ///
350 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully resumed or on error.
351 /// The error parameter passed to the block is nil if the resumption was successful.
352 #[unsafe(method(resumeWithCompletionHandler:))]
353 #[unsafe(method_family = none)]
354 pub unsafe fn resumeWithCompletionHandler(
355 &self,
356 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
357 );
358
359 #[cfg(feature = "block2")]
360 /// Restore a virtual machine.
361 ///
362 /// Restore a stopped virtual machine to a state previously saved to file through `saveMachineStateToURL:completionHandler:`.
363 ///
364 /// If the file cannot be read, or contains otherwise invalid contents, this operation will fail with a `VZErrorRestore` error.
365 /// If the virtual machine is not in the stopped state, this operation will fail with a `VZErrorInvalidVirtualMachineStateTransition` error.
366 /// If the virtual machine cannot be started due to an internal error, this operation will fail with a `VZErrorInternal` error.
367 /// The `VZVirtualMachineConfiguration` must also support restoring, which can be checked with `-[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]`.
368 ///
369 /// If this operation fails, the virtual machine state is unchanged.
370 /// If successful, the virtual machine is restored and placed in the paused state.
371 ///
372 /// Parameter `saveFileURL`: URL to file containing saved state of a suspended virtual machine.
373 /// The file must have been generated by `saveMachineStateToURL:completionHandler:` on the same host.
374 /// Otherwise, this operation will fail with a `VZErrorRestore` error indicating a permission denied failure reason.
375 ///
376 /// The virtual machine must also be configured compatibly with the state contained in the file.
377 /// If the `VZVirtualMachineConfiguration` is not compatible with the content of the file, this operation will fail with a `VZErrorRestore` error indicating an invalid argument failure reason.
378 ///
379 /// Files generated with `saveMachineStateToURL:completionHandler:` on a software version that is newer than the current version will also be rejected with an invalid argument failure reason.
380 /// In some cases, `restoreMachineStateFromURL:completionHandler:` can fail if a software update has changed the host in a way that would be incompatible with the previous format.
381 /// In this case, an invalid argument error will be surfaced. In most cases, the virtual machine should be restarted with `startWithCompletionHandler:`.
382 ///
383 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully started or on error.
384 /// The error parameter passed to the block is nil if the restore was successful.
385 ///
386 /// See: -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]
387 #[unsafe(method(restoreMachineStateFromURL:completionHandler:))]
388 #[unsafe(method_family = none)]
389 pub unsafe fn restoreMachineStateFromURL_completionHandler(
390 &self,
391 save_file_url: &NSURL,
392 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
393 );
394
395 #[cfg(feature = "block2")]
396 /// Save a virtual machine.
397 ///
398 /// Save a paused virtual machine to file.
399 /// The contents of this file can be used later to restore the state of the paused virtual machine.
400 ///
401 /// If the virtual machine is not paused, this operation will fail with a `VZErrorInvalidVirtualMachineState` error.
402 /// If the virtual machine cannot be saved, this operation will fail with a `VZErrorSave` error.
403 /// The `VZVirtualMachineConfiguration` must also support saving, which can be checked with `-[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]`.
404 ///
405 /// If this operation fails, the virtual machine state is unchanged.
406 /// If successful, the file is written out and the virtual machine state is unchanged.
407 ///
408 /// Parameter `saveFileURL`: URL to location where the saved state of the virtual machine is to be written.
409 /// Each file is protected by an encryption key that is tied to the host on which it is created.
410 ///
411 /// Parameter `completionHandler`: Block called after the virtual machine has been successfully saved or on error.
412 /// The error parameter passed to the block is nil if the save was successful.
413 ///
414 /// See: -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]
415 #[unsafe(method(saveMachineStateToURL:completionHandler:))]
416 #[unsafe(method_family = none)]
417 pub unsafe fn saveMachineStateToURL_completionHandler(
418 &self,
419 save_file_url: &NSURL,
420 completion_handler: &block2::DynBlock<dyn Fn(*mut NSError)>,
421 );
422
423 /// Request that the guest turns itself off.
424 ///
425 /// Parameter `error`: If not nil, assigned with the error if the request failed.
426 ///
427 /// Returns: YES if the request was made successfully.
428 ///
429 /// The -[VZVirtualMachineDelegate guestDidStopVirtualMachine:] delegate method is invoked when the guest has turned itself off.
430 ///
431 /// See also: -[VZVirtualMachineDelegate guestDidStopVirtualMachine:].
432 #[unsafe(method(requestStopWithError:_))]
433 #[unsafe(method_family = none)]
434 pub unsafe fn requestStopWithError(&self) -> Result<(), Retained<NSError>>;
435 );
436}