Struct VZVirtualMachineConfiguration

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

Available on crate feature VZVirtualMachineConfiguration only.

Virtual machine configuration.

VZVirtualMachineConfiguration defines the configuration of a VZVirtualMachine.

The configuration of devices is often done in two parts:

• Device configuration
• Device attachment

The device configuration defines the characteristics of the emulated hardware device. For example, for a network device, the device configuration defines the type of network adapter present in the virtual machine and its MAC address.

The device attachment defines the host machine’s resources that are exposed by the virtual device. For example, for a network device, the device attachment can be virtual network interface with a NAT to the real network.

Creating a virtual machine using the Virtualization framework requires the app to have the “com.apple.security.virtualization” entitlement. A VZVirtualMachineConfiguration is considered invalid if the application does not have the entitlement.

Configuring a virtual machine to run macOS

To configure a virtual machine running macOS:

• Set up a platform configuration of type VZMacPlatformConfiguration and set it on the platform property.
• Set up a VZMacOSBootLoader on the bootLoader property.
• Set the CPUCount and memorySize based on the guest’s VZMacOSConfigurationRequirements.
• Set up the main storage device as first device on storageDevices. Additional storage devices can be set up after the main storage.
• Set up the keyboards, pointingDevices and graphicsDevices devices.
• Set up any additional device as needed.

Configuring a virtual machine to run Linux

To configure a virtual machine running Linux:

• Set up a VZLinuxBootLoader on the bootLoader property.
• Set the CPUCount and memorySize.
• Set up any additional device as needed.

See: VZVirtualMachine

See also Apple’s documentation

Implementations

impl VZVirtualMachineConfiguration

pub unsafe fn bootLoader(&self) -> Option<Retained<VZBootLoader>>

Available on crate feature VZBootLoader only.

Boot loader used when the virtual machine starts.

See: VZLinuxBootLoader

See: VZMacOSBootLoader

pub unsafe fn setBootLoader(&self, boot_loader: Option<&VZBootLoader>)

Available on crate feature VZBootLoader only.

Setter for bootLoader.

pub unsafe fn memorySize(&self) -> u64

Virtual machine memory size in bytes.

The memory size must be a multiple of a 1 megabyte (1024 * 1024 bytes) between VZVirtualMachineConfiguration.minimumAllowedMemorySize and VZVirtualMachineConfiguration.maximumAllowedMemorySize.

The memorySize represents the total physical memory seen by a guest OS running in the virtual machine. Not all memory is allocated on start, the virtual machine allocates memory on demand.

See: VZVirtualMachineConfiguration.minimumAllowedMemorySize

See: VZVirtualMachineConfiguration.maximumAllowedMemorySize

pub unsafe fn setMemorySize(&self, memory_size: u64)

Setter for memorySize.

pub unsafe fn CPUCount(&self) -> NSUInteger

Number of CPUs.

The number of CPUs must be a value between VZVirtualMachineConfiguration.minimumAllowedCPUCount and VZVirtualMachineConfiguration.maximumAllowedCPUCount.

See: VZVirtualMachineConfiguration.minimumAllowedCPUCount

See: VZVirtualMachineConfiguration.maximumAllowedCPUCount

pub unsafe fn setCPUCount(&self, cpu_count: NSUInteger)

Setter for CPUCount.

pub unsafe fn platform(&self) -> Retained<VZPlatformConfiguration>

Available on crate feature VZPlatformConfiguration only.

The hardware platform to use.

Can be an instance of a VZGenericPlatformConfiguration or VZMacPlatformConfiguration. Defaults to VZGenericPlatformConfiguration. When restoring from saved state you must ensure your configuration matches that of the saved virtual machine.

See: VZGenericPlatformConfiguration

See: VZMacPlatformConfiguration

pub unsafe fn setPlatform(&self, platform: &VZPlatformConfiguration)

Available on crate feature VZPlatformConfiguration only.

Setter for platform.

pub unsafe fn audioDevices( &self, ) -> Retained<NSArray<VZAudioDeviceConfiguration>>

Available on crate feature VZAudioDeviceConfiguration only.

List of audio devices. Empty by default.

