ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOHIDDevice

Includes:

Overview

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 Accessing Hardware From Applications 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 Human Interface Device & Force Feedback. 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.

Functions

IOHIDDeviceClose: Closes communication with a HID device.
IOHIDDeviceConformsTo: Convenience function that scans the Application Collection elements to see if it conforms to the provided usagePage and usage.
IOHIDDeviceCopyMatchingElements: Obtains HID elements that match the criteria contained in the matching dictionary.
IOHIDDeviceCopyValueMultiple: Copies a values for multiple elements.
IOHIDDeviceCopyValueMultipleWithCallback: Copies a values for multiple elements and returns status via a completion callback.
IOHIDDeviceCreate: Creates an element from an io_service_t.
IOHIDDeviceGetProperty: Obtains a property from an IOHIDDevice.
IOHIDDeviceGetReport: Obtains a report from the device.
IOHIDDeviceGetReportWithCallback: Obtains a report from the device.
IOHIDDeviceGetTypeID: Returns the type identifier of all IOHIDDevice instances.
IOHIDDeviceGetValue: Gets a value for an element.
IOHIDDeviceGetValueWithCallback: Gets a value for an element and returns status via a completion callback.
IOHIDDeviceOpen: Opens a HID device for communication.
IOHIDDeviceRegisterInputReportCallback: Registers a callback to be used when an input report is issued by the device.
IOHIDDeviceRegisterInputValueCallback: Registers a callback to be used when an input value is issued by the device.
IOHIDDeviceRegisterRemovalCallback: Registers a callback to be used when a IOHIDDevice is removed.
IOHIDDeviceScheduleWithRunLoop: Schedules HID device with run loop.
IOHIDDeviceSetInputValueMatching: Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
IOHIDDeviceSetInputValueMatchingMultiple: Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
IOHIDDeviceSetProperty: Sets a property for an IOHIDDevice.
IOHIDDeviceSetReport: Sends a report to the device.
IOHIDDeviceSetReportWithCallback: Sends a report to the device.
IOHIDDeviceSetValue: Sets a value for an element.
IOHIDDeviceSetValueMultiple: Sets multiple values for multiple elements.
IOHIDDeviceSetValueMultipleWithCallback: Sets multiple values for multiple elements and returns status via a completion callback.
IOHIDDeviceSetValueWithCallback: Sets a value for an element and returns status via a completion callback.
IOHIDDeviceUnscheduleFromRunLoop: Unschedules HID device with run loop.

IOHIDDeviceClose

Closes communication with a HID device.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceConformsTo

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

CF_EXPORT 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

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceCopyMatchingElements

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

CF_EXPORT 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 . Passing a NULL dictionary will result in all device elements being returned.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceCopyValueMultiple

Copies a values for multiple elements.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceCopyValueMultipleWithCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceCreate

Creates an element from an io_service_t.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetProperty

Obtains a property from an IOHIDDevice.

CF_EXPORT 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 .

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetReport

Obtains a report from the device.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetReportWithCallback

Obtains a report from the device.

CF_EXPORT 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.
pReportLength: 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetTypeID

Returns the type identifier of all IOHIDDevice instances.

CF_EXPORT CFTypeID IOHIDDeviceGetTypeID(
    void) ;

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetValue

Gets a value for an element.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceGetValueWithCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceOpen

Opens a HID device for communication.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceRegisterInputReportCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceRegisterInputValueCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceRegisterRemovalCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceScheduleWithRunLoop

Schedules HID device with run loop.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetInputValueMatching

Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

CF_EXPORT 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 . 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetInputValueMatchingMultiple

Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.

CF_EXPORT 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 . This method is useful if interested in multiple, specific elements .

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetProperty

Sets a property for an IOHIDDevice.

CF_EXPORT 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 .

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetReport

Sends a report to the device.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetReportWithCallback

Sends a report to the device.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetValue

Sets a value for an element.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetValueMultiple

Sets multiple values for multiple elements.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetValueMultipleWithCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceSetValueWithCallback

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

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

IOHIDDeviceUnscheduleFromRunLoop

Unschedules HID device with run loop.

CF_EXPORT 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.

Availability: Introduced in Mac OS X v10.5.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11