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);