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}