objc2_virtualization/generated/
VZNetworkBlockDeviceStorageDeviceAttachment.rs

1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10extern_class!(
11    /// Storage device attachment backed by a Network Block Device (NBD) client.
12    ///
13    /// This storage device attachment provides an NBD client implementation. The NBD client is connected
14    /// to an NBD server referred to by an NBD Uniform Resource Indicator (URI), represented as an URL in
15    /// this API. The NBD server runs outside of Virtualization framework and is not controlled by
16    /// Virtualization framework. The NBD client forwards the guest's I/O operations to the NBD server,
17    /// where the I/O operations are handled.
18    ///
19    /// The NBD client will attempt to connect to the NBD server referred to by the URL when you start the virtual
20    /// machine (e.g. when `[VZVirtualMachine startWithCompletionHandler:]` is called). A connection attempt is NOT
21    /// made when the attachment object is initialized. Reconnection attempts will take place throughout the life
22    /// cycle of the virtual machine when the NBD client encounters a recoverable error such as connection timeout
23    /// and unexpected connection errors. The NBD client will disconnect from the server when the virtual machine
24    /// shuts down.
25    ///
26    /// Using this attachment requires the app to have the "com.apple.security.network.client" entitlement as this attachment opens an outgoing
27    /// network connection.
28    ///
29    /// For more information about NBD, see https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md.
30    /// For more information about the NBD URL format, see https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.
31    ///
32    /// An example use of this API is:
33    /// ```text
34    /// NSURL *url = [[NSURL alloc] initWithString:
35    /// "
36    /// nbd://localhost:10809/myDisk"]
37    /// NSError *error = nil;
38    /// VZNetworkBlockDeviceStorageDeviceAttachment *attachment =
39    /// [[VZNetworkBlockDeviceStorageDeviceAttachment alloc] initWithURL:url
40    /// timeout:5.0
41    /// forcedReadOnly:NO
42    /// synchronizationMode:VZDiskSynchronizationModeFull
43    /// error:
44    /// &error
45    /// ];
46    ///
47    /// if (!attachment) {
48    /// // Handle the `error`.
49    /// }
50    ///
51    /// VZVirtioBlockDeviceConfiguration *blockDevice = [[VZVirtioBlockDeviceConfiguration alloc] initWithAttachment:attachment];
52    /// ```
53    ///
54    /// See also [Apple's documentation](https://developer.apple.com/documentation/virtualization/vznetworkblockdevicestoragedeviceattachment?language=objc)
55    #[unsafe(super(VZStorageDeviceAttachment, NSObject))]
56    #[derive(Debug, PartialEq, Eq, Hash)]
57    #[cfg(feature = "VZStorageDeviceAttachment")]
58    pub struct VZNetworkBlockDeviceStorageDeviceAttachment;
59);
60
61#[cfg(feature = "VZStorageDeviceAttachment")]
62extern_conformance!(
63    unsafe impl NSObjectProtocol for VZNetworkBlockDeviceStorageDeviceAttachment {}
64);
65
66#[cfg(feature = "VZStorageDeviceAttachment")]
67impl VZNetworkBlockDeviceStorageDeviceAttachment {
68    extern_methods!(
69        #[cfg(feature = "VZDiskSynchronizationMode")]
70        /// Initialize the attachment from an NBD Uniform Resource Indicator (URI) represented as an URL.
71        ///
72        /// Parameter `URL`: The URL referring to the NBD server to which the NBD client is to be connected.
73        ///
74        /// Parameter `timeout`: The timeout value in seconds for the connection between the client and server. When the timeout expires, an attempt to reconnect with the server will take place.
75        ///
76        /// Parameter `forcedReadOnly`: If YES, the disk attachment is forced to be read-only, regardless of whether or not the NBD server supports write requests.
77        ///
78        /// Parameter `error`: If not nil, assigned with the error if the initialization failed.
79        ///
80        /// Returns: An initialized `VZNetworkBlockDeviceStorageDeviceAttachment` or nil if there was an error.
81        ///
82        /// The `forcedReadOnly` parameter affects how the NBD client is exposed to the guest operating system
83        /// by the storage controller. As part of the NBD protocol, whether or not the disk exposed by the NBD client is
84        /// read-only is advertised by the NBD server during the handshake phase of the protocol. Setting `forcedReadOnly`
85        /// to YES will force the NBD client to show up as read-only to the guest regardless of whether or not the NBD
86        /// server advertises itself as read-only.
87        #[unsafe(method(initWithURL:timeout:forcedReadOnly:synchronizationMode:error:_))]
88        #[unsafe(method_family = init)]
89        pub unsafe fn initWithURL_timeout_forcedReadOnly_synchronizationMode_error(
90            this: Allocated<Self>,
91            url: &NSURL,
92            timeout: NSTimeInterval,
93            forced_read_only: bool,
94            synchronization_mode: VZDiskSynchronizationMode,
95        ) -> Result<Retained<Self>, Retained<NSError>>;
96
97        /// Convenience initializer to create the attachment from an NBD URL.
98        ///
99        /// Parameter `URL`: The URL referring to the NBD server to which the NBD client is to be connected.
100        ///
101        /// Parameter `error`: If not nil, assigned with the error if the initialization failed.
102        ///
103        /// Returns: An initialized `VZNetworkBlockDeviceStorageDeviceAttachment` or nil if there was an error.
104        ///
105        /// This initializer automatically assigns optimized default values for the `timeout`,
106        /// `forcedReadOnly`, and `synchronizationMode` properties.
107        #[unsafe(method(initWithURL:error:_))]
108        #[unsafe(method_family = init)]
109        pub unsafe fn initWithURL_error(
110            this: Allocated<Self>,
111            url: &NSURL,
112        ) -> Result<Retained<Self>, Retained<NSError>>;
113
114        /// Check if URL is a valid NBD URL.
115        ///
116        /// Parameter `URL`: The NBD URL to validate.
117        ///
118        /// Parameter `error`: If not nil, assigned with an error describing why the URL is not valid.
119        ///
120        /// See https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md for more detailed descriptions
121        /// of valid URIs.
122        ///
123        /// This method checks that the URL is well-formed, it does not attempt to access the URL.
124        #[unsafe(method(validateURL:error:_))]
125        #[unsafe(method_family = none)]
126        pub unsafe fn validateURL_error(url: &NSURL) -> Result<(), Retained<NSError>>;
127
128        /// URL referring to the NBD server to which the NBD client is to be connected.
129        #[unsafe(method(URL))]
130        #[unsafe(method_family = none)]
131        pub unsafe fn URL(&self) -> Retained<NSURL>;
132
133        /// The timeout value in seconds for the connection between the client and server. When the timeout expires, an attempt to reconnect with the server will take place.
134        #[unsafe(method(timeout))]
135        #[unsafe(method_family = none)]
136        pub unsafe fn timeout(&self) -> NSTimeInterval;
137
138        /// Whether the underlying disk attachment is forced to be read-only.
139        ///
140        /// The `forcedReadOnly` parameter affects how the NBD client is exposed to the guest operating system
141        /// by the storage controller. As part of the NBD protocol, whether or not the disk exposed by the NBD client
142        /// is read-only is advertised by the NBD server during the handshake phase of the protocol. Setting
143        /// `forcedReadOnly` to YES will force the NBD client to show up as read-only to the
144        /// guest regardless of whether or not the NBD server advertises itself as read-only.
145        #[unsafe(method(isForcedReadOnly))]
146        #[unsafe(method_family = none)]
147        pub unsafe fn isForcedReadOnly(&self) -> bool;
148
149        #[cfg(feature = "VZDiskSynchronizationMode")]
150        /// The mode in which the NBD client synchronizes data with the NBD server.
151        #[unsafe(method(synchronizationMode))]
152        #[unsafe(method_family = none)]
153        pub unsafe fn synchronizationMode(&self) -> VZDiskSynchronizationMode;
154
155        /// The attachment's delegate.
156        #[unsafe(method(delegate))]
157        #[unsafe(method_family = none)]
158        pub unsafe fn delegate(
159            &self,
160        ) -> Option<Retained<ProtocolObject<dyn VZNetworkBlockDeviceStorageDeviceAttachmentDelegate>>>;
161
162        /// This is a [weak property][objc2::topics::weak_property].
163        /// Setter for [`delegate`][Self::delegate].
164        #[unsafe(method(setDelegate:))]
165        #[unsafe(method_family = none)]
166        pub unsafe fn setDelegate(
167            &self,
168            delegate: Option<
169                &ProtocolObject<dyn VZNetworkBlockDeviceStorageDeviceAttachmentDelegate>,
170            >,
171        );
172    );
173}
174
175/// Methods declared on superclass `VZStorageDeviceAttachment`.
176#[cfg(feature = "VZStorageDeviceAttachment")]
177impl VZNetworkBlockDeviceStorageDeviceAttachment {
178    extern_methods!(
179        #[unsafe(method(new))]
180        #[unsafe(method_family = new)]
181        pub unsafe fn new() -> Retained<Self>;
182
183        #[unsafe(method(init))]
184        #[unsafe(method_family = init)]
185        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
186    );
187}
188
189extern_protocol!(
190    /// A class conforming to VZNetworkBlockDeviceStorageDeviceAttachmentDelegate can provide
191    /// methods for tracking the attachment's state.
192    ///
193    /// See also [Apple's documentation](https://developer.apple.com/documentation/virtualization/vznetworkblockdevicestoragedeviceattachmentdelegate?language=objc)
194    pub unsafe trait VZNetworkBlockDeviceStorageDeviceAttachmentDelegate:
195        NSObjectProtocol
196    {
197        #[cfg(feature = "VZStorageDeviceAttachment")]
198        /// Invoked when the NBD client has successfully connected/reconnected with the server.
199        ///
200        /// Parameter `attachment`: The attachment object invoking the delegate method.
201        ///
202        /// Connection with the server will take place when the virtual machine is first started, and reconnection
203        /// attempts will take place when the connection times out or when the NBD client has encountered a recoverable
204        /// error, such as an I/O error from the server. The method may be invoked multiple times during a virtual
205        /// machine's life cycle. Reconnections are transparent to the guest.
206        #[optional]
207        #[unsafe(method(attachmentWasConnected:))]
208        #[unsafe(method_family = none)]
209        unsafe fn attachmentWasConnected(
210            &self,
211            attachment: &VZNetworkBlockDeviceStorageDeviceAttachment,
212        );
213
214        #[cfg(feature = "VZStorageDeviceAttachment")]
215        /// Invoked when the NBD client has encountered a non-recoverable error.
216        ///
217        /// Parameter `attachment`: The attachment object invoking the delegate method.
218        ///
219        /// Parameter `error`: The error.
220        ///
221        /// The NBD client will be in a non-functional state after this method is invoked.
222        #[optional]
223        #[unsafe(method(attachment:didEncounterError:))]
224        #[unsafe(method_family = none)]
225        unsafe fn attachment_didEncounterError(
226            &self,
227            attachment: &VZNetworkBlockDeviceStorageDeviceAttachment,
228            error: &NSError,
229        );
230    }
231);