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

IOHIDDeviceQueueInterface

Declared In:

Overview

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

Discussion

The functions listed here will work with any version of the IOHIDDeviceQueueInterface. This behavior is useful when you need to keep track of all values of an input element, rather than just the most recent one.
Note:Absolute element values (based on a fixed origin) will only be placed on a queue if there is a change in value.

Functions

addElement: Adds an element to this IOHIDDeviceQueueInterface instance.
containsElement: Determines whether an element has been added to this IOHIDDeviceQueueInterface instance.
copyNextValue: Dequeues a retained copy of an element value from the head of an IOHIDDeviceQueueInterface.
getAsyncEventSource: Obtains the event source for this IOHIDDeviceQueueInterface instance.
getDepth: Obtains the queue depth for this IOHIDDeviceQueueInterface instance.
removeElement: Removes an element from this IOHIDDeviceQueueInterface instance.
setDepth: Sets the depth for this IOHIDDeviceQueueInterface instance.
setValueAvailableCallback: Sets callback to be used when the queue transitions to non-empty.
start: Starts element value delivery to the queue.
stop: Stops element value delivery to the queue.

addElement

Adds an element to this IOHIDDeviceQueueInterface instance.

IOReturn ( *addElement)(
    void *self,
    IOHIDElementRef element,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
element: IOHIDElementRef referencing the element to be added to the queue.
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.

containsElement

Determines whether an element has been added to this IOHIDDeviceQueueInterface instance.

IOReturn ( *containsElement)(
    void *self,
    IOHIDElementRef element,
    Boolean *pValue,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
element: IOHIDElementRef referencing the element to be be found in the queue.
pValue: Pointer to a Boolean to return whether or not the element was found in the queue.
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.

copyNextValue

Dequeues a retained copy of an element value from the head of an IOHIDDeviceQueueInterface.

IOReturn ( *copyNextValue)(
    void *self,
    IOHIDValueRef *pValue,
    uint32_t timeout,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
pValue: Pointer to a IOHIDValueRef to return the value at the head of the queue.
timeout: Timeout in milliseconds before aborting an attempt to dequeue a value from the head of a queue.
options: Reserved for future use. Ignored in current implementation. Set to zero.

Return Value

Returns kIOReturnSuccess if successful, kIOReturnUnderrun if data is unavailble, or a kern_return_t if unsuccessful.

Discussion

Because the value is a retained copy, it is up to the caller to release the value using CFRelease. Use with setValueCallback to avoid polling the queue for data.

getAsyncEventSource

Obtains the event source for this IOHIDDeviceQueueInterface instance.

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

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
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.

getDepth

Obtains the queue depth for this IOHIDDeviceQueueInterface instance.

IOReturn ( *getDepth)(
    void *self,
    uint32_t *pDepth);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
pDepth: Pointer to a uint32_t to obtain the number of elements that can be serviced by the queue.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

removeElement

Removes an element from this IOHIDDeviceQueueInterface instance.

IOReturn ( *removeElement)(
    void *self,
    IOHIDElementRef element,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
element: IOHIDElementRef referencing the element to be removed from the queue.
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.

setDepth

Sets the depth for this IOHIDDeviceQueueInterface instance.

IOReturn ( *setDepth)(
    void *self,
    uint32_t depth,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
depth: The maximum number of elements in the queue before the oldest elements in the queue begin to be lost.
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

Regardless of element value size, queue will guarantee n=depth elements will be serviced.

setValueAvailableCallback

Sets callback to be used when the queue transitions to non-empty.

IOReturn ( *setValueAvailableCallback)(
    void *self,
    IOHIDCallback callback,
    void *context);

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
callback: Callback of type IOHIDCallback to be used when data is placed on the queue.
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 make use of asynchronous behavior, the event source obtained using getAsyncEventSource must be added to a run loop.

start

Starts element value delivery to the queue.

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

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
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.

stop

Stops element value delivery to the queue.

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

Parameters

self: Pointer to the IOHIDDeviceQueueInterface.
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.

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