objc2_io_bluetooth/generated/objc2/

IOBluetoothDeviceInquiry.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-foundation")]
use objc2_foundation::*;

use crate::*;

extern_class!(
    /// Object representing a device inquiry that finds Bluetooth devices in-range of the computer,
    /// and (optionally) retrieves name information for them.
    ///
    /// You should only use this object if your application needs to know about in-range devices and cannot
    /// use the GUI provided by the IOBluetoothUI framework. It will not let you perform unlimited back-to-back
    /// inquiries, but will instead throttle the number of attempted inquiries if too many are attempted within
    /// a small window of time.
    /// Important Note: DO NOT perform remote name requests on devices from delegate methods or while this
    /// object is in use. If you wish to do your own remote name requests on devices, do them after you have
    /// stopped this object. If you do not heed this warning, you could potentially deadlock your process.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/iobluetooth/iobluetoothdeviceinquiry?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct IOBluetoothDeviceInquiry;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for IOBluetoothDeviceInquiry {}
);

impl IOBluetoothDeviceInquiry {
    extern_methods!(
        /// # Safety
        ///
        /// This is not retained internally, you must ensure the object is still alive.
        #[unsafe(method(delegate))]
        #[unsafe(method_family = none)]
        pub unsafe fn delegate(&self) -> Option<Retained<AnyObject>>;

        /// Setter for [`delegate`][Self::delegate].
        ///
        /// # Safety
        ///
        /// - `delegate` should be of the correct type.
        /// - This is unretained, you must ensure the object is kept alive while in use.
        #[unsafe(method(setDelegate:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDelegate(&self, delegate: Option<&AnyObject>);

        /// Class method to create an inquiry object.
        ///
        /// Parameter `delegate`: A delegate object that wishes to receive messages from the inquiry object. Delegate methods are listed below, under IOBluetoothDeviceInquiryDelegate.
        ///
        /// Returns: A pointer to the created IOBluetoothDeviceInquiry object.
        ///
        /// The inquiry is NOT automatically started. You musts call -start on it to start the search for in-range devices.
        ///
        /// # Safety
        ///
        /// - `delegate` should be of the correct type.
        /// - `delegate` might not allow `None`.
        #[unsafe(method(inquiryWithDelegate:))]
        #[unsafe(method_family = none)]
        pub unsafe fn inquiryWithDelegate(delegate: Option<&AnyObject>) -> Option<Retained<Self>>;

        /// Initializes an alloc'd inquiry object, and sets the delegate object, as if -setDelegate: were called on it.
        ///
        /// Parameter `delegate`: A delegate object that wishes to receive messages from the inquiry object. Delegate methods are listed below, under IOBluetoothDeviceInquiryDelegate.
        ///
        /// Returns: A pointer to the initialized IOBluetoothDeviceInquiry object.
        ///
        /// # Safety
        ///
        /// - `delegate` should be of the correct type.
        /// - `delegate` might not allow `None`.
        #[unsafe(method(initWithDelegate:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithDelegate(
            this: Allocated<Self>,
            delegate: Option<&AnyObject>,
        ) -> Option<Retained<Self>>;

        /// Tells inquiry object to begin the inquiry and name updating process, if specified.
        ///
        /// Returns: Returns kIOReturnSuccess if start was successful. Returns kIOReturnBusy if the object is already in process. May return other IOReturn values, as appropriate.
        ///
        /// Calling start multiple times in rapid succession or back-to-back will probably not produce the intended
        /// results. Inquiries are throttled if they are called too quickly in succession.
        #[unsafe(method(start))]
        #[unsafe(method_family = none)]
        pub unsafe fn start(&self) -> IOReturn;

        /// Halts the inquiry object. Could either stop the search for new devices, or the updating of found device names.
        ///
        /// Returns: Returns kIOReturnSuccess if the inquiry is successfully stopped. Returns kIOReturnNotPermitted if the inquiry object is already stopped. May return other IOReturn values, as appropriate.
        #[unsafe(method(stop))]
        #[unsafe(method_family = none)]
        pub unsafe fn stop(&self) -> IOReturn;

