Struct VZVirtualMachine

#[repr(C)]
pub struct VZVirtualMachine { /* private fields */ }

Available on crate feature VZVirtualMachine only.

VZVirtualMachine represents the entire state of a single virtual machine.

A Virtual Machine is the emulation of a complete hardware machine of the same architecture as the real hardware machine. When executing the Virtual Machine, the Virtualization framework uses certain hardware resources and emulates others to provide isolation and great performance.

The definition of a virtual machine starts with its configuration. This is done by setting up a VZVirtualMachineConfiguration object. Once configured, the virtual machine can be started with [VZVirtualMachine startWithCompletionHandler:].

To install macOS on a virtual machine, configure a new virtual machine with a suitable VZMacPlatformConfiguration, then use a VZMacOSInstaller to install the restore image on it.

Creating a virtual machine using the Virtualization framework requires the app to have the “com.apple.security.virtualization” entitlement.

See also: VZVirtualMachineConfiguration

See also: VZMacOSInstaller

See also Apple’s documentation

Implementations

impl VZVirtualMachine

pub unsafe fn new() -> Retained<Self>

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn initWithConfiguration( this: Allocated<Self>, configuration: &VZVirtualMachineConfiguration, ) -> Retained<Self>

Available on crate feature VZVirtualMachineConfiguration only.

Initialize the virtual machine.

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 on the main queue.

Parameter configuration: The configuration of the virtual machine. The configuration must be valid. Validation can be performed at runtime with [VZVirtualMachineConfiguration validateWithError:]. The configuration is copied by the initializer.

pub unsafe fn initWithConfiguration_queue( this: Allocated<Self>, configuration: &VZVirtualMachineConfiguration, queue: &DispatchQueue, ) -> Retained<Self>

Available on crate features VZVirtualMachineConfiguration and dispatch2 only.

Initialize the virtual machine.

Parameter configuration: The configuration of the virtual machine. The configuration must be valid. Validation can be performed at runtime with [VZVirtualMachineConfiguration validateWithError:]. The configuration is copied by the initializer.

Parameter queue: The serial queue on which the virtual machine operates. Every operation on the virtual machine must be done on that queue. The callbacks and delegate methods are invoked on that queue. If the queue is not serial, the behavior is undefined.

pub unsafe fn isSupported() -> bool

Indicate whether or not virtualization is available.

If virtualization is unavailable, no VZVirtualMachineConfiguration will validate. The validation error of the VZVirtualMachineConfiguration provides more information about why virtualization is unavailable.

pub unsafe fn state(&self) -> VZVirtualMachineState

Execution state of the virtual machine.

pub unsafe fn delegate( &self, ) -> Option<Retained<ProtocolObject<dyn VZVirtualMachineDelegate>>>

Available on crate feature VZVirtualMachineDelegate only.

The virtual machine delegate.

pub unsafe fn setDelegate( &self, delegate: Option<&ProtocolObject<dyn VZVirtualMachineDelegate>>, )

Available on crate feature VZVirtualMachineDelegate only.

This is a weak property. Setter for delegate.

pub unsafe fn canStart(&self) -> bool

Return YES if the machine is in a state that can be started.

See: -[VZVirtualMachine startWithCompletionHandler:].

See: -[VZVirtualMachine state]

pub unsafe fn canStop(&self) -> bool

Return YES if the machine is in a state that can be stopped.

See: -[VZVirtualMachine stopWithCompletionHandler:]

See: -[VZVirtualMachine state]

pub unsafe fn canPause(&self) -> bool

Return YES if the machine is in a state that can be paused.

See: -[VZVirtualMachine pauseWithCompletionHandler:]

See: -[VZVirtualMachine state]

pub unsafe fn canResume(&self) -> bool

Return YES if the machine is in a state that can be resumed.

See: -[VZVirtualMachine resumeWithCompletionHandler:]

See: -[VZVirtualMachine state]

pub unsafe fn canRequestStop(&self) -> bool

Returns whether the machine is in a state where the guest can be asked to stop.

See: -[VZVirtualMachine requestStopWithError:]

See: -[VZVirtualMachine state]

pub unsafe fn consoleDevices(&self) -> Retained<NSArray<VZConsoleDevice>>

Available on crate feature VZConsoleDevice only.

Return the list of console devices configured on this virtual machine. Return an empty array if no console device is configured.

See: VZVirtioConsoleDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn directorySharingDevices( &self, ) -> Retained<NSArray<VZDirectorySharingDevice>>

Available on crate feature VZDirectorySharingDevice only.

Return the list of directory sharing devices configured on this virtual machine. Return an empty array if no directory sharing device is configured.

See: VZVirtioFileSystemDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn graphicsDevices(&self) -> Retained<NSArray<VZGraphicsDevice>>

Available on crate feature VZGraphicsDevice only.

Return the list of graphics devices configured on this virtual machine. Return an empty array if no graphics device is configured.

See: VZGraphicsDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn memoryBalloonDevices( &self, ) -> Retained<NSArray<VZMemoryBalloonDevice>>

Available on crate feature VZMemoryBalloonDevice only.

Return the list of memory balloon devices configured on this virtual machine. Return an empty array if no memory balloon device is configured.

See: VZVirtioTraditionalMemoryBalloonDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn networkDevices(&self) -> Retained<NSArray<VZNetworkDevice>>

Available on crate feature VZNetworkDevice only.

Return the list of network devices configured on this virtual machine. Return an empty array if no network device is configured.

