objc2_io_kit/
consumes_argument.rs

1#![allow(non_snake_case, clippy::missing_safety_doc)]
2use core::{ffi::c_void, ptr};
3use objc2_core_foundation::{CFDictionary, CFRetained};
4
5use crate::{
6    io_iterator_t, io_name_t, io_service_t, IONotificationPortRef, IOServiceMatchingCallback,
7};
8
9fn consume(matching: Option<CFRetained<CFDictionary>>) -> *mut CFDictionary {
10    if let Some(matching) = matching {
11        CFRetained::into_raw(matching).as_ptr()
12    } else {
13        ptr::null_mut()
14    }
15}
16
17/// Look up a registered IOService object that matches a matching dictionary.
18///
19/// This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up.
20///
21/// Parameter `mainPort`: The main port obtained from IOMainPort(). Pass kIOMainPortDefault to look up the default main port.
22///
23/// Parameter `matching`: A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.
24///
25/// Returns: The first service matched is returned on success. The service must be released by the caller.
26pub unsafe extern "C-unwind" fn IOServiceGetMatchingService(
27    main_port: libc::mach_port_t,
28    matching: Option<CFRetained<CFDictionary>>,
29) -> io_service_t {
30    extern "C-unwind" {
31        fn IOServiceGetMatchingService(
32            main_port: libc::mach_port_t,
33            matching: *mut CFDictionary,
34        ) -> io_service_t;
35    }
36
37    unsafe { IOServiceGetMatchingService(main_port, consume(matching)) }
38}
39
40/// Look up registered IOService objects that match a matching dictionary.
41///
42/// This is the preferred method of finding IOService objects currently registered by IOKit (that is, objects that have had their registerService() methods invoked). To find IOService objects that aren't yet registered, use an iterator as created by IORegistryEntryCreateIterator(). IOServiceAddMatchingNotification can also supply this information and install a notification of new IOServices. The matching information used in the matching dictionary may vary depending on the class of service being looked up.
43///
44/// Parameter `mainPort`: The main port obtained from IOMainPort(). Pass kIOMainPortDefault to look up the default main port.
45///
46/// Parameter `matching`: A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.
47///
48/// Parameter `existing`: An iterator handle, or NULL, is returned on success, and should be released by the caller when the iteration is finished. If NULL is returned, the iteration was successful but found no matching services.
49///
50/// Returns: A kern_return_t error code.
51pub unsafe extern "C-unwind" fn IOServiceGetMatchingServices(
52    main_port: libc::mach_port_t,
53    matching: Option<CFRetained<CFDictionary>>,
54    existing: *mut io_iterator_t,
55) -> libc::kern_return_t {
56    extern "C-unwind" {
57        fn IOServiceGetMatchingServices(
58            main_port: libc::mach_port_t,
59            matching: *mut CFDictionary,
60            existing: *mut io_iterator_t,
61        ) -> libc::kern_return_t;
62    }
63
64    unsafe { IOServiceGetMatchingServices(main_port, consume(matching), existing) }
65}
66
67/// Look up registered IOService objects that match a matching dictionary, and install a notification request of new IOServices that match.
68///
69/// This is the preferred method of finding IOService objects that may arrive at any time. The type of notification specifies the state change the caller is interested in, on IOService's that match the match dictionary. Notification types are identified by name, and are defined in IOKitKeys.h. The matching information used in the matching dictionary may vary depending on the class of service being looked up.
70///
71/// Parameter `notifyPort`: A IONotificationPortRef object that controls how messages will be sent when the armed notification is fired. When the notification is delivered, the io_iterator_t representing the notification should be iterated through to pick up all outstanding objects. When the iteration is finished the notification is rearmed. See IONotificationPortCreate.
72///
73/// Parameter `notificationType`: A notification type from IOKitKeys.h
74/// <br>
75/// kIOPublishNotification Delivered when an IOService is registered.
76/// <br>
77/// kIOFirstPublishNotification Delivered when an IOService is registered, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.
78/// <br>
79/// kIOMatchedNotification Delivered when an IOService has had all matching drivers in the kernel probed and started.
80/// <br>
81/// kIOFirstMatchNotification Delivered when an IOService has had all matching drivers in the kernel probed and started, but only once per IOService instance. Some IOService's may be reregistered when their state is changed.
82/// <br>
83/// kIOTerminatedNotification Delivered after an IOService has been terminated.
84///
85/// Parameter `matching`: A CF dictionary containing matching information, of which one reference is always consumed by this function (Note prior to the Tiger release there was a small chance that the dictionary might not be released if there was an error attempting to serialize the dictionary). IOKitLib can construct matching dictionaries for common criteria with helper functions such as IOServiceMatching, IOServiceNameMatching, IOBSDNameMatching.
86///
87/// Parameter `callback`: A callback function called when the notification fires.
88///
89/// Parameter `refCon`: A reference constant for the callbacks use.
90///
91/// Parameter `notification`: An iterator handle is returned on success, and should be released by the caller when the notification is to be destroyed. The notification is armed when the iterator is emptied by calls to IOIteratorNext - when no more objects are returned, the notification is armed. Note the notification is not armed when first created.
92///
93/// Returns: A kern_return_t error code.
94pub unsafe extern "C-unwind" fn IOServiceAddMatchingNotification(
95    notify_port: IONotificationPortRef,
96    notification_type: io_name_t,
97    matching: Option<CFRetained<CFDictionary>>,
98    callback: IOServiceMatchingCallback,
99    ref_con: *mut c_void,
100    notification: *mut io_iterator_t,
101) -> libc::kern_return_t {
102    extern "C-unwind" {
103        fn IOServiceAddMatchingNotification(
104            notify_port: IONotificationPortRef,
105            notification_type: io_name_t,
106            matching: *mut CFDictionary,
107            callback: IOServiceMatchingCallback,
108            ref_con: *mut c_void,
109            notification: *mut io_iterator_t,
110        ) -> libc::kern_return_t;
111    }
112
113    unsafe {
114        IOServiceAddMatchingNotification(
115            notify_port,
116            notification_type,
117            consume(matching),
118            callback,
119            ref_con,
120            notification,
121        )
122    }
123}
objc2_io_kit/consumes_argument.rs

objc2_io_kit/
consumes_argument.rs