        /// Set the length of the inquiry that is performed each time -start is used on an inquiry object.
        ///
        /// Parameter `seconds`: Number of seconds the inquiry will search for in-range devices before refreshing device names, if specified.
        ///
        /// Returns: Number of seconds the search will be performed.
        ///
        /// A default of 10 seconds is used, unless a different value is specified using this method.  Note that if you
        /// have called -start again too quickly, your inquiry may actually take much longer than what length you
        /// specify, as inquiries are throttled in the system. Also note that if you have the inquiry object updating
        /// device names for you, the whole inquiry process could be much longer than the specified length, depending
        /// on the number of devices found and how responsive to name requests they are. If you -must- have a strict
        /// inquiry length, disable name updates. In other words, this "length" only refers to the actual device discovery
        /// portion of the whole inquiry process.
        #[unsafe(method(inquiryLength))]
        #[unsafe(method_family = none)]
        pub unsafe fn inquiryLength(&self) -> u8;

        /// Setter for [`inquiryLength`][Self::inquiryLength].
        #[unsafe(method(setInquiryLength:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setInquiryLength(&self, inquiry_length: u8);

        #[cfg(feature = "IOBluetoothUserLib")]
        /// Set the devices that are found.
        ///
        /// Parameter `searchType`: Bluetooth versions the search will discover.
        ///
        /// A default of kIOBluetoothDeviceSearchClassic is used, unless a different value is specified using this method.
        #[unsafe(method(searchType))]
        #[unsafe(method_family = none)]
        pub unsafe fn searchType(&self) -> IOBluetoothDeviceSearchTypes;

        #[cfg(feature = "IOBluetoothUserLib")]
        /// Setter for [`searchType`][Self::searchType].
        #[unsafe(method(setSearchType:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSearchType(&self, search_type: IOBluetoothDeviceSearchTypes);

        /// Sets whether or not the inquiry object will retrieve the names of devices found during the search.
        ///
        /// Parameter `inValue`: Pass TRUE if names are to be updated, otherwise pass FALSE.
        ///
        /// The default value for the inquiry object is TRUE, unless this method is used to change it.
        #[unsafe(method(updateNewDeviceNames))]
        #[unsafe(method_family = none)]
        pub unsafe fn updateNewDeviceNames(&self) -> bool;

        /// Setter for [`updateNewDeviceNames`][Self::updateNewDeviceNames].
        #[unsafe(method(setUpdateNewDeviceNames:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setUpdateNewDeviceNames(&self, update_new_device_names: bool);

        #[cfg(feature = "objc2-foundation")]
        /// Returns found IOBluetoothDevice objects as an array.
        ///
        /// Returns: Returns an NSArray of IOBluetoothDevice objects.
        ///
        /// Will not return nil. If there are no devices found, returns an array with length of 0.
        #[unsafe(method(foundDevices))]
        #[unsafe(method_family = none)]
        pub unsafe fn foundDevices(&self) -> Option<Retained<NSArray>>;

        /// Removes all found devices from the inquiry object.
        #[unsafe(method(clearFoundDevices))]
        #[unsafe(method_family = none)]
        pub unsafe fn clearFoundDevices(&self);

        #[cfg(feature = "Bluetooth")]
        /// Use this method to set the criteria for the device search.
        ///
        /// Parameter `inServiceClassMajor`: Set the major service class for found devices. Set to kBluetoothServiceClassMajorAny for all devices. See BluetoothAssignedNumbers.h for possible values.
        ///
        /// Parameter `inMajorDeviceClass`: Set the major device class for found devices. Set to kBluetoothDeviceClassMajorAny for all devices. See BluetoothAssignedNumbers.h for possible values.
        ///
        /// Parameter `inMinorDeviceClass`: Set the minor device class for found devices. Set to kBluetoothDeviceClassMinorAny for all devices. See BluetoothAssignedNumbers.h for possible values.
        ///
        /// The default inquiry object will search for all types of devices. If you wish to find only keyboards, for example, you might use this method like this:
        ///
        /// [myInquiryObject        setSearchCriteria:kBluetoothServiceClassMajorAny
        /// majorDeviceClass:kBluetoothDeviceClassMajorPeripheral
        /// minorDeviceClass:kBluetoothDeviceClassMinorPeripheral1Keyboard];
        ///
        /// However, we recommend only using this if you are certain of the device class you are looking for, as some
        /// devices may report a different/unexpected device class, and the search may miss the device you are interested in.
        #[unsafe(method(setSearchCriteria:majorDeviceClass:minorDeviceClass:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSearchCriteria_majorDeviceClass_minorDeviceClass(
            &self,
            in_service_class_major: BluetoothServiceClassMajor,
            in_major_device_class: BluetoothDeviceClassMajor,
            in_minor_device_class: BluetoothDeviceClassMinor,
        );
    );
}