See: VZVirtioNetworkDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn socketDevices(&self) -> Retained<NSArray<VZSocketDevice>>

Available on crate feature VZSocketDevice only.

Return the list of socket devices configured on this virtual machine. Return an empty array if no socket device is configured.

See: VZVirtioSocketDeviceConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn usbControllers(&self) -> Retained<NSArray<VZUSBController>>

Available on crate feature VZUSBController only.

Return the list of USB controllers configured on this virtual machine. Return an empty array if no USB controller is configured.

See: VZUSBControllerConfiguration

See: VZVirtualMachineConfiguration

pub unsafe fn startWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Start a virtual machine.

Start a virtual machine that is in either Stopped or Error state.

Parameter completionHandler: Block called after the virtual machine has been successfully started or on error. The error parameter passed to the block is nil if the start was successful.

pub unsafe fn startWithOptions_completionHandler( &self, options: &VZVirtualMachineStartOptions, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate features VZVirtualMachineStartOptions and block2 only.

Start a virtual machine with options.

Start a virtual machine that is in either Stopped or Error state.

Parameter options: Options used to control how the virtual machine is started.

Parameter completionHandler: Block called after the virtual machine has been successfully started or on error. The error parameter passed to the block is nil if the start was successful.

See also: VZMacOSVirtualMachineStartOptions

pub unsafe fn stopWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Stop a virtual machine.

Stop a virtual machine that is in either Running or Paused state.

Parameter completionHandler: Block called after the virtual machine has been successfully stopped or on error. The error parameter passed to the block is nil if the stop was successful.

This is a destructive operation. It stops the virtual machine without giving the guest a chance to stop cleanly.

See also: -[VZVirtualMachine requestStopWithError:]

pub unsafe fn pauseWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Pause a virtual machine.

Pause a virtual machine that is in Running state.

Parameter completionHandler: Block called after the virtual machine has been successfully paused or on error. The error parameter passed to the block is nil if the pause was successful.

pub unsafe fn resumeWithCompletionHandler( &self, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Resume a virtual machine.

Resume a virtual machine that is in the Paused state.

Parameter completionHandler: Block called after the virtual machine has been successfully resumed or on error. The error parameter passed to the block is nil if the resumption was successful.

pub unsafe fn restoreMachineStateFromURL_completionHandler( &self, save_file_url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Restore a virtual machine.

Restore a stopped virtual machine to a state previously saved to file through saveMachineStateToURL:completionHandler:.

If the file cannot be read, or contains otherwise invalid contents, this operation will fail with a VZErrorRestore error. If the virtual machine is not in the stopped state, this operation will fail with a VZErrorInvalidVirtualMachineStateTransition error. If the virtual machine cannot be started due to an internal error, this operation will fail with a VZErrorInternal error. The VZVirtualMachineConfiguration must also support restoring, which can be checked with -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:].

If this operation fails, the virtual machine state is unchanged. If successful, the virtual machine is restored and placed in the paused state.

Parameter saveFileURL: URL to file containing saved state of a suspended virtual machine. The file must have been generated by saveMachineStateToURL:completionHandler: on the same host. Otherwise, this operation will fail with a VZErrorRestore error indicating a permission denied failure reason.

The virtual machine must also be configured compatibly with the state contained in the file. 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.

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. 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. In this case, an invalid argument error will be surfaced. In most cases, the virtual machine should be restarted with startWithCompletionHandler:.

Parameter completionHandler: Block called after the virtual machine has been successfully started or on error. The error parameter passed to the block is nil if the restore was successful.

See: -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]

pub unsafe fn saveMachineStateToURL_completionHandler( &self, save_file_url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )

Available on crate feature block2 only.

Save a virtual machine.

Save a paused virtual machine to file. The contents of this file can be used later to restore the state of the paused virtual machine.

If the virtual machine is not paused, this operation will fail with a VZErrorInvalidVirtualMachineState error. If the virtual machine cannot be saved, this operation will fail with a VZErrorSave error. The VZVirtualMachineConfiguration must also support saving, which can be checked with -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:].

If this operation fails, the virtual machine state is unchanged. If successful, the file is written out and the virtual machine state is unchanged.

Parameter saveFileURL: URL to location where the saved state of the virtual machine is to be written. Each file is protected by an encryption key that is tied to the host on which it is created.

Parameter completionHandler: Block called after the virtual machine has been successfully saved or on error. The error parameter passed to the block is nil if the save was successful.

See: -[VZVirtualMachineConfiguration validateSaveRestoreSupportWithError:]

pub unsafe fn requestStopWithError(&self) -> Result<(), Retained<NSError>>

Request that the guest turns itself off.

Parameter error: If not nil, assigned with the error if the request failed.

Returns: YES if the request was made successfully.

The -[VZVirtualMachineDelegate guestDidStopVirtualMachine:] delegate method is invoked when the guest has turned itself off.

See also: -[VZVirtualMachineDelegate guestDidStopVirtualMachine:].

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for VZVirtualMachine

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for VZVirtualMachine

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<VZVirtualMachine> for VZVirtualMachine

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for VZVirtualMachine

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for VZVirtualMachine

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for VZVirtualMachine

const NAME: &'static str = "VZVirtualMachine"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<VZVirtualMachine as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for VZVirtualMachine

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for VZVirtualMachine

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for VZVirtualMachine

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for VZVirtualMachine

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for VZVirtualMachine

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for VZVirtualMachine

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for VZVirtualMachine

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for VZVirtualMachine

impl Eq for VZVirtualMachine