objc2_core_midi/generated/

MIDIDriver.rs

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

use crate::*;

/// Points to a pointer to a MIDIDriverInterface, a CFPlugIn structure (defined in
/// MIDIDriver.h) containing function pointers for the driver's methods.  Only the
/// MIDIServer may call a driver's methods.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coremidi/mididriverref?language=objc)
pub type MIDIDriverRef = *mut NonNull<MIDIDriverInterface>;

/// A MIDIDeviceListRef is a list of MIDIDeviceRef's.  The devices are not owned by
/// the list (i.e., disposing the list does not dispose the devices it references).
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coremidi/mididevicelistref?language=objc)
#[cfg(feature = "MIDIServices")]
pub type MIDIDeviceListRef = MIDIObjectRef;

/// The COM-style interface to a MIDI driver.
///
///
/// This is the function table interface to a MIDI driver.  Version 1 and 2 drivers use
/// this same table of function pointers (except as noted).
///
/// Drivers which support multiple version interfaces can tell which version
/// of the server is running by checking to see whether kMIDIDriverInterface2ID
/// or kMIDIDriverInterfaceID is passed to the factory function. If the version 1 interface is
/// requested, the driver should behave as if it is a version 1 driver.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coremidi/mididriverinterface?language=objc)
#[cfg(all(feature = "MIDIServices", feature = "objc2-core-foundation"))]
#[repr(C)]
#[allow(unpredictable_function_pointer_comparisons)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MIDIDriverInterface {
    pub(crate) _reserved: NonNull<c_void>,
    pub QueryInterface:
        unsafe extern "C-unwind" fn(NonNull<c_void>, REFIID, *mut LPVOID) -> HRESULT,
    pub AddRef: unsafe extern "C-unwind" fn(NonNull<c_void>) -> ULONG,
    pub Release: unsafe extern "C-unwind" fn(NonNull<c_void>) -> ULONG,
    /// This is only called for version 1 drivers.  The server is requesting that the driver
    /// detect the devices which are present.  For each device present, the driver should
    /// create a MIDIDeviceRef with entities, using MIDIDeviceCreate and
    /// MIDIDeviceAddEntity, and add the device to the supplied MIDIDeviceListRef, using
    /// MIDIDeviceListAddDevice.
    ///
    /// The driver should not retain any references to the created devices and entities.
    pub FindDevices: unsafe extern "C-unwind" fn(MIDIDriverRef, MIDIDeviceListRef) -> OSStatus,
    /// The server is telling the driver to begin MIDI I/O.
    ///
    /// The provided device list contains the devices which were previously located by
    /// FindDevices (in the case of a version 1 driver), or the devices which are owned by
    /// this driver and are currently in the current MIDISetup (for version 2 drivers).
    ///
    /// The provided devices may or may not still be present.  A version 1 driver should
    /// attempt to use as many of the devices as are actually present.
    ///
    /// A version 2 driver may make calls such as MIDISetupAddDevice, MIDIDeviceAddEntity,
    /// MIDIDeviceRemoveEntity to dynamically modify the system's current state. For devices
    /// in the provided device list which are not present, the driver should set their
    /// kMIDIPropertyOffline property to 1.  A version 2 driver may also set up
    /// notifications when the IORegistry changes, to detect connection and disconnection of
    /// devices it wishes to control.  At these times also, the driver may change the
    /// devices' kMIDIPropertyOffline, and dynamically modify the system's current state to
    /// reflect the devices which are present.  When passing a CFRunLoopRef to IOKit for
    /// notification purposes, the driver must use the server's main runloop, which is
    /// obtained with CFRunLoopGetCurrent().
    ///
    /// The driver will probably want to iterate through the destination endpoints and
    /// assign their driver refCons, so as to identify multiple destinations when Send() is
    /// called.
    ///
    /// The provided device list remains owned by the system and can be assumed to contain
    /// only devices owned by this driver.  The driver may retain references to the devices
    /// in this list and any it creates while running.
    pub Start: unsafe extern "C-unwind" fn(MIDIDriverRef, MIDIDeviceListRef) -> OSStatus,
    /// The server is telling the driver to terminate MIDI I/O.  All I/O operations that
    /// were begun in Start, or as a result of a subsequent IOKit notification, should be
    /// terminated.
    pub Stop: unsafe extern "C-unwind" fn(MIDIDriverRef) -> OSStatus,
    /// not currently used
    pub Configure: unsafe extern "C-unwind" fn(MIDIDriverRef, MIDIDeviceRef) -> OSStatus,
    /// Send a MIDIPacketList to the destination endpoint whose refCons are being passed as
    /// arguments.
    pub Send: unsafe extern "C-unwind" fn(
        MIDIDriverRef,
        NonNull<MIDIPacketList>,
        NonNull<c_void>,
        NonNull<c_void>,
    ) -> OSStatus,
    /// A client has opened or closed a connection, and now the server is telling the driver
    /// that input from a particular source either does or does not have any listeners in
    /// the system.  The driver may use this information to decide whether to pass messages
    /// from the source to the server, and it may even be able to tell the source hardware
    /// not to generate incoming MIDI I/O for that source.
    pub EnableSource:
        unsafe extern "C-unwind" fn(MIDIDriverRef, MIDIEndpointRef, Boolean) -> OSStatus,
    /// Only for version 2 drivers (new for CoreMIDI 1.1).
    ///
    /// Drivers which support schedule-ahead, when receiving this message, should unschedule
    /// all pending output to the specified destination.  If the destination is null/0, the
    /// driver should unschedule all pending output to all destinations.
    pub Flush: unsafe extern "C-unwind" fn(
        MIDIDriverRef,
        MIDIEndpointRef,
        *mut c_void,
        *mut c_void,
    ) -> OSStatus,
    /// Only for version 2 drivers (new for CoreMIDI 1.1).
    ///
    /// Some specialized drivers (e.g. a MIDI monitor display) may wish to intercept and
    /// look at all outgoing MIDI messages.  After a driver calls
    /// MIDIDriverEnableMonitoring(true) on itself, this function is called with the
    /// outgoing MIDI packets for all destinations in the system.  The Monitor function
    /// cannot rely on the MIDI events arriving in order, due to MIDIServer's schedule-ahead
    /// facilities.
    pub Monitor: unsafe extern "C-unwind" fn(
        MIDIDriverRef,
        MIDIEndpointRef,
        NonNull<MIDIPacketList>,
    ) -> OSStatus,
    /// Only for version 3 drivers (new for macOS 12.0).
    ///
    /// Send a MIDIEventList to the destination endpoint whose refCons are being passed as
    /// arguments.
    pub SendPackets: unsafe extern "C-unwind" fn(
        MIDIDriverRef,
        NonNull<MIDIEventList>,
        NonNull<c_void>,
        NonNull<c_void>,
    ) -> OSStatus,
    /// Only for version 3 drivers (new for macOS 12.0).
    ///
    /// Same as Monitor but uses MIDEventList, whose protocol may vary from MIDI 1.0.
    pub MonitorEvents: unsafe extern "C-unwind" fn(
        MIDIDriverRef,
        MIDIEndpointRef,
        NonNull<MIDIEventList>,
    ) -> OSStatus,
}

