objc2_io_usb_host/generated/IOUSBHostControllerInterface.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#[cfg(feature = "objc2-io-kit")]
10use objc2_io_kit::*;
11
12use crate::*;
13
14/// Client-supplied block to handle IOUSBHostCIMessage structures representing controller, port, device, or endpoint commands
15///
16/// The kernel driver controls the state of the client's USB services via commands that target the controller, port, device, or endpoint. The command response
17/// must be received by the kernel driver before a new command will be sent.
18///
19/// Commands with a type targeting the controller (IOUSBHostCIMessageTypeController*) should be processed by the IOUSBHostCIControllerStateMachine
20/// available via the IOUSBHostControllerInterface's controllerStateMachine property.
21///
22/// Commands with a type targeting the root ports (IOUSBHostCIMessageTypePort*) should be processed by the IOUSBHostCIPortStateMachines
23/// available via the getPortStateMachineForCommand interface.
24///
25/// Commands with a type targeting a device (IOUSBHostCIMessageTypeDevice*) should be processed by a client-created IOUSBHostCIDeviceStateMachine.
26///
27/// Commands with a type targeting an endpoint (IOUSBHostCIMessageTypeEndpoint*) should be processed by a client-created IOUSBHostCIEndpointStateMachine.
28///
29/// See also [Apple's documentation](https://developer.apple.com/documentation/iousbhost/iousbhostcontrollerinterfacecommandhandler?language=objc)
30#[cfg(all(
31 feature = "IOUSBHostControllerInterfaceDefinitions",
32 feature = "block2"
33))]
34pub type IOUSBHostControllerInterfaceCommandHandler =
35 *mut block2::DynBlock<dyn Fn(NonNull<IOUSBHostControllerInterface>, IOUSBHostCIMessage)>;
36
37/// Client-supplied block to handle IOUSBHostCIDoorbell messages
38///
39/// The kernel driver sends IOUSBHostCIDoorbell messages to notify the client that transfer structures for specific endpoints have been updated. Doorbell messages
40/// should be processed by a client-created IOUSBHostCIEndpointStateMachine.
41///
42/// See also [Apple's documentation](https://developer.apple.com/documentation/iousbhost/iousbhostcontrollerinterfacedoorbellhandler?language=objc)
43#[cfg(all(
44 feature = "IOUSBHostControllerInterfaceDefinitions",
45 feature = "block2"
46))]
47pub type IOUSBHostControllerInterfaceDoorbellHandler = *mut block2::DynBlock<
48 dyn Fn(NonNull<IOUSBHostControllerInterface>, NonNull<IOUSBHostCIDoorbell>, u32),
49>;
50
51extern_class!(
52 /// [Apple's documentation](https://developer.apple.com/documentation/iousbhost/iousbhostcontrollerinterface?language=objc)
53 #[unsafe(super(NSObject))]
54 #[derive(Debug, PartialEq, Eq, Hash)]
55 pub struct IOUSBHostControllerInterface;
56);
57
58extern_conformance!(
59 unsafe impl NSObjectProtocol for IOUSBHostControllerInterface {}
60);
61
62impl IOUSBHostControllerInterface {
63 extern_methods!(
64 #[unsafe(method(init))]
65 #[unsafe(method_family = init)]
66 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
67
68 #[cfg(all(
69 feature = "IOUSBHostControllerInterfaceDefinitions",
70 feature = "block2",
71 feature = "dispatch2",
72 feature = "objc2-io-kit"
73 ))]
74 /// Initializes IOUSBHostControllerInterface object along with a user client
75 ///
76 /// If the user client cannot be created, nil will be returned.
77 /// When done using the object, destroy must be called on the object.
78 ///
79 /// Parameter `capabilities`: NSData containing an array of IOUSBHostCIMessage structures. The first must have an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypeControllerCapabilities,
80 /// followed by at least one message with an IOUSBHostCIMessageControlType of IOUSBHostCIMessageTypePortCapabilities.
81 ///
82 /// Parameter `queue`: A serial queue to service asynchronous operations. If nil, a serial queue will be created on behalf of the client.
83 ///
84 /// Parameter `interruptRateHz`: NSUInteger representing the rate in Hz at which interrupts will be delivered to the kernel driver.
85 /// A value ot 0 will send all interrupts to the kernel immediately.
86 ///
87 /// Parameter `commandHandler`: IOUSBHostControllerInterfaceCommandHandler used to process IOUSBHostCIMessage messages sent by the kernel driver.
88 ///
89 /// Parameter `doorbellHandler`: IOUSBHostControllerInterfaceDoorbellHandler used to process IOUSBHostCIDoorbell values sent by the kernel driver.
90 ///
91 /// Parameter `interestHandler`: IOServiceInterestCallback used to process service state changes such as termination. See IOServiceAddInterestNotification
92 /// in IOKitLib for more details. All notifications will be serviced on an internal serial queue separate from command and doorbell handlers.
93 ///
94 /// Returns: An IOUSBHostControllerInterface. The object is to be released by the caller.
95 ///
96 /// # Safety
97 ///
98 /// - `queue` possibly has additional threading requirements.
99 /// - `command_handler` must be a valid pointer.
100 /// - `doorbell_handler` must be a valid pointer.
101 /// - `interest_handler` must be implemented correctly.
102 #[unsafe(method(initWithCapabilities:queue:interruptRateHz:error:commandHandler:doorbellHandler:interestHandler:))]
103 #[unsafe(method_family = init)]
104 pub unsafe fn initWithCapabilities_queue_interruptRateHz_error_commandHandler_doorbellHandler_interestHandler(
105 this: Allocated<Self>,
106 capabilities: &NSData,
107 queue: Option<&DispatchQueue>,
108 interrupt_rate_hz: NSUInteger,
109 error: Option<&mut Option<Retained<NSError>>>,
110 command_handler: IOUSBHostControllerInterfaceCommandHandler,
111 doorbell_handler: IOUSBHostControllerInterfaceDoorbellHandler,
112 interest_handler: IOServiceInterestCallback,
113 ) -> Option<Retained<Self>>;
114
115 /// Removes underlying allocations of the IOUSBHostControllerInterface object along with user client
116 ///
117 /// When the IOUSBHostControllerInterface is no longer needed, destroy must be called. This will destroy
118 /// the connection with the user client and de-register interest on the service. If the object
119 /// is freed, destroy will be called automatically. Calling destroy multiple times has no effect.
120 #[unsafe(method(destroy))]
121 #[unsafe(method_family = none)]
122 pub unsafe fn destroy(&self);
123
124 #[cfg(feature = "dispatch2")]
125 /// The dispatch queue for asynchronous operations.
126 #[unsafe(method(queue))]
127 #[unsafe(method_family = none)]
128 pub unsafe fn queue(&self) -> Retained<DispatchQueue>;
129
130 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
131 /// Enqueue an interrupt for delivery to the kernel service
132 ///
133 /// This method enqueues one interrupt message for delivery to the kernel service. interruptRateHz is used to determine when the interrupt message is
134 /// delivered to the kernel service.
135 ///
136 /// Parameter `interrupt`: An IOUSBHostCIMessage structure representing an interrupt message
137 ///
138 /// # Safety
139 ///
140 /// `interrupt` must be a valid pointer.
141 #[unsafe(method(enqueueInterrupt:error:_))]
142 #[unsafe(method_family = none)]
143 pub unsafe fn enqueueInterrupt_error(
144 &self,
145 interrupt: NonNull<IOUSBHostCIMessage>,
146 ) -> Result<(), Retained<NSError>>;
147
148 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
149 /// Enqueue an interrupt for delivery to the kernel service
150 ///
151 /// This method enqueues one interrupt message for delivery to the kernel service.
152 ///
153 /// Parameter `interrupt`: An IOUSBHostCIMessage structure representing an interrupt message
154 ///
155 /// Parameter `expedite`: Bool NO to use interruptRateHz to determine when the interrupt message is delivered to the kernel service. Bool YES if interruptRateHz
156 /// should be ignored, sending the message to the kernel driver at the next opportunity while maintaining in-order delivery of all interrupt messages.
157 ///
158 /// # Safety
159 ///
160 /// `interrupt` must be a valid pointer.
161 #[unsafe(method(enqueueInterrupt:expedite:error:_))]
162 #[unsafe(method_family = none)]
163 pub unsafe fn enqueueInterrupt_expedite_error(
164 &self,
165 interrupt: NonNull<IOUSBHostCIMessage>,
166 expedite: bool,
167 ) -> Result<(), Retained<NSError>>;
168
169 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
170 /// Enqueue interrupts for delivery to the kernel service
171 ///
172 /// This method enqueues one or more interrupt messages for delivery to the kernel service. interruptRateHz is used to determine when the interrupt message is
173 /// delivered to the kernel service.
174 ///
175 /// Parameter `interrupts`: An IOUSBHostCIMessage structure representing one or more interrupt messages
176 ///
177 /// Parameter `count`: The number of interrupt messages represented by the interrupts parameter
178 ///
179 /// # Safety
180 ///
181 /// `interrupts` must be a valid pointer.
182 #[unsafe(method(enqueueInterrupts:count:error:_))]
183 #[unsafe(method_family = none)]
184 pub unsafe fn enqueueInterrupts_count_error(
185 &self,
186 interrupts: NonNull<IOUSBHostCIMessage>,
187 count: NSUInteger,
188 ) -> Result<(), Retained<NSError>>;
189
190 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
191 /// Enqueue interrupts for delivery to the kernel service
192 ///
193 /// This method enqueues one or more interrupt messages for delivery to the kernel service. interruptRateHz is used to determine when the interrupt message is
194 /// delivered to the kernel service.
195 ///
196 /// Parameter `interrupts`: An IOUSBHostCIMessage structure representing one or more interrupt messages
197 ///
198 /// Parameter `count`: The number of interrupt messages represented by the interrupts parameter
199 ///
200 /// Parameter `expedite`: Bool NO to use interruptRateHz to determine when the interrupt message is delivered to the kernel service. Bool YES if interruptRateHz
201 /// should be ignored, sending the message to the kernel driver at the next opportunity while maintaining in-order delivery of all interrupt messages.
202 ///
203 /// # Safety
204 ///
205 /// `interrupts` must be a valid pointer.
206 #[unsafe(method(enqueueInterrupts:count:expedite:error:_))]
207 #[unsafe(method_family = none)]
208 pub unsafe fn enqueueInterrupts_count_expedite_error(
209 &self,
210 interrupts: NonNull<IOUSBHostCIMessage>,
211 count: NSUInteger,
212 expedite: bool,
213 ) -> Result<(), Retained<NSError>>;
214
215 /// The interrupt moderation rate for sending interrupt messages to the kernel driver
216 ///
217 /// interruptRateHz will cause submitted interrupt messages to be batched together and submitted to the kernel
218 /// at the specified rate. A value ot 0 will deliver all interrupts to the kernel driver as soon as possible.
219 #[unsafe(method(interruptRateHz))]
220 #[unsafe(method_family = none)]
221 pub unsafe fn interruptRateHz(&self) -> NSUInteger;
222
223 /// Setter for [`interruptRateHz`][Self::interruptRateHz].
224 #[unsafe(method(setInterruptRateHz:))]
225 #[unsafe(method_family = none)]
226 pub unsafe fn setInterruptRateHz(&self, interrupt_rate_hz: NSUInteger);
227
228 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
229 /// # Safety
230 ///
231 /// `message` must be a valid pointer.
232 #[unsafe(method(descriptionForMessage:))]
233 #[unsafe(method_family = none)]
234 pub unsafe fn descriptionForMessage(
235 &self,
236 message: NonNull<IOUSBHostCIMessage>,
237 ) -> Retained<NSString>;
238
239 #[cfg(feature = "IOUSBHostCIControllerStateMachine")]
240 #[unsafe(method(controllerStateMachine))]
241 #[unsafe(method_family = none)]
242 pub unsafe fn controllerStateMachine(&self) -> Retained<IOUSBHostCIControllerStateMachine>;
243
244 #[cfg(all(
245 feature = "IOUSBHostCIPortStateMachine",
246 feature = "IOUSBHostControllerInterfaceDefinitions"
247 ))]
248 /// # Safety
249 ///
250 /// `command` must be a valid pointer.
251 #[unsafe(method(getPortStateMachineForCommand:error:_))]
252 #[unsafe(method_family = none)]
253 pub unsafe fn getPortStateMachineForCommand_error(
254 &self,
255 command: NonNull<IOUSBHostCIMessage>,
256 ) -> Result<Retained<IOUSBHostCIPortStateMachine>, Retained<NSError>>;
257
258 #[cfg(feature = "IOUSBHostCIPortStateMachine")]
259 #[unsafe(method(getPortStateMachineForPort:error:_))]
260 #[unsafe(method_family = none)]
261 pub unsafe fn getPortStateMachineForPort_error(
262 &self,
263 port: NSUInteger,
264 ) -> Result<Retained<IOUSBHostCIPortStateMachine>, Retained<NSError>>;
265
266 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
267 /// The capabilities structure passed in during initialization
268 ///
269 /// The capabilities passed into the initializer can be retrieved for reference.
270 #[unsafe(method(capabilities))]
271 #[unsafe(method_family = none)]
272 pub unsafe fn capabilities(&self) -> NonNull<IOUSBHostCIMessage>;
273
274 #[cfg(feature = "IOUSBHostControllerInterfaceDefinitions")]
275 /// Retrieve a port capabilities structure passed in during initialization
276 #[unsafe(method(capabilitiesForPort:))]
277 #[unsafe(method_family = none)]
278 pub unsafe fn capabilitiesForPort(&self, port: NSUInteger) -> NonNull<IOUSBHostCIMessage>;
279
280 /// A UUID used to identify the host controller interface in this process and the kernel
281 #[unsafe(method(uuid))]
282 #[unsafe(method_family = none)]
283 pub unsafe fn uuid(&self) -> Retained<NSUUID>;
284 );
285}
286
287/// Methods declared on superclass `NSObject`.
288impl IOUSBHostControllerInterface {
289 extern_methods!(
290 #[unsafe(method(new))]
291 #[unsafe(method_family = new)]
292 pub unsafe fn new() -> Retained<Self>;
293 );
294}