|
ADC Home > Reference Library > Reference > Hardware & Drivers > 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 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) ;
deviceReference to an IOHIDDevice.
optionsOption 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) ;
deviceReference to an IOHIDDevice.
usagePageDevice usage page
usageDevice 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) ;
deviceReference to an IOHIDDevice.
matchingCFDictionaryRef containg element matching criteria.
optionsReserved for future use.
Returns CFArrayRef containing multiple IOHIDElement object.
Matching keys are prefixed by kIOHIDElement and declared in
Copies a values for multiple elements.
Reference to an IOHIDDevice. CFArrayRef containing multiple IOHIDElementRefs whose
values are to be obtained. 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.
Copies a values for multiple elements and returns status via a
completion callback.
Reference to an IOHIDDevice. CFArrayRef containing multiple IOHIDElementRefs whose
values are to be obtained. Pointer to CFDictionaryRef where the keys are the
provided elements and the values are the requested values. CFTimeInterval containing the timeout. Pointer to a callback method of type
IOHIDValueMultipleCallback. 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.
Creates an element from an io_service_t.
Allocator to be used during creation. 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.
Obtains a property from an IOHIDDevice.
Reference to an IOHIDDevice. CFStringRef containing key to be used when querying the
device. Returns CFTypeRef containing the property.
Property keys are prefixed by kIOHIDDevice and declared in
Obtains a report from the device.
Reference to an IOHIDDevice. Type of report being requested. ID of the report being requested. Pointer to preallocated buffer in which to copy inbound
report data. 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.
Obtains a report from the device.
Reference to an IOHIDDevice. Type of report being requested. ID of the report being requested. Pointer to preallocated buffer in which to copy inbound
report data. 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. Pointer to a callback method of type
IOHIDReportCallback. 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.
Returns the type identifier of all IOHIDDevice instances.
Gets a value for an element.
Reference to an IOHIDDevice. IOHIDElementRef whose value is to be obtained. 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.
Gets a value for an element and returns status via a completion
callback.
Reference to an IOHIDDevice. IOHIDElementRef whose value is to be obtained. Pointer to IOHIDValueRef to be passedback. CFTimeInterval containing the timeout. Pointer to a callback method of type
IOHIDValueCallback. 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.
Opens a HID device for communication.
Reference to an IOHIDDevice. 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.
Registers a callback to be used when an input report is issued
by the device.
Reference to an IOHIDDevice. Pointer to preallocated buffer in which to copy inbound
report data. Length of preallocated buffer. Pointer to a callback method of type
IOHIDReportCallback. Pointer to data to be passed to the callback. An input report is an interrupt driver report issued by the
device.
Registers a callback to be used when an input value is issued by
the device.
Reference to an IOHIDDevice. Pointer to a callback method of type IOHIDValueCallback. 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.
Registers a callback to be used when a IOHIDDevice is removed.
Reference to an IOHIDDevice. Pointer to a callback method of type IOHIDCallback. Pointer to data to be passed to the callback. In most cases this occurs when a device is unplugged.
Schedules HID device with run loop.
Reference to an IOHIDDevice. RunLoop to be used when scheduling any asynchronous
activity. 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.
Sets matching criteria for input values received via
IOHIDDeviceRegisterInputValueCallback.
Reference to an IOHIDDevice. CFDictionaryRef containg device matching criteria. Matching keys are prefixed by kIOHIDElement and declared in
Sets multiple matching criteria for input values received via
IOHIDDeviceRegisterInputValueCallback.
Reference to an IOHIDDevice. CFArrayRef containing multiple CFDictionaryRef objects
containg input element matching criteria. Matching keys are prefixed by kIOHIDElement and declared in
Sets a property for an IOHIDDevice.
Reference to an IOHIDDevice. CFStringRef containing key to be used when modifiying the
device property. CFTypeRef containg the property to be set. Returns TRUE if successful.
Property keys are prefixed by kIOHIDDevice and declared in
Sends a report to the device.
Reference to an IOHIDDevice. Type of report being sent. ID of the report being sent. If the device supports
multiple reports, this should also be set in the first byte of
the report. The report bytes to be sent to the device. 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.
Sends a report to the device.
Reference to an IOHIDDevice. Type of report being sent. ID of the report being sent. If the device supports
multiple reports, this should also be set in the first byte of
the report. The report bytes to be sent to the device. The length of the report to be sent to the device. CFTimeInterval containing the timeout. Pointer to a callback method of type
IOHIDReportCallback. 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.
Sets a value for an element.
Reference to an IOHIDDevice. IOHIDElementRef whose value is to be modified. 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.
Sets multiple values for multiple elements.
Reference to an IOHIDDevice. 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.
Sets multiple values for multiple elements and returns status
via a completion callback.
Reference to an IOHIDDevice. CFDictionaryRef where key is IOHIDElementRef and
value is IOHIDValueRef. CFTimeInterval containing the timeout. Pointer to a callback method of type
IOHIDValueMultipleCallback. 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.
Sets a value for an element and returns status via a completion
callback.
Reference to an IOHIDDevice. IOHIDElementRef whose value is to be modified. IOHIDValueRef containing value to be set. CFTimeInterval containing the timeout. Pointer to a callback method of type
IOHIDValueCallback. 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.
Unschedules HID device with run loop.
Reference to an IOHIDDevice. RunLoop to be used when unscheduling any asynchronous
activity. Run loop mode to be used when unscheduling any
asynchronous activity. Formally disassociates device with client's run loop.
IOHIDDeviceCopyValueMultiple
CF_EXPORT IOReturn IOHIDDeviceCopyValueMultiple(
IOHIDDeviceRef device,
CFArrayRef elements,
CFDictionaryRef *pMultiple) ;
Parameters
deviceelementspMultipleReturn Value
Discussion
IOHIDDeviceCopyValueMultipleWithCallback
CF_EXPORT IOReturn IOHIDDeviceCopyValueMultipleWithCallback(
IOHIDDeviceRef device,
CFArrayRef elements,
CFDictionaryRef *pMultiple,
CFTimeInterval timeout,
IOHIDValueMultipleCallback callback,
void *context) ;
Parameters
deviceelementspMultipletimeoutcallbackcontextReturn Value
Discussion
IOHIDDeviceCreate
CF_EXPORT IOHIDDeviceRef IOHIDDeviceCreate(
CFAllocatorRef allocator,
io_service_t service) ;
Parameters
allocatorio_service_tReturn Value
Discussion
IOHIDDeviceGetProperty
CF_EXPORT CFTypeRef IOHIDDeviceGetProperty(
IOHIDDeviceRef device,
CFStringRef key) ;
Parameters
devicekeyReturn Value
Discussion
IOHIDDeviceGetReport
CF_EXPORT IOReturn IOHIDDeviceGetReport(
IOHIDDeviceRef device,
IOHIDReportType reportType,
CFIndex reportID,
uint8_t *report,
CFIndex *pReportLength) ;
Parameters
devicereportTypereportIDreportpReportLengthReturn Value
Discussion
IOHIDDeviceGetReportWithCallback
CF_EXPORT IOReturn IOHIDDeviceGetReportWithCallback(
IOHIDDeviceRef device,
IOHIDReportType reportType,
CFIndex reportID,
uint8_t *report,
CFIndex *pReportLength,
CFTimeInterval timeout,
IOHIDReportCallback callback,
void *context) ;
Parameters
devicereportTypereportIDreportpReportLengthpReportLengthcallbackcontextReturn Value
Discussion
IOHIDDeviceGetTypeID
CF_EXPORT CFTypeID IOHIDDeviceGetTypeID(
void) ;
IOHIDDeviceGetValue
CF_EXPORT IOReturn IOHIDDeviceGetValue(
IOHIDDeviceRef device,
IOHIDElementRef element,
IOHIDValueRef *pValue) ;
Parameters
deviceelementpValueReturn Value
Discussion
IOHIDDeviceGetValueWithCallback
CF_EXPORT IOReturn IOHIDDeviceGetValueWithCallback(
IOHIDDeviceRef device,
IOHIDElementRef element,
IOHIDValueRef *pValue,
CFTimeInterval timeout,
IOHIDValueCallback callback,
void *context) ;
Parameters
deviceelementpValuetimeoutcallbackcontextReturn Value
Discussion
IOHIDDeviceOpen
CF_EXPORT IOReturn IOHIDDeviceOpen(
IOHIDDeviceRef device,
IOOptionBits options) ;
Parameters
deviceoptionsReturn Value
Discussion
IOHIDDeviceRegisterInputReportCallback
CF_EXPORT void IOHIDDeviceRegisterInputReportCallback(
IOHIDDeviceRef device,
uint8_t *report,
CFIndex reportLength,
IOHIDReportCallback callback,
void *context) ;
Parameters
devicereportreportLengthcallbackcontext
Discussion
IOHIDDeviceRegisterInputValueCallback
CF_EXPORT void IOHIDDeviceRegisterInputValueCallback(
IOHIDDeviceRef device,
IOHIDValueCallback callback,
void *context) ;
Parameters
devicecallbackcontext
Discussion
IOHIDDeviceRegisterRemovalCallback
CF_EXPORT void IOHIDDeviceRegisterRemovalCallback(
IOHIDDeviceRef device,
IOHIDCallback callback,
void *context) ;
Parameters
devicecallbackcontext
Discussion
IOHIDDeviceScheduleWithRunLoop
CF_EXPORT void IOHIDDeviceScheduleWithRunLoop(
IOHIDDeviceRef device,
CFRunLoopRef runLoop,
CFStringRef runLoopMode) ;
Parameters
devicerunLooprunLoopMode
Discussion
IOHIDDeviceSetInputValueMatching
CF_EXPORT void IOHIDDeviceSetInputValueMatching(
IOHIDDeviceRef device,
CFDictionaryRef matching) ;
Parameters
managermatching
Discussion
IOHIDDeviceSetInputValueMatchingMultiple
CF_EXPORT void IOHIDDeviceSetInputValueMatchingMultiple(
IOHIDDeviceRef device,
CFArrayRef multiple) ;
Parameters
managermultiple
Discussion
IOHIDDeviceSetProperty
CF_EXPORT Boolean IOHIDDeviceSetProperty(
IOHIDDeviceRef device,
CFStringRef key,
CFTypeRef property) ;
Parameters
devicekeypropertyReturn Value
Discussion
IOHIDDeviceSetReport
CF_EXPORT IOReturn IOHIDDeviceSetReport(
IOHIDDeviceRef device,
IOHIDReportType reportType,
CFIndex reportID,
const uint8_t * report,
CFIndex reportLength) ;
Parameters
devicereportTypereportIDreportreportLengthReturn Value
Discussion
IOHIDDeviceSetReportWithCallback
CF_EXPORT IOReturn IOHIDDeviceSetReportWithCallback(
IOHIDDeviceRef device,
IOHIDReportType reportType,
CFIndex reportID,
const uint8_t * report,
CFIndex reportLength,
CFTimeInterval timeout,
IOHIDReportCallback callback,
void * context) ;
Parameters
devicereportTypereportIDreportreportLengthtimeoutcallbackcontextReturn Value
Discussion
IOHIDDeviceSetValue
CF_EXPORT IOReturn IOHIDDeviceSetValue(
IOHIDDeviceRef device,
IOHIDElementRef element,
IOHIDValueRef value) ;
Parameters
deviceelementvalueReturn Value
Discussion
IOHIDDeviceSetValueMultiple
CF_EXPORT IOReturn IOHIDDeviceSetValueMultiple(
IOHIDDeviceRef device,
CFDictionaryRef multiple) ;
Parameters
devicemulipleReturn Value
Discussion
IOHIDDeviceSetValueMultipleWithCallback
CF_EXPORT IOReturn IOHIDDeviceSetValueMultipleWithCallback(
IOHIDDeviceRef device,
CFDictionaryRef multiple,
CFTimeInterval timeout,
IOHIDValueMultipleCallback callback,
void *context) ;
Parameters
devicemulipletimeoutcallbackcontextReturn Value
Discussion
IOHIDDeviceSetValueWithCallback
CF_EXPORT IOReturn IOHIDDeviceSetValueWithCallback(
IOHIDDeviceRef device,
IOHIDElementRef element,
IOHIDValueRef value,
CFTimeInterval timeout,
IOHIDValueCallback callback,
void *context) ;
Parameters
deviceelementvaluetimeoutcallbackcontextReturn Value
Discussion
IOHIDDeviceUnscheduleFromRunLoop
CF_EXPORT void IOHIDDeviceUnscheduleFromRunLoop(
IOHIDDeviceRef device,
CFRunLoopRef runLoop,
CFStringRef runLoopMode) ;
Parameters
devicerunLooprunLoopMode
Discussion
Did this document help you?