Mac Developer Library

Developer

IOHIDDevice.h User-Space Reference

Options
Deployment Target:

On This Page

IOHIDDevice.h User-Space Reference

IOHIDDevice defines a Human Interface Device (HID) object, which interacts with an IOHIDDevicePlugIn object that typically maps to an object in the kernel. IOHIDDevice is used to communicate with a single HID device in order to obtain or set device properties, element values, and reports. IOHIDDevice is also a CFType object and as such conforms to all the conventions expected such object.

This documentation assumes that you have a basic understanding of the material contained in For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts n the "Device Access and the I/O Kit" chapter of Accessing Hardware From Applications.

This documentation also assumes you have read . Please review documentation before using this reference.

All of the information described in this document is contained in the header file IOHIDDevice.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDDevice.h.

Included Headers

  • <CoreFoundation/CoreFoundation.h>

  • <IOKit/hid/IOHIDBase.h>

Functions

  • Closes communication with a HID device.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceClose ( IOHIDDeviceRef device, IOOptionBits options );

    Parameters

    device

    Reference to an IOHIDDevice.

    options

    Option bits to be sent down to the device.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This closes a link between the client's task and the actual device.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Convenience function that scans the Application Collection elements to see if it conforms to the provided usagePage and usage.

    Declaration

    Objective-C

    Boolean IOHIDDeviceConformsTo ( IOHIDDeviceRef device, uint32_t usagePage, uint32_t usage );

    Parameters

    device

    Reference to an IOHIDDevice.

    usagePage

    Device usage page

    usage

    Device usage

    Return Value

    Returns TRUE if device conforms to provided usage.

    Discussion

    Examples of Application Collection usages pairs are:

    usagePage = kHIDPage_GenericDesktop

    usage = kHIDUsage_GD_Mouse

    or

    usagePage = kHIDPage_GenericDesktop

    usage = kHIDUsage_GD_Keyboard

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Obtains HID elements that match the criteria contained in the matching dictionary.

    Declaration

    Objective-C

    CFArrayRef IOHIDDeviceCopyMatchingElements ( IOHIDDeviceRef device, CFDictionaryRef matching, IOOptionBits options );

    Parameters

    device

    Reference to an IOHIDDevice.

    matching

    CFDictionaryRef containg element matching criteria.

    options

    Reserved for future use.

    Return Value

    Returns CFArrayRef containing multiple IOHIDElement object.

    Discussion

    Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result in all device elements being returned.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Copies a values for multiple elements.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceCopyValueMultiple ( IOHIDDeviceRef device, CFArrayRef elements, CFDictionaryRef *pMultiple );

    Parameters

    device

    Reference to an IOHIDDevice.

    elements

    CFArrayRef containing multiple IOHIDElementRefs whose values are to be obtained.

    pMultiple

    Pointer to CFDictionaryRef where the keys are the provided elements and the values are the requested values.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and return back immediately for input type element. If requesting a value for a feature element, this will block until the report has been issued to the device.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Copies a values for multiple elements and returns status via a completion callback.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceCopyValueMultipleWithCallback ( IOHIDDeviceRef device, CFArrayRef elements, CFDictionaryRef *pMultiple, CFTimeInterval timeout, IOHIDValueMultipleCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    elements

    CFArrayRef containing multiple IOHIDElementRefs whose values are to be obtained.

    pMultiple

    Pointer to CFDictionaryRef where the keys are the provided elements and the values are the requested values.

    timeout

    CFTimeInterval containing the timeout.

    callback

    Pointer to a callback method of type IOHIDValueMultipleCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronusly and is only relevent for either output or feature type elements.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Creates an element from an io_service_t.

    Declaration

    Objective-C

    IOHIDDeviceRef IOHIDDeviceCreate ( CFAllocatorRef allocator, io_service_t service );

    Parameters

    allocator

    Allocator to be used during creation.

    io_service_t

    Reference to service object in the kernel.

    Return Value

    Returns a new IOHIDDeviceRef.

    Discussion

    The io_service_t passed in this method must reference an object in the kernel of type IOHIDDevice.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Obtains a property from an IOHIDDevice.

    Declaration

    Objective-C

    CFTypeRef IOHIDDeviceGetProperty ( IOHIDDeviceRef device, CFStringRef key );

    Parameters

    device

    Reference to an IOHIDDevice.

    key

    CFStringRef containing key to be used when querying the device.

    Return Value

    Returns CFTypeRef containing the property.

    Discussion

    Property keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Obtains a report from the device.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceGetReport ( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, uint8_t *report, CFIndex *pReportLength );

    Parameters

    device

    Reference to an IOHIDDevice.

    reportType

    Type of report being requested.

    reportID

    ID of the report being requested.

    report

    Pointer to preallocated buffer in which to copy inbound report data.

    pReportLength

    Pointer to length of preallocated buffer. This value will be modified to refect the length of the returned report.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and will block until the report has been received from the device. This is only intended for feature reports because of sporadic devicesupport for polling input reports. Please defer to using IOHIDDeviceRegisterInputReportCallback for obtaining input reports.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Obtains a report from the device.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceGetReportWithCallback ( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, uint8_t *report, CFIndex *pReportLength, CFTimeInterval timeout, IOHIDReportCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    reportType

    Type of report being requested.

    reportID

    ID of the report being requested.

    report

    Pointer to preallocated buffer in which to copy inbound report data.

    pReportLength

    Pointer to length of preallocated buffer.

    Pointer to length of preallocated buffer. This value will be modified to refect the length of the returned report.

    callback

    Pointer to a callback method of type IOHIDReportCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronously and will block until the report has been received from the device. This is only intended for feature reports because of sporadic devicesupport for polling input reports. Please defer to using IOHIDDeviceRegisterInputReportCallback for obtaining input reports.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Returns the io_service_t for an IOHIDDevice, if it has one.

    Declaration

    Objective-C

    io_service_t IOHIDDeviceGetService ( IOHIDDeviceRef device );

    Parameters

    device

    Reference to an IOHIDDevice.

    Return Value

    Returns the io_service_t if the IOHIDDevice has one, or MACH_PORT_NULL if it does not.

    Discussion

    If the IOHIDDevice references an object in the kernel, this is used to get the io_service_t for that object.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.6 and later.

  • Returns the type identifier of all IOHIDDevice instances.

    Declaration

    Objective-C

    CFTypeID IOHIDDeviceGetTypeID ( void );

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Gets a value for an element.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceGetValue ( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef *pValue );

    Parameters

    device

    Reference to an IOHIDDevice.

    element

    IOHIDElementRef whose value is to be obtained.

    pValue

    Pointer to IOHIDValueRef to be obtained.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and return back immediately for input type element. If requesting a value for a feature element, this will block until the report has been issued to the device. If obtaining values for multiple elements you may want to consider using IOHIDDeviceCopyValueMultiple or IOHIDTransaction.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Gets a value for an element and returns status via a completion callback.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceGetValueWithCallback ( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef *pValue, CFTimeInterval timeout, IOHIDValueCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    element

    IOHIDElementRef whose value is to be obtained.

    pValue

    Pointer to IOHIDValueRef to be passedback.

    timeout

    CFTimeInterval containing the timeout.

    callback

    Pointer to a callback method of type IOHIDValueCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronusly and is only relevent for either output or feature type elements. If obtaining values for multiple elements you may want to consider using IOHIDDeviceCopyValueMultipleWithCallback or IOHIDTransaction.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Opens a HID device for communication.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceOpen ( IOHIDDeviceRef device, IOOptionBits options );

    Parameters

    device

    Reference to an IOHIDDevice.

    options

    Option bits to be sent down to the device.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    Before the client can issue commands that change the state of the device, it must have succeeded in opening the device. This establishes a link between the client's task and the actual device. To establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Registers a callback to be used when an input report is issued by the device.

    Declaration

    Objective-C

    void IOHIDDeviceRegisterInputReportCallback ( IOHIDDeviceRef device, uint8_t *report, CFIndex reportLength, IOHIDReportCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    report

    Pointer to preallocated buffer in which to copy inbound report data.

    reportLength

    Length of preallocated buffer.

    callback

    Pointer to a callback method of type IOHIDReportCallback.

    context

    Pointer to data to be passed to the callback.

    Discussion

    An input report is an interrupt driver report issued by the device.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Registers a callback to be used when an input value is issued by the device.

    Declaration

    Objective-C

    void IOHIDDeviceRegisterInputValueCallback ( IOHIDDeviceRef device, IOHIDValueCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    callback

    Pointer to a callback method of type IOHIDValueCallback.

    context

    Pointer to data to be passed to the callback.

    Discussion

    An input element refers to any element of type kIOHIDElementTypeInput and is usually issued by interrupt driven reports. If more specific element values are desired, you can specify matching criteria via IOHIDDeviceSetInputValueMatching and IOHIDDeviceSetInputValueMatchingMultiple.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Registers a callback to be used when a IOHIDDevice is removed.

    Declaration

    Objective-C

    void IOHIDDeviceRegisterRemovalCallback ( IOHIDDeviceRef device, IOHIDCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    callback

    Pointer to a callback method of type IOHIDCallback.

    context

    Pointer to data to be passed to the callback.

    Discussion

    In most cases this occurs when a device is unplugged.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Schedules HID device with run loop.

    Declaration

    Objective-C

    void IOHIDDeviceScheduleWithRunLoop ( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    device

    Reference to an IOHIDDevice.

    runLoop

    RunLoop to be used when scheduling any asynchronous activity.

    runLoopMode

    Run loop mode to be used when scheduling any asynchronous activity.

    Discussion

    Formally associates device with client's run loop. Scheduling this device with the run loop is necessary before making use of any asynchronous APIs.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

    Declaration

    Objective-C

    void IOHIDDeviceSetInputValueMatching ( IOHIDDeviceRef device, CFDictionaryRef matching );

    Parameters

    manager

    Reference to an IOHIDDevice.

    matching

    CFDictionaryRef containg device matching criteria.

    Discussion

    Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result in all devices being enumerated. Any subsequent calls will cause the hid manager to release previously matched input elements and restart the matching process using the revised criteria. If interested in multiple, specific device elements, please defer to using IOHIDDeviceSetInputValueMatchingMultiple.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

    Declaration

    Objective-C

    void IOHIDDeviceSetInputValueMatchingMultiple ( IOHIDDeviceRef device, CFArrayRef multiple );

    Parameters

    manager

    Reference to an IOHIDDevice.

    multiple

    CFArrayRef containing multiple CFDictionaryRef objects containg input element matching criteria.

    Discussion

    Matching keys are prefixed by kIOHIDElement and declared in <IOKit/hid/IOHIDKeys.h>. This method is useful if interested in multiple, specific elements .

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets a property for an IOHIDDevice.

    Declaration

    Objective-C

    Boolean IOHIDDeviceSetProperty ( IOHIDDeviceRef device, CFStringRef key, CFTypeRef property );

    Parameters

    device

    Reference to an IOHIDDevice.

    key

    CFStringRef containing key to be used when modifiying the device property.

    property

    CFTypeRef containg the property to be set.

    Return Value

    Returns TRUE if successful.

    Discussion

    Property keys are prefixed by kIOHIDDevice and declared in <IOKit/hid/IOHIDKeys.h>.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sends a report to the device.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetReport ( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, const uint8_t *report, CFIndex reportLength );

    Parameters

    device

    Reference to an IOHIDDevice.

    reportType

    Type of report being sent.

    reportID

    ID of the report being sent. If the device supports multiple reports, this should also be set in the first byte of the report.

    report

    The report bytes to be sent to the device.

    reportLength

    The length of the report to be sent to the device.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type reports.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sends a report to the device.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetReportWithCallback ( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, const uint8_t *report, CFIndex reportLength, CFTimeInterval timeout, IOHIDReportCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    reportType

    Type of report being sent.

    reportID

    ID of the report being sent. If the device supports multiple reports, this should also be set in the first byte of the report.

    report

    The report bytes to be sent to the device.

    reportLength

    The length of the report to be sent to the device.

    timeout

    CFTimeInterval containing the timeout.

    callback

    Pointer to a callback method of type IOHIDReportCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type reports.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets a value for an element.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetValue ( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef value );

    Parameters

    device

    Reference to an IOHIDDevice.

    element

    IOHIDElementRef whose value is to be modified.

    value

    IOHIDValueRef containing value to be set.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type elements. If setting values for multiple elements you may want to consider using IOHIDDeviceSetValueMultiple or IOHIDTransaction.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets multiple values for multiple elements.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetValueMultiple ( IOHIDDeviceRef device, CFDictionaryRef multiple );

    Parameters

    device

    Reference to an IOHIDDevice.

    muliple

    CFDictionaryRef where key is IOHIDElementRef and value is IOHIDValueRef.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves synchronously and will block until the report has been issued to the device. It is only relevent for either output or feature type elements.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets multiple values for multiple elements and returns status via a completion callback.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetValueMultipleWithCallback ( IOHIDDeviceRef device, CFDictionaryRef multiple, CFTimeInterval timeout, IOHIDValueMultipleCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    muliple

    CFDictionaryRef where key is IOHIDElementRef and value is IOHIDValueRef.

    timeout

    CFTimeInterval containing the timeout.

    callback

    Pointer to a callback method of type IOHIDValueMultipleCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronously and will invoke the callback once the report has been issued to the device. It is only relevent for either output or feature type elements.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Sets a value for an element and returns status via a completion callback.

    Declaration

    Objective-C

    IOReturn IOHIDDeviceSetValueWithCallback ( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef value, CFTimeInterval timeout, IOHIDValueCallback callback, void *context );

    Parameters

    device

    Reference to an IOHIDDevice.

    element

    IOHIDElementRef whose value is to be modified.

    value

    IOHIDValueRef containing value to be set.

    timeout

    CFTimeInterval containing the timeout.

    callback

    Pointer to a callback method of type IOHIDValueCallback.

    context

    Pointer to data to be passed to the callback.

    Return Value

    Returns kIOReturnSuccess if successful.

    Discussion

    This method behaves asynchronously and will invoke the callback once the report has been issued to the device. It is only relevent for either output or feature type elements. If setting values for multiple elements you may want to consider using IOHIDDeviceSetValueWithCallback or IOHIDTransaction.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.

  • Unschedules HID device with run loop.

    Declaration

    Objective-C

    void IOHIDDeviceUnscheduleFromRunLoop ( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode );

    Parameters

    device

    Reference to an IOHIDDevice.

    runLoop

    RunLoop to be used when unscheduling any asynchronous activity.

    runLoopMode

    Run loop mode to be used when unscheduling any asynchronous activity.

    Discussion

    Formally disassociates device with client's run loop.

    Import Statement

    Objective-C

    @import IOKit;

    Availability

    Available in OS X v10.5 and later.