IOKit (JNA API)
Description: declaration: package: com.sun.jna.platform.mac, interface: IOKit

Package com.sun.jna.platform.mac

# Interface IOKit

All Superinterfaces:
  `Library`

public interface IOKit extends Library
The I/O Kit framework implements non-kernel access to I/O Kit objects (drivers and nubs) through the device-interface mechanism.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static class`
  `IOKit.IOConnect`
  For an application to communicate with a device, the first thing it must do is create a connection between itself and the in-kernel object representing the device.
  `static class`
  `IOKit.IOIterator`
  An IOKit iterator handle.
  `static class`
  `IOKit.IOObject`
  IOKitLib implements non-kernel task access to common IOKit object types - IORegistryEntry, IOService, IOIterator etc.
  `static class`
  `IOKit.IORegistryEntry`
  The base class for all objects in the registry.
  `static class`
  `IOKit.IOService`
  The base class for most I/O Kit families, devices, and drivers.

  ## Nested classes/interfaces inherited from interface com.sun.jna.Library

  `Library.Handler`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final IOKit`
  `INSTANCE`
  `static final double`
  `kIOPSTimeRemainingUnknown`
  `static final double`
  `kIOPSTimeRemainingUnlimited`
  `static final int`
  `kIORegistryIterateParents`
  `static final int`
  `kIORegistryIterateRecursively`
  `static final int`
  `kIOReturnNoDevice`
  Return value when attempting parent or child in registry and they do not exist

  ### Fields inherited from interface com.sun.jna.Library

  `OPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_SYMBOL_PROVIDER, OPTION_TYPE_MAPPER`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CoreFoundation.CFMutableDictionaryRef`
  `IOBSDNameMatching(int masterPort, int options, String bsdName)`
  Create a matching dictionary that specifies an `IOService` match based on BSD device name.
  `IOKit.IORegistryEntry`
  `IOIteratorNext(IOKit.IOIterator iterator)`
  Returns the next object in an iteration.
  `int`
  `IOMasterPort(int bootstrapPort, IntByReference port)`
  Returns the mach port used to initiate communication with IOKit.
  `boolean`
  `IOObjectConformsTo(IOKit.IOObject object, String className)`
  Performs an OSDynamicCast operation on an IOKit object.
  `int`
  `IOObjectRelease(IOKit.IOObject object)`
  Releases an object handle previously returned by `IOKitLib`.
  `CoreFoundation.CFTypeRef`
  `IOPSCopyPowerSourcesInfo()`
  Returns a blob of Power Source information in an opaque CFTypeRef.
  `CoreFoundation.CFArrayRef`
  `IOPSCopyPowerSourcesList(CoreFoundation.CFTypeRef blob)`
  Returns a CFArray of Power Source handles, each of type CFTypeRef.
  `CoreFoundation.CFDictionaryRef`
  `IOPSGetPowerSourceDescription(CoreFoundation.CFTypeRef blob, CoreFoundation.CFTypeRef ps)`
  Returns a CFDictionary with readable information about the specific power source.
  `double`
  `IOPSGetTimeRemainingEstimate()`
  Returns the estimated seconds remaining until all power sources (battery and/or UPS's) are empty.
  `int`
  `IORegistryEntryCreateCFProperties(IOKit.IORegistryEntry entry, PointerByReference properties, CoreFoundation.CFAllocatorRef allocator, int options)`
  Create a CF dictionary representation of a registry entry's property table.
  `CoreFoundation.CFTypeRef`
  `IORegistryEntryCreateCFProperty(IOKit.IORegistryEntry entry, CoreFoundation.CFStringRef key, CoreFoundation.CFAllocatorRef allocator, int options)`
  Create a CF representation of a registry entry's property.
  `int`
  `IORegistryEntryGetChildEntry(IOKit.IORegistryEntry entry, String plane, PointerByReference child)`
  Returns the first child of a registry entry in a plane.
  `int`
  `IORegistryEntryGetChildIterator(IOKit.IORegistryEntry entry, String plane, PointerByReference iter)`
  Returns an iterator over a registry entry’s child entries in a plane.
  `int`
  `IORegistryEntryGetName(IOKit.IORegistryEntry entry, Pointer name)`
  Returns a name assigned to a registry entry.
  `int`
  `IORegistryEntryGetParentEntry(IOKit.IORegistryEntry entry, String plane, PointerByReference parent)`
  Returns the first parent of a registry entry in a plane.
  `int`
  `IORegistryEntryGetRegistryEntryID(IOKit.IORegistryEntry entry, LongByReference id)`
  Returns an ID for the registry entry that is global to all tasks.
  `CoreFoundation.CFTypeRef`
  `IORegistryEntrySearchCFProperty(IOKit.IORegistryEntry entry, String plane, CoreFoundation.CFStringRef key, CoreFoundation.CFAllocatorRef allocator, int options)`
  Create a CF representation of a registry entry's property.
  `IOKit.IORegistryEntry`
  `IORegistryGetRootEntry(int masterPort)`
  Return a handle to the registry root.
  `int`
  `IOServiceClose(IOKit.IOConnect connect)`
  Close a connection to an IOService and destroy the connect handle.
  `int`
  `IOServiceGetBusyState(IOKit.IOService service, IntByReference busyState)`
  Returns the busyState of an IOService.
  `IOKit.IOService`
  `IOServiceGetMatchingService(int masterPort, CoreFoundation.CFDictionaryRef matchingDictionary)`
  Look up a registered IOService object that matches a matching dictionary.
  `int`
  `IOServiceGetMatchingServices(int masterPort, CoreFoundation.CFDictionaryRef matchingDictionary, PointerByReference iterator)`
  Look up registered IOService objects that match a matching dictionary.
  `CoreFoundation.CFMutableDictionaryRef`
  `IOServiceMatching(String name)`
  Create a matching dictionary that specifies an `IOService` class match.
  `CoreFoundation.CFMutableDictionaryRef`
  `IOServiceNameMatching(String name)`
  Create a matching dictionary that specifies an `IOService` name match.
  `int`
  `IOServiceOpen(IOKit.IOService service, int owningTask, int type, PointerByReference connect)`
  A request to create a connection to an IOService.

- ## Field Details

  - ### INSTANCE

    static final IOKit INSTANCE

  - ### kIORegistryIterateRecursively

    static final int kIORegistryIterateRecursively
    See Also:
      - Constant Field Values

  - ### kIORegistryIterateParents

    static final int kIORegistryIterateParents
    See Also:
      - Constant Field Values

  - ### kIOReturnNoDevice

    static final int kIOReturnNoDevice
    Return value when attempting parent or child in registry and they do not exist
    See Also:
      - Constant Field Values

  - ### kIOPSTimeRemainingUnlimited

    static final double kIOPSTimeRemainingUnlimited
    See Also:
      - Constant Field Values

  - ### kIOPSTimeRemainingUnknown

    static final double kIOPSTimeRemainingUnknown
    See Also:
      - Constant Field Values

- ## Method Details

  - ### IOMasterPort

    int IOMasterPort(int bootstrapPort, IntByReference port)
    Returns the mach port used to initiate communication with IOKit.
    Parameters:
      `bootstrapPort` - Pass 0 for the default.
      `port` - A pointer to the master port is returned. Multiple calls to IOMasterPort will not result in leaking ports (each call to IOMasterPort adds another send right to the port) but it is considered good programming practice to deallocate the port when you are finished with it using `SystemB.mach_port_deallocate(int, int)`.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IOServiceMatching

    CoreFoundation.CFMutableDictionaryRef IOServiceMatching(String name)
    Create a matching dictionary that specifies an `IOService` class match.
    Parameters:
      `name` - The class name. Class matching is successful on `IOService`s of this class or any subclass.
    Returns:
      The matching dictionary created, is returned on success, or `null` on failure.

      The dictionary is commonly passed to `IOServiceGetMatchingServices(int, com.sun.jna.platform.mac.CoreFoundation.CFDictionaryRef, com.sun.jna.ptr.PointerByReference)` which will consume a reference, otherwise it should be released with `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)` by the caller.

  - ### IOServiceNameMatching

    CoreFoundation.CFMutableDictionaryRef IOServiceNameMatching(String name)
    Create a matching dictionary that specifies an `IOService` name match.
    Parameters:
      `name` - The `IOService` name.
    Returns:
      The matching dictionary created, is returned on success, or `null` on failure.

      The dictionary is commonly passed to `IOServiceGetMatchingServices(int, com.sun.jna.platform.mac.CoreFoundation.CFDictionaryRef, com.sun.jna.ptr.PointerByReference)` which will consume a reference, otherwise it should be released with `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)` by the caller.

  - ### IOBSDNameMatching

    CoreFoundation.CFMutableDictionaryRef IOBSDNameMatching(int masterPort, int options, String bsdName)
    Create a matching dictionary that specifies an `IOService` match based on BSD device name.
    Parameters:
      `masterPort` - The master port obtained from `IOMasterPort(int, com.sun.jna.ptr.IntByReference)`.
      `options` - No options are currently defined.
      `bsdName` - The BSD name.
    Returns:
      The matching dictionary created, is returned on success, or `null` on failure.

      The dictionary is commonly passed to `IOServiceGetMatchingServices(int, com.sun.jna.platform.mac.CoreFoundation.CFDictionaryRef, com.sun.jna.ptr.PointerByReference)` which will consume a reference, otherwise it should be released with `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)` by the caller.

  - ### IOServiceGetMatchingService

    IOKit.IOService IOServiceGetMatchingService(int masterPort, CoreFoundation.CFDictionaryRef matchingDictionary)
    Look up a registered IOService object that matches a matching dictionary.
    Parameters:
      `masterPort` - The master port obtained from `IOMasterPort(int, com.sun.jna.ptr.IntByReference)`.
      `matchingDictionary` - A CF dictionary containing matching information, of which one reference is always consumed by this function. IOKitLib can construct matching dictionaries for common criteria with helper functions such as `IOServiceMatching(java.lang.String)`, `IOServiceNameMatching(java.lang.String)`, and `IOBSDNameMatching(int, int, java.lang.String)`.
    Returns:
      The first service matched is returned on success.

      The service must be released by the caller.

  - ### IOServiceGetMatchingServices

    int IOServiceGetMatchingServices(int masterPort, CoreFoundation.CFDictionaryRef matchingDictionary, PointerByReference iterator)
    Look up registered IOService objects that match a matching dictionary.
    Parameters:
      `masterPort` - The master port obtained from `IOMasterPort(int, com.sun.jna.ptr.IntByReference)`.
      `matchingDictionary` - A CF dictionary containing matching information, of which one reference is always consumed by this function. IOKitLib can construct matching dictionaries for common criteria with helper functions such as `IOServiceMatching(java.lang.String)`, `IOServiceNameMatching(java.lang.String)`, and `IOBSDNameMatching(int, int, java.lang.String)`.
      `iterator` - An iterator handle is returned on success, and should be released by the caller when the iteration is finished.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IOIteratorNext

    IOKit.IORegistryEntry IOIteratorNext(IOKit.IOIterator iterator)
    Returns the next object in an iteration.
    Parameters:
      `iterator` - An IOKit iterator handle.
    Returns:
      If the iterator handle is valid, the next element in the iteration is returned, otherwise zero is returned. The element should be released by the caller when it is finished.

  - ### IORegistryEntryCreateCFProperty

    CoreFoundation.CFTypeRef IORegistryEntryCreateCFProperty(IOKit.IORegistryEntry entry, CoreFoundation.CFStringRef key, CoreFoundation.CFAllocatorRef allocator, int options)
    Create a CF representation of a registry entry's property.
    Parameters:
      `entry` - The registry entry handle whose property to copy.
      `key` - A `CFString` specifying the property name.
      `allocator` - The CF allocator to use when creating the CF container.
      `options` - No options are currently defined.
    Returns:
      A CF container is created and returned the caller on success.

      The caller should release with `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)`.

  - ### IORegistryEntryCreateCFProperties

    int IORegistryEntryCreateCFProperties(IOKit.IORegistryEntry entry, PointerByReference properties, CoreFoundation.CFAllocatorRef allocator, int options)
    Create a CF dictionary representation of a registry entry's property table.
    Parameters:
      `entry` - The registry entry handle whose property table to copy.
      `properties` - A CFDictionary is created and returned the caller on success. The caller should release with CFRelease.
      `allocator` - The CF allocator to use when creating the CF containers.
      `options` - No options are currently defined.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryEntrySearchCFProperty

    CoreFoundation.CFTypeRef IORegistryEntrySearchCFProperty(IOKit.IORegistryEntry entry, String plane, CoreFoundation.CFStringRef key, CoreFoundation.CFAllocatorRef allocator, int options)
    Create a CF representation of a registry entry's property.
    Parameters:
      `entry` - The registry entry at which to start the search.
      `plane` - The name of an existing registry plane. Plane names are defined in `IOKitKeys.h`, for example, `kIOServicePlane`.
      `key` - A `CFString` specifying the property name.
      `allocator` - The CF allocator to use when creating the CF container.
      `options` - `kIORegistryIterateRecursively` may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard `IORegistryEntryCreateCFProperty(com.sun.jna.platform.mac.IOKit.IORegistryEntry, com.sun.jna.platform.mac.CoreFoundation.CFStringRef, com.sun.jna.platform.mac.CoreFoundation.CFAllocatorRef, int)` call. `kIORegistryIterateParents` may be set to iterate the parents of the entry, in place of the children.
    Returns:
      A CF container is created and returned the caller on success. The caller should release with CFRelease.

  - ### IORegistryEntryGetRegistryEntryID

    int IORegistryEntryGetRegistryEntryID(IOKit.IORegistryEntry entry, LongByReference id)
    Returns an ID for the registry entry that is global to all tasks.
    Parameters:
      `entry` - The registry entry handle whose ID to look up.
      `id` - The resulting ID.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryEntryGetName

    int IORegistryEntryGetName(IOKit.IORegistryEntry entry, Pointer name)
    Returns a name assigned to a registry entry.
    Parameters:
      `entry` - The registry entry handle whose name to look up.
      `name` - The caller's buffer to receive the name. This must be a 128-byte buffer.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryEntryGetChildIterator

    int IORegistryEntryGetChildIterator(IOKit.IORegistryEntry entry, String plane, PointerByReference iter)
    Returns an iterator over a registry entry’s child entries in a plane.
    Parameters:
      `entry` - The registry entry whose children to iterate over.
      `plane` - The name of an existing registry plane. Plane names are defined in `IOKitKeys.h`, for example, `kIOServicePlane`.
      `iter` - The created iterator over the children of the entry, on success. The iterator must be released when the iteration is finished.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryEntryGetChildEntry

    int IORegistryEntryGetChildEntry(IOKit.IORegistryEntry entry, String plane, PointerByReference child)
    Returns the first child of a registry entry in a plane.
    Parameters:
      `entry` - The registry entry whose child to look up.
      `plane` - The name of an existing registry plane. Plane names are defined in `IOKitKeys.h`, for example, `kIOServicePlane`.
      `child` - The first child of the registry entry, on success. The child must be released by the caller.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryEntryGetParentEntry

    int IORegistryEntryGetParentEntry(IOKit.IORegistryEntry entry, String plane, PointerByReference parent)
    Returns the first parent of a registry entry in a plane.
    Parameters:
      `entry` - The registry entry whose parent to look up.
      `plane` - The name of an existing registry plane. Plane names are defined in `IOKitKeys.h`, for example, `kIOServicePlane`.
      `parent` - The first parent of the registry entry, on success. The parent must be released by the caller.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IORegistryGetRootEntry

    IOKit.IORegistryEntry IORegistryGetRootEntry(int masterPort)
    Return a handle to the registry root.
    Parameters:
      `masterPort` - The master port obtained from `IOMasterPort(int, com.sun.jna.ptr.IntByReference)`.
    Returns:
      A handle to the IORegistryEntry root instance, to be released with `IOObjectRelease(com.sun.jna.platform.mac.IOKit.IOObject)` by the caller, or 0 on failure.

  - ### IOObjectConformsTo

    boolean IOObjectConformsTo(IOKit.IOObject object, String className)
    Performs an OSDynamicCast operation on an IOKit object.
    Parameters:
      `object` - An IOKit object.
      `className` - The name of the class.
    Returns:
      If the object handle is valid, and represents an object in the kernel that dynamic casts to the class true is returned, otherwise false.

  - ### IOObjectRelease

    int IOObjectRelease(IOKit.IOObject object)
    Releases an object handle previously returned by `IOKitLib`.
    Parameters:
      `object` - The IOKit object to release.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IOServiceOpen

    int IOServiceOpen(IOKit.IOService service, int owningTask, int type, PointerByReference connect)
    A request to create a connection to an IOService.
    Parameters:
      `service` - The IOService object to open a connection to, usually obtained via the `IOServiceGetMatchingServices(int, com.sun.jna.platform.mac.CoreFoundation.CFDictionaryRef, com.sun.jna.ptr.PointerByReference)` API.
      `owningTask` - The mach task requesting the connection.
      `type` - A constant specifying the type of connection to be created, interpreted only by the IOService's family.
      `connect` - An `io_connect_t` handle is returned on success, to be used with the IOConnectXXX APIs. It should be destroyed with `IOServiceClose(com.sun.jna.platform.mac.IOKit.IOConnect)`.
    Returns:
      A return code generated by `IOService::newUserClient`.

  - ### IOServiceGetBusyState

    int IOServiceGetBusyState(IOKit.IOService service, IntByReference busyState)
    Returns the busyState of an IOService.
    Parameters:
      `service` - The IOService whose busyState to return.
      `busyState` - The busyState count is returned.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IOServiceClose

    int IOServiceClose(IOKit.IOConnect connect)
    Close a connection to an IOService and destroy the connect handle.
    Parameters:
      `connect` - The connect handle created by IOServiceOpen. It will be destroyed by this function, and should not be released with IOObjectRelease.
    Returns:
      0 if successful, otherwise a `kern_return_t` error code.

  - ### IOPSCopyPowerSourcesInfo

    CoreFoundation.CFTypeRef IOPSCopyPowerSourcesInfo()
    Returns a blob of Power Source information in an opaque CFTypeRef.
    Returns:
      `null` if errors were encountered, a `CoreFoundation.CFTypeRef` otherwise.

      Caller must `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)` the return value when done accessing it.

  - ### IOPSCopyPowerSourcesList

    CoreFoundation.CFArrayRef IOPSCopyPowerSourcesList(CoreFoundation.CFTypeRef blob)
    Returns a CFArray of Power Source handles, each of type CFTypeRef.
    Parameters:
      `blob` - Takes the `CoreFoundation.CFTypeRef` returned by `IOPSCopyPowerSourcesInfo()`
    Returns:
      `null` if errors were encountered, otherwise a CFArray of `CoreFoundation.CFTypeRef`s.

      Caller must `CoreFoundation.CFRelease(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)` the returned `CoreFoundation.CFArrayRef`.

  - ### IOPSGetPowerSourceDescription

    CoreFoundation.CFDictionaryRef IOPSGetPowerSourceDescription(CoreFoundation.CFTypeRef blob, CoreFoundation.CFTypeRef ps)
    Returns a CFDictionary with readable information about the specific power source.
    Parameters:
      `blob` - the `CoreFoundation.CFTypeRef` returned by `IOPSCopyPowerSourcesInfo()`
      `ps` - One of the `CoreFoundation.CFTypeRef`s in the CFArray returned by `IOPSCopyPowerSourcesList(com.sun.jna.platform.mac.CoreFoundation.CFTypeRef)`.
    Returns:
      `null` if an error was encountered, otherwise a CFDictionary.

      Caller should NOT release the returned CFDictionary - it will be released as part of the `CoreFoundation.CFTypeRef` returned by `IOPSCopyPowerSourcesInfo()`.

  - ### IOPSGetTimeRemainingEstimate

    double IOPSGetTimeRemainingEstimate()
    Returns the estimated seconds remaining until all power sources (battery and/or UPS's) are empty.
    Returns:
      Returns `kIOPSTimeRemainingUnknown` if the OS cannot determine the time remaining.

      Returns `kIOPSTimeRemainingUnlimited` if the system has an unlimited power source.

      Otherwise returns a positive number indicating the time remaining in seconds until all power sources are depleted.