/// Methods declared on superclass `NSObject`.
impl IOBluetoothDeviceInquiry {
    extern_methods!(
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_protocol!(
    /// This category on NSObject describes the delegate methods for the IOBluetoothDeviceInquiry object. All
    /// methods are optional, but it is highly recommended you implement them all. Do NOT invoke remote name
    /// requests on found IOBluetoothDevice objects unless the inquiry object has been stopped. Doing so may
    /// deadlock your process.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/iobluetooth/iobluetoothdeviceinquirydelegate?language=objc)
    pub unsafe trait IOBluetoothDeviceInquiryDelegate: NSObjectProtocol {
        /// This message will be delivered when the inquiry actually starts. Since the inquiry could be throttled, this
        /// message may not be received immediately after called -start.
        ///
        /// Parameter `sender`: Inquiry object that sent this delegate message.
        ///
        /// # Safety
        ///
        /// `sender` might not allow `None`.
        #[optional]
        #[unsafe(method(deviceInquiryStarted:))]
        #[unsafe(method_family = none)]
        unsafe fn deviceInquiryStarted(&self, sender: Option<&IOBluetoothDeviceInquiry>);

        #[cfg(all(feature = "IOBluetoothDevice", feature = "IOBluetoothObject"))]
        /// A new device has been found. You do not need to retain the device - it will be held in the internal
        /// storage of the inquiry, and can be accessed later using -foundDevices.
        ///
        /// Parameter `sender`: Inquiry object that sent this delegate message.
        ///
        /// Parameter `device`: IOBluetoothDevice that was found.
        ///
        /// # Safety
        ///
        /// - `sender` might not allow `None`.
        /// - `device` might not allow `None`.
        #[optional]
        #[unsafe(method(deviceInquiryDeviceFound:device:))]
        #[unsafe(method_family = none)]
        unsafe fn deviceInquiryDeviceFound_device(
            &self,
            sender: Option<&IOBluetoothDeviceInquiry>,
            device: Option<&IOBluetoothDevice>,
        );

        /// The inquiry has begun updating device names that were found during the search.
        ///
        /// Parameter `sender`: Inquiry object that sent this delegate message.
        ///
        /// Parameter `devicesRemaining`: Number of devices remaining to update.
        ///
        /// # Safety
        ///
        /// `sender` might not allow `None`.
        #[optional]
        #[unsafe(method(deviceInquiryUpdatingDeviceNamesStarted:devicesRemaining:))]
        #[unsafe(method_family = none)]
        unsafe fn deviceInquiryUpdatingDeviceNamesStarted_devicesRemaining(
            &self,
            sender: Option<&IOBluetoothDeviceInquiry>,
            devices_remaining: u32,
        );

        #[cfg(all(feature = "IOBluetoothDevice", feature = "IOBluetoothObject"))]
        /// A device name has been retrieved. Also indicates how many devices are left to be updated.
        ///
        /// Parameter `sender`: Inquiry object that sent this delegate message.
        ///
        /// Parameter `device`: IOBluetoothDevice that was updated.
        ///
        /// Parameter `devicesRemaining`: Number of devices remaining to update.
        ///
        /// # Safety
        ///
        /// - `sender` might not allow `None`.
        /// - `device` might not allow `None`.
        #[optional]
        #[unsafe(method(deviceInquiryDeviceNameUpdated:device:devicesRemaining:))]
        #[unsafe(method_family = none)]
        unsafe fn deviceInquiryDeviceNameUpdated_device_devicesRemaining(
            &self,
            sender: Option<&IOBluetoothDeviceInquiry>,
            device: Option<&IOBluetoothDevice>,
            devices_remaining: u32,
        );

        /// When the inquiry is completely stopped, this delegate method will be invoked. It will supply an error
        /// code value, kIOReturnSuccess if the inquiry stopped without problem, otherwise a non-kIOReturnSuccess
        /// error code will be supplied.
        ///
        /// Parameter `sender`: Inquiry object that sent this delegate message.
        ///
        /// Parameter `error`: Error code. kIOReturnSuccess if the inquiry completed without incident.
        ///
        /// Parameter `aborted`: TRUE if user called -stop on the inquiry.
        ///
        /// # Safety
        ///
        /// `sender` might not allow `None`.
        #[optional]
        #[unsafe(method(deviceInquiryComplete:error:aborted:))]
        #[unsafe(method_family = none)]
        unsafe fn deviceInquiryComplete_error_aborted(
            &self,
            sender: Option<&IOBluetoothDeviceInquiry>,
            error: IOReturn,
            aborted: bool,
        );
    }
);