Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access I/O Kit Framework Reference
|
IOHIDDevice.h |
Includes: |
<CoreFoundation/CoreFoundation.h> <IOKit/hid/IOHIDBase.h> |
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.
Closes communication with a HID device.
Convenience function that scans the Application Collection elements to see if it conforms to the provided usagePage and usage.
Obtains HID elements that match the criteria contained in the matching dictionary.
Copies a values for multiple elements.
Copies a values for multiple elements and returns status via a completion callback.
Creates an element from an io_service_t.
Obtains a property from an IOHIDDevice.
Obtains a report from the device.
Obtains a report from the device.
Returns the io_service_t for an IOHIDDevice, if it has one.
Returns the type identifier of all IOHIDDevice instances.
Gets a value for an element.
Gets a value for an element and returns status via a completion callback.
Opens a HID device for communication.
Registers a callback to be used when an input report is issued by the device.
Registers a callback to be used when an input value is issued by the device.
Registers a callback to be used when a IOHIDDevice is removed.
Schedules HID device with run loop.
Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
Sets a property for an IOHIDDevice.
Sends a report to the device.
Sends a report to the device.
Sets a value for an element.
Sets multiple values for multiple elements.
Sets multiple values for multiple elements and returns status via a completion callback.
Sets a value for an element and returns status via a completion callback.
Unschedules HID device with run loop.
IOHIDDeviceClose |
Closes communication with a HID device.
CF_EXPORT IOReturn IOHIDDeviceClose( IOHIDDeviceRef device, IOOptionBits options) ;
device
Reference to an IOHIDDevice.
options
Option bits to be sent down to the device.
Returns kIOReturnSuccess if successful.
This closes a link between the client's task and the actual device.
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) ;
device
Reference to an IOHIDDevice.
usagePage
Device usage page
usage
Device usage
Returns TRUE if device conforms to provided usage.
Examples of Application Collection usages pairs are:
usagePage = kHIDPage_GenericDesktop
usage = kHIDUsage_GD_Mouse
or
usagePage = kHIDPage_GenericDesktop
usage = kHIDUsage_GD_Keyboard
IOHIDDeviceCopyMatchingElements |
Obtains HID elements that match the criteria contained in the matching dictionary.
CF_EXPORT CFArrayRef IOHIDDeviceCopyMatchingElements( IOHIDDeviceRef device, CFDictionaryRef matching, IOOptionBits options) ;
device
Reference to an IOHIDDevice.
matching
CFDictionaryRef containg element matching criteria.
options
Reserved for future use.
Returns CFArrayRef containing multiple IOHIDElement object.
Matching keys are prefixed by kIOHIDElement and declared in
IOHIDDeviceCopyValueMultiple |
Copies a values for multiple elements.
CF_EXPORT IOReturn IOHIDDeviceCopyValueMultiple( IOHIDDeviceRef device, CFArrayRef elements, CFDictionaryRef *pMultiple) ;
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.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
This method behaves asynchronusly and is only relevent for either output or feature type elements.
IOHIDDeviceCreate |
Creates an element from an io_service_t.
CF_EXPORT IOHIDDeviceRef IOHIDDeviceCreate( CFAllocatorRef allocator, io_service_t service) ;
allocator
Allocator to be used during creation.
io_service_t
Reference to service object in the kernel.
Returns a new IOHIDDeviceRef.
The io_service_t passed in this method must reference an object in the kernel of type IOHIDDevice.
IOHIDDeviceGetProperty |
Obtains a property from an IOHIDDevice.
CF_EXPORT CFTypeRef IOHIDDeviceGetProperty( IOHIDDeviceRef device, CFStringRef key) ;
device
Reference to an IOHIDDevice.
key
CFStringRef containing key to be used when querying the device.
Returns CFTypeRef containing the property.
Property keys are prefixed by kIOHIDDevice and declared in
IOHIDDeviceGetReport |
Obtains a report from the device.
CF_EXPORT IOReturn IOHIDDeviceGetReport( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, uint8_t *report, CFIndex *pReportLength) ;
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.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
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.
IOHIDDeviceGetService |
Returns the io_service_t for an IOHIDDevice, if it has one.
CF_EXPORT io_service_t IOHIDDeviceGetService( IOHIDDeviceRef device) ;
device
Reference to an IOHIDDevice.
Returns the io_service_t if the IOHIDDevice has one, or MACH_PORT_NULL if it does not.
If the IOHIDDevice references an object in the kernel, this is used to get the io_service_t for that object.
IOHIDDeviceGetTypeID |
Returns the type identifier of all IOHIDDevice instances.
CF_EXPORT CFTypeID IOHIDDeviceGetTypeID( void) ;
IOHIDDeviceGetValue |
Gets a value for an element.
CF_EXPORT IOReturn IOHIDDeviceGetValue( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef *pValue) ;
device
Reference to an IOHIDDevice.
element
IOHIDElementRef whose value is to be obtained.
pValue
Pointer to IOHIDValueRef to be obtained.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
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.
IOHIDDeviceOpen |
Opens a HID device for communication.
CF_EXPORT IOReturn IOHIDDeviceOpen( IOHIDDeviceRef device, IOOptionBits options) ;
device
Reference to an IOHIDDevice.
options
Option bits to be sent down to the device.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
An input report is an interrupt driver report issued by the device.
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) ;
device
Reference to an IOHIDDevice.
callback
Pointer to a callback method of type IOHIDValueCallback.
context
Pointer to data to be passed to the callback.
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.
IOHIDDeviceRegisterRemovalCallback |
Registers a callback to be used when a IOHIDDevice is removed.
CF_EXPORT void IOHIDDeviceRegisterRemovalCallback( IOHIDDeviceRef device, IOHIDCallback callback, void *context) ;
device
Reference to an IOHIDDevice.
callback
Pointer to a callback method of type IOHIDCallback.
context
Pointer to data to be passed to the callback.
In most cases this occurs when a device is unplugged.
IOHIDDeviceScheduleWithRunLoop |
Schedules HID device with run loop.
CF_EXPORT void IOHIDDeviceScheduleWithRunLoop( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode) ;
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.
Formally associates device with client's run loop. Scheduling this device with the run loop is necessary before making use of any asynchronous APIs.
IOHIDDeviceSetInputValueMatching |
Sets matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
CF_EXPORT void IOHIDDeviceSetInputValueMatching( IOHIDDeviceRef device, CFDictionaryRef matching) ;
manager
Reference to an IOHIDDevice.
matching
CFDictionaryRef containg device matching criteria.
Matching keys are prefixed by kIOHIDElement and declared in
IOHIDDeviceSetInputValueMatchingMultiple |
Sets multiple matching criteria for input values received via IOHIDDeviceRegisterInputValueCallback.
CF_EXPORT void IOHIDDeviceSetInputValueMatchingMultiple( IOHIDDeviceRef device, CFArrayRef multiple) ;
manager
Reference to an IOHIDDevice.
multiple
CFArrayRef containing multiple CFDictionaryRef objects containg input element matching criteria.
Matching keys are prefixed by kIOHIDElement and declared in
IOHIDDeviceSetProperty |
Sets a property for an IOHIDDevice.
CF_EXPORT Boolean IOHIDDeviceSetProperty( IOHIDDeviceRef device, CFStringRef key, CFTypeRef property) ;
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.
Returns TRUE if successful.
Property keys are prefixed by kIOHIDDevice and declared in
IOHIDDeviceSetReport |
Sends a report to the device.
CF_EXPORT IOReturn IOHIDDeviceSetReport( IOHIDDeviceRef device, IOHIDReportType reportType, CFIndex reportID, const uint8_t * report, CFIndex reportLength) ;
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.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
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.
IOHIDDeviceSetValue |
Sets a value for an element.
CF_EXPORT IOReturn IOHIDDeviceSetValue( IOHIDDeviceRef device, IOHIDElementRef element, IOHIDValueRef value) ;
device
Reference to an IOHIDDevice.
element
IOHIDElementRef whose value is to be modified.
value
IOHIDValueRef containing value to be set.
Returns kIOReturnSuccess if successful.
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.
IOHIDDeviceSetValueMultiple |
Sets multiple values for multiple elements.
CF_EXPORT IOReturn IOHIDDeviceSetValueMultiple( IOHIDDeviceRef device, CFDictionaryRef multiple) ;
device
Reference to an IOHIDDevice.
muliple
CFDictionaryRef where key is IOHIDElementRef and value is IOHIDValueRef.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
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.
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) ;
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.
Returns kIOReturnSuccess if successful.
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.
IOHIDDeviceUnscheduleFromRunLoop |
Unschedules HID device with run loop.
CF_EXPORT void IOHIDDeviceUnscheduleFromRunLoop( IOHIDDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode) ;
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.
Formally disassociates device with client's run loop.
Last Updated: 2009-10-15