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

IOHIDDeviceDeviceInterface

Declared In:

IOHIDDevicePlugIn.h

Overview

The object you use to access HID devices from user space, returned by version 1.5 of the IOHIDFamily.

Discussion

The functions listed here will work with any version of the IOHIDDeviceDeviceInterface.

Note: Please note that methods declared in this interface follow the copy/get/set conventions.

Functions

close: Closes the task's connection to the IOHIDDevice.
copyMatchingElements: Obtains a CFArrayRef containing the IOHIDDeviceDeviceInterface elements that match the passed matching dictionary.
getAsyncEventSource: Obtains the event source for this IOHIDDeviceDeviceInterface instance.
getProperty: Obtains a property related to the IOHIDDevice.
getReport: Obtains a report of type kIOHIDReportTypeInput or kIOHIDReportTypeFeature from the IOHIDDevice.
getValue: Obtains the current value for an element.
open: Opens the IOHIDDevice.
setInputReportCallback: Sets the input report callback to be used when data is received from the Input pipe.
setProperty: Sets a property related to the IOHIDDevice.
setReport: Sends a report of type kIOHIDReportTypeOutput or kIOHIDReportTypeFeature to the IOHIDDevice.
setValue: Sets the value for an element.

close

Closes the task's connection to the IOHIDDevice.

IOReturn ( *close)(
    void *self,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
options: Option bits to be passed down to the user client.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService.

Discussion

Releases the client's access to the IOHIDDevice.

copyMatchingElements

Obtains a CFArrayRef containing the IOHIDDeviceDeviceInterface elements that match the passed matching dictionary.

IOReturn ( *copyMatchingElements)(
    void *self,
    CFDictionaryRef matchingDict,
    CFArrayRef *pElements,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
matchingDict: CFDictionaryRef containing the element properties to match on.
pElements: CFArrayRef containing matched elements.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

Objects contained in the returned array are of type IOHIDElementRef. Please see IOHIDElement.h for additional API information. Elemenet properties are prefixed by kIOHIDElement and declared in IOHIDKeys.h.

getAsyncEventSource

Obtains the event source for this IOHIDDeviceDeviceInterface instance.

IOReturn ( *getAsyncEventSource)(
    void *self,
    CFTypeRef *pSource);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
pSource: Pointer to a CFType to return the run loop event source.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef.

getProperty

Obtains a property related to the IOHIDDevice.

IOReturn ( *getProperty)(
    void *self,
    CFStringRef key,
    CFTypeRef *pProperty);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
key: CFStringRef key
pProperty: Pointer to a CFTypeRef property.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h.

getReport

Obtains a report of type kIOHIDReportTypeInput or kIOHIDReportTypeFeature from the IOHIDDevice.

IOReturn ( *getReport)(
    void *self,
    IOHIDReportType reportType,
    uint32_t reportID,
    uint8_t *report,
    CFIndex *pReportLength, 
    uint32_t timeout,
    IOHIDReportCallback callback,
    void *context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
reportType: The report type.
reportID: The report id.
report: Pointer to a pre-allocated buffer to be filled.
reportLength: Length of the report buffer. When finished, this will contain the actual length of the report.
timeout: Timeout in milliseconds for issuing the getReport.
callback: Callback of type IOHIDReportCallback to be used when report data has been received from the device. If null, this method will behave synchronously.
context: Pointer to data to be passed to the callback.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

This method is useful if specific knowledge of the unparsed report is known to the caller. Otherwise, using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction is recommended.
Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

getValue

Obtains the current value for an element.

IOReturn ( *getValue)(
    void *self,
    IOHIDElementRef element,
    IOHIDValueRef *pValue, 
    uint32_t timeout,
    IOHIDValueCallback callback,
    void *context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
element: IOHIDElementRef referencing the element of interest.
pValue: Pointer to a IOHIDValueRef to return the element value.
timeout: Time in milliseconds to wait before aborting request.
callback: Callback of type IOHIDReportCallback to be used when element value has been received from the device. If null, this method will behave synchronously.
context: Pointer to data to be passed to the callback.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

If an element of type kIOHIDElementTypeFeature is passed, this method will issue a request to the IOHIDDevice. Otherwise, this will return the last value reported by the IOHIDDevice. If requesting multiple feature element values, please consider using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction.
Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

open

Opens the IOHIDDevice.

IOReturn ( *open)(
    void *self,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
options: Option bits to be passed down to the user client.

Return Value

Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid.

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.

setInputReportCallback

Sets the input report callback to be used when data is received from the Input pipe.

IOReturn ( *setInputReportCallback)(
    void *self,
    uint8_t *report,
    CFIndex reportLength, 
    IOHIDReportCallback callback,
    void *context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
report: Pointer to a pre-allocated buffer to be filled and passed back via the callback.
reportLength: Length of the report buffer.
callback: Callback of type IOHIDReportCallback to be used when report data has been receieved by the IOHIDDevice.
context: Pointer to data to be passed to the callback.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

In order to function properly, the event source obtained using getAsyncEventSource must be added to a run loop.

setProperty

Sets a property related to the IOHIDDevice.

IOReturn ( *setProperty)(
    void *self,
    CFStringRef key,
    CFTypeRef property);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
key: CFStringRef key
property: CFTypeRef property.

Return Value

Returns kIOReturnSuccess if successful.

Discussion

Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h.

setReport

Sends a report of type kIOHIDReportTypeOutput or kIOHIDReportTypeFeature to the IOHIDDevice.

IOReturn ( *setReport)(
    void *self,
    IOHIDReportType reportType,
    uint32_t reportID,
    const uint8_t * report,
    CFIndex reportLength, 
    uint32_t timeout,
    IOHIDReportCallback callback,
    void * context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
reportType: The report type.
reportID: The report id.
report: Pointer to a buffer containing the report data to be sent.
reportLength: Length of the report buffer.
timeout: Timeout in milliseconds for issuing the setReport.
callback: Callback of type IOHIDReportCallback to be used after report data has been sent to the device. If null, this method will behave synchronously.
context: Pointer to data to be passed to the callback.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

This method is useful if specific knowledge of the unparsed report is known to the caller. Otherwise, using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeOutput direction is recommended.
Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

setValue

Sets the value for an element.

IOReturn ( *setValue)(
    void *self,
    IOHIDElementRef element,
    IOHIDValueRef value, 
    uint32_t timeout,
    IOHIDValueCallback callback,
    void *context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceDeviceInterface.
element: IOHIDElementRef referencing the element of interest.
value: IOHIDValueRef containing element value to be set.
timeout: Time in milliseconds to wait before aborting request.
callback: Callback of type IOHIDValueCallback to be used after report data has been sent to the device. If null, this method will behave synchronously.
context: Pointer to data to be passed to the callback.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

If setting multiple element values, please consider using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeOutput direction.
Note: In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

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: 2009-02-23