#[cfg(all(
    feature = "MIDIServices",
    feature = "objc2",
    feature = "objc2-core-foundation"
))]
unsafe impl Encode for MIDIDriverInterface {
    const ENCODING: Encoding = Encoding::Struct("MIDIDriverInterface", &[
        <NonNull<c_void>>::ENCODING,
        <unsafe extern "C-unwind" fn(NonNull<c_void>,REFIID,*mut LPVOID,) -> HRESULT>::ENCODING,
        <unsafe extern "C-unwind" fn(NonNull<c_void>,) -> ULONG>::ENCODING,
        <unsafe extern "C-unwind" fn(NonNull<c_void>,) -> ULONG>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIDeviceListRef,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIDeviceListRef,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIDeviceRef,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,NonNull<MIDIPacketList>,NonNull<c_void>,NonNull<c_void>,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIEndpointRef,Boolean,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIEndpointRef,*mut c_void,*mut c_void,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIEndpointRef,NonNull<MIDIPacketList>,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,NonNull<MIDIEventList>,NonNull<c_void>,NonNull<c_void>,) -> OSStatus>::ENCODING,
        <unsafe extern "C-unwind" fn(MIDIDriverRef,MIDIEndpointRef,NonNull<MIDIEventList>,) -> OSStatus>::ENCODING,
    ]);
}

#[cfg(all(
    feature = "MIDIServices",
    feature = "objc2",
    feature = "objc2-core-foundation"
))]
unsafe impl RefEncode for MIDIDriverInterface {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

extern "C" {
    /// This constant, "MIDIDriverUsesSerial", when defined to "YES" in a driver's
    /// bundle, tells MIDIServer that the driver uses serial ports and is eligible to
    /// have serial ports assigned to it.
    ///
    /// When a serial driver's Start() method is called, it should use
    /// MIDIGetSerialPortOwner to discover which serial ports it has
    /// been assigned to use, and only use those ports.
    ///
    /// New for CoreMIDI 1.1.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coremidi/kmididriverpropertyusesserial?language=objc)
    #[cfg(feature = "objc2-core-foundation")]
    pub static kMIDIDriverPropertyUsesSerial: &'static CFString;
}

extern "C-unwind" {
    /// Drivers call this function to create new MIDIDevice objects
    /// corresponding to the hardware that is present.
    ///
    /// Non-drivers may call this function as of CoreMIDI 1.1, to
    /// create external devices.
    ///
    ///
    /// Parameter `owner`: The driver creating the device.  NULL if a non-driver.
    ///
    /// Parameter `name`: The name of the new device.
    ///
    /// Parameter `manufacturer`: The name of the device's manufacturer.
    ///
    /// Parameter `model`: The device's model name.
    ///
    /// Parameter `outDevice`: On successful return, points to the newly-created device.
    ///
    /// Returns: An OSStatus result code.
    ///
    /// # Safety
    ///
    /// - `owner` must be a valid pointer or null.
    /// - `out_device` must be a valid pointer.
    #[cfg(all(feature = "MIDIServices", feature = "objc2-core-foundation"))]
    pub fn MIDIDeviceCreate(
        owner: MIDIDriverRef,
        name: &CFString,
        manufacturer: &CFString,
        model: &CFString,
        out_device: NonNull<MIDIDeviceRef>,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Drivers may call this function to dispose MIDIDevice objects
    /// which have not yet been added to the system via MIDISetupAddDevice.
    /// Once a device has been added to the system with MIDISetupAddDevice,
    /// the driver must not use this call to destroy it; it must
    /// use MIDISetupRemoveDevice to do so.
    ///
    /// Non-drivers do not have access to this function; they must call
    /// MIDISetupAddDevice and MIDISetupRemoveDevice.
    ///
    ///
    /// Parameter `device`: The device to be disposed.
    ///
    /// Returns: An OSStatus result code.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIDeviceDispose(device: MIDIDeviceRef) -> OSStatus;
}

extern "C-unwind" {
    /// Returns the number of devices in a device list.
    ///
    ///
    /// Parameter `devList`: The device list.
    ///
    /// Returns: The number of devices in the list, or 0 if an error occurred.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIDeviceListGetNumberOfDevices(dev_list: MIDIDeviceListRef) -> ItemCount;
}

extern "C-unwind" {
    /// Return one of the devices in a device list.
    ///
    ///
    /// Parameter `devList`: The device list.
    ///
    /// Parameter `index0`: The index (0...MIDIDeviceListGetNumberOfDevices()-1) of the device
    /// to return.
    ///
    /// Returns: A reference to a device, or NULL if an error occurred.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIDeviceListGetDevice(dev_list: MIDIDeviceListRef, index0: ItemCount)
        -> MIDIDeviceRef;
}

extern "C-unwind" {
    /// Add a device to a device list.
    ///
    ///
    /// Parameter `devList`: The device list.
    ///
    /// Parameter `dev`: The device to add to the list.
    ///
    /// Returns: An OSStatus result code.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIDeviceListAddDevice(dev_list: MIDIDeviceListRef, dev: MIDIDeviceRef) -> OSStatus;
}

extern "C-unwind" {
    /// Dispose a device list, but not the contained devices.
    ///
    ///
    /// Parameter `devList`: The device list to be disposed.
    ///
    /// Returns: An OSStatus result code.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIDeviceListDispose(dev_list: MIDIDeviceListRef) -> OSStatus;
}

extern "C-unwind" {
    /// Drivers need an efficient way to translate from a MIDIEndpoint (source or
    /// destination) to their own internal data structures corresponding to
    /// that endpoint.  This function provides a way for the driver to
    /// assign its own refCons to endpoints.
    ///
    /// These refCons are passed back to the driver in its Send() and Flush()
    /// methods.
    ///
    /// RefCons are not persistent (i.e. they are not saved as part of a
    /// MIDISetup).  They need to be re-initialized in each call to Start().
    ///
    /// A typical use is to use one refCon to refer to a device, and a second
    /// to refer to a port on the device.
    ///
    ///
    /// Parameter `endpt`: The endpoint whose refCons are to be set
    ///
    /// Parameter `ref1`: The first refCon.
    ///
    /// Parameter `ref2`: The second refCon.
    ///
    /// Returns: An OSStatus result code.
    ///
    /// # Safety
    ///
    /// - `ref1` must be a valid pointer or null.
    /// - `ref2` must be a valid pointer or null.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIEndpointSetRefCons(
        endpt: MIDIEndpointRef,
        ref1: *mut c_void,
        ref2: *mut c_void,
    ) -> OSStatus;
}

extern "C-unwind" {
    /// Obtain the refCons assigned to the endpoints
    ///
    ///
    /// Parameter `endpt`: The endpoint whose refCons are to be return
    ///
    /// Parameter `ref1`: On exit, the first refCon.
    ///
    /// Parameter `ref2`: On exit, the second refCon.
    ///
    /// Returns: An OSStatus result code.
    ///
    /// # Safety
    ///
    /// - `ref1` must be a valid pointer or null.
    /// - `ref2` must be a valid pointer or null.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIEndpointGetRefCons(
        endpt: MIDIEndpointRef,
        ref1: *mut NonNull<c_void>,
        ref2: *mut NonNull<c_void>,
    ) -> OSStatus;
}

/// Drivers typically need to receive asynchronous I/O completion callbacks
/// on a high-priority thread.  To save drivers from the trouble of
/// creating their own threads for this purpose, and to make efficient
/// use of system resources, the MIDIServer provides a thread which
/// drivers may use.
///
/// Drivers should do as little work as possible in this thread; typically,
/// just dequeueing and encoding output packets, and decoding input packets
/// into MIDIPacketLists to be passed to MIDIReceived.
///
/// This is a realtime-priority thread and shouldn't be used for anything other
/// than I/O.  For lower-priority tasks, drivers can use the runloop which
/// was current when they were constructed.
///
///
/// Returns: The CFRunLoopRef of the server's driver I/O thread.
#[cfg(feature = "objc2-core-foundation")]
#[inline]
pub unsafe extern "C-unwind" fn MIDIGetDriverIORunLoop() -> CFRetained<CFRunLoop> {
    extern "C-unwind" {
        fn MIDIGetDriverIORunLoop() -> Option<NonNull<CFRunLoop>>;
    }
    let ret = unsafe { MIDIGetDriverIORunLoop() };
    let ret = ret.expect("function was marked as returning non-null, but actually returned NULL");
    unsafe { CFRetained::retain(ret) }
}

extern "C-unwind" {
    /// Returns the list of devices which are in the current MIDISetup
    /// and which were created/owned by the specified driver.
    ///
    /// The returned device list should be disposed (using MIDIDeviceListDispose)
    /// by the caller.
    ///
    ///
    /// Parameter `driver`: The driver whose devices are to be returned.
    ///
    ///
    /// Returns: The requested device list.
    ///
    /// # Safety
    ///
    /// `driver` must be a valid pointer.
    #[cfg(feature = "MIDIServices")]
    pub fn MIDIGetDriverDeviceList(driver: MIDIDriverRef) -> MIDIDeviceListRef;
}

/// A driver may make this call to have MIDIServer pass it every outgoing MIDI
/// packet, to all destinations in the system (not just those controlled by
/// itself).
///
///
/// Parameter `driver`: The driver whose Monitor function is to be enabled.
///
/// Parameter `enabled`: true to enable monitoring, false to disable it.
///
///
/// Returns: An OSStatus result code.
///
/// # Safety
///
/// `driver` must be a valid pointer.
#[inline]
pub unsafe extern "C-unwind" fn MIDIDriverEnableMonitoring(
    driver: MIDIDriverRef,
    enabled: bool,
) -> OSStatus {
    extern "C-unwind" {
        fn MIDIDriverEnableMonitoring(driver: MIDIDriverRef, enabled: Boolean) -> OSStatus;
    }
    unsafe { MIDIDriverEnableMonitoring(driver, enabled as _) }
}