See: VZVirtioSoundDeviceConfiguration

pub unsafe fn setAudioDevices( &self, audio_devices: &NSArray<VZAudioDeviceConfiguration>, )

Available on crate feature VZAudioDeviceConfiguration only.

Setter for audioDevices.

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

Available on crate feature VZConsoleDeviceConfiguration only.

List of console devices. Empty by default.

See: VZVirtioConsoleDeviceConfiguration

pub unsafe fn setConsoleDevices( &self, console_devices: &NSArray<VZConsoleDeviceConfiguration>, )

Available on crate feature VZConsoleDeviceConfiguration only.

Setter for consoleDevices.

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

Available on crate feature VZDirectorySharingDeviceConfiguration only.

List of directory sharing devices. Empty by default.

See: VZVirtioFileSystemDeviceConfiguration

pub unsafe fn setDirectorySharingDevices( &self, directory_sharing_devices: &NSArray<VZDirectorySharingDeviceConfiguration>, )

Available on crate feature VZDirectorySharingDeviceConfiguration only.

Setter for directorySharingDevices.

pub unsafe fn entropyDevices( &self, ) -> Retained<NSArray<VZEntropyDeviceConfiguration>>

Available on crate feature VZEntropyDeviceConfiguration only.

List of entropy devices. Empty by default.

See: VZVirtioEntropyDeviceConfiguration

pub unsafe fn setEntropyDevices( &self, entropy_devices: &NSArray<VZEntropyDeviceConfiguration>, )

Available on crate feature VZEntropyDeviceConfiguration only.

Setter for entropyDevices.

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

Available on crate feature VZMemoryBalloonDeviceConfiguration only.

List of memory balloon devices. Empty by default.

See: VZVirtioTraditionalMemoryBalloonDeviceConfiguration

pub unsafe fn setMemoryBalloonDevices( &self, memory_balloon_devices: &NSArray<VZMemoryBalloonDeviceConfiguration>, )

Available on crate feature VZMemoryBalloonDeviceConfiguration only.

Setter for memoryBalloonDevices.

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

Available on crate feature VZNetworkDeviceConfiguration only.

List of network adapters. Empty by default.

See: VZVirtioNetworkDeviceConfiguration

pub unsafe fn setNetworkDevices( &self, network_devices: &NSArray<VZNetworkDeviceConfiguration>, )

Available on crate feature VZNetworkDeviceConfiguration only.

Setter for networkDevices.

pub unsafe fn serialPorts(&self) -> Retained<NSArray<VZSerialPortConfiguration>>

Available on crate feature VZSerialPortConfiguration only.

List of serial ports. Empty by default.

See: VZVirtioConsoleDeviceSerialPortConfiguration

pub unsafe fn setSerialPorts( &self, serial_ports: &NSArray<VZSerialPortConfiguration>, )

Available on crate feature VZSerialPortConfiguration only.

Setter for serialPorts.

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

Available on crate feature VZSocketDeviceConfiguration only.

List of socket devices. Empty by default.

See: VZVirtioSocketDeviceConfiguration

pub unsafe fn setSocketDevices( &self, socket_devices: &NSArray<VZSocketDeviceConfiguration>, )

Available on crate feature VZSocketDeviceConfiguration only.

Setter for socketDevices.

pub unsafe fn storageDevices( &self, ) -> Retained<NSArray<VZStorageDeviceConfiguration>>

Available on crate feature VZStorageDeviceConfiguration only.

List of disk devices. Empty by default.

See: VZNVMExpressControllerDeviceConfiguration

See: VZUSBMassStorageDeviceConfiguration

See: VZVirtioBlockDeviceConfiguration

pub unsafe fn setStorageDevices( &self, storage_devices: &NSArray<VZStorageDeviceConfiguration>, )

Available on crate feature VZStorageDeviceConfiguration only.

Setter for storageDevices.

pub unsafe fn keyboards(&self) -> Retained<NSArray<VZKeyboardConfiguration>>

Available on crate feature VZKeyboardConfiguration only.

List of keyboards. Empty by default.

See: VZUSBKeyboardConfiguration

See: VZMacKeyboardConfiguration

pub unsafe fn setKeyboards(&self, keyboards: &NSArray<VZKeyboardConfiguration>)

Available on crate feature VZKeyboardConfiguration only.

Setter for keyboards.

pub unsafe fn pointingDevices( &self, ) -> Retained<NSArray<VZPointingDeviceConfiguration>>

Available on crate feature VZPointingDeviceConfiguration only.

List of pointing devices. Empty by default.

See: VZUSBScreenCoordinatePointingDeviceConfiguration

See: VZMacTrackpadConfiguration

pub unsafe fn setPointingDevices( &self, pointing_devices: &NSArray<VZPointingDeviceConfiguration>, )

Available on crate feature VZPointingDeviceConfiguration only.

Setter for pointingDevices.

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

Available on crate feature VZGraphicsDeviceConfiguration only.

List of graphics devices. Empty by default.

See: VZMacGraphicsDeviceConfiguration

pub unsafe fn setGraphicsDevices( &self, graphics_devices: &NSArray<VZGraphicsDeviceConfiguration>, )

Available on crate feature VZGraphicsDeviceConfiguration only.

Setter for graphicsDevices.

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

Available on crate feature VZUSBControllerConfiguration only.

List of USB Controllers. Empty by default.

This list represents a set of USB controllers that the virtual machine will start with. For each entry in this list, there will be a corresponding runtime object created in VZVirtualMachine.usbControllers property.

See: VZUSBControllerConfiguration

pub unsafe fn setUsbControllers( &self, usb_controllers: &NSArray<VZUSBControllerConfiguration>, )

Available on crate feature VZUSBControllerConfiguration only.

Setter for usbControllers.

impl VZVirtualMachineConfiguration

Methods declared on superclass NSObject.

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

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

impl VZVirtualMachineConfiguration

VZVirtualMachineConfigurationValidation. Virtual machine configuration runtime validation.

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

Validate the configuration.

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

Returns: YES if the configuration is valid.

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

Validate the configuration is savable.

Verify that a virtual machine with this configuration is savable. Not all configuration options can be safely saved and restored from file. If this evaluates to NO, the caller should expect future calls to saveMachineStateToURL:completionHandler: to fail.

Parameter error: If not nil, assigned with an error describing the unsupported configuration option.

Returns: YES if the configuration is savable.

pub unsafe fn minimumAllowedMemorySize() -> u64

: Minimum amount of memory required by virtual machines.

See: VZVirtualMachineConfiguration.memorySize

pub unsafe fn maximumAllowedMemorySize() -> u64

: Maximum amount of memory allowed for a virtual machine.

See: VZVirtualMachineConfiguration.memorySize

pub unsafe fn minimumAllowedCPUCount() -> NSUInteger

: Minimum number of CPUs for a virtual machine.

See: VZVirtualMachineConfiguration.CPUCount

pub unsafe fn maximumAllowedCPUCount() -> NSUInteger

: Maximum number of CPUs for a virtual machine.

See: VZVirtualMachineConfiguration.CPUCount

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 VZVirtualMachineConfiguration

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for VZVirtualMachineConfiguration

fn as_ref(&self) -> &NSObject

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

impl AsRef<VZVirtualMachineConfiguration> for VZVirtualMachineConfiguration

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for VZVirtualMachineConfiguration

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for VZVirtualMachineConfiguration

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for VZVirtualMachineConfiguration

const NAME: &'static str = "VZVirtualMachineConfiguration"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<VZVirtualMachineConfiguration 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 CopyingHelper for VZVirtualMachineConfiguration

type Result = VZVirtualMachineConfiguration

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for VZVirtualMachineConfiguration

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

Formats the value using the given formatter.

impl Deref for VZVirtualMachineConfiguration

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for VZVirtualMachineConfiguration

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 VZVirtualMachineConfiguration

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSCopying for VZVirtualMachineConfiguration

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSObjectProtocol for VZVirtualMachineConfiguration

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 VZVirtualMachineConfiguration

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 VZVirtualMachineConfiguration

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

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

impl DowncastTarget for VZVirtualMachineConfiguration

impl Eq for VZVirtualMachineConfiguration