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

IOHIDDeviceTransactionInterface

Declared In:

Overview

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

Discussion

The functions listed here will work with any version of the IOHIDDeviceTransactionInterface. This functionality is useful when either setting or getting the values for multiple parsed elements.

Functions

addElement: Adds an element to this IOHIDDeviceTransactionInterface instance.
clear: Clears element transaction values for an IOHIDDeviceTransactionInterface.
commit: Commits element transaction to an IOHIDDevice in this IOHIDDeviceTransactionInterface instance.
containsElement: Checks whether an element has been added to this IOHIDDeviceTransactionInterface instance.
getAsyncEventSource: Obtains the event source for this IOHIDDeviceTransactionInterface instance.
getDirection: Obtains the direction for this IOHIDDeviceTransactionInterface instance.
getValue: Obtains the transaction value for an element in this IOHIDDeviceTransactionInterface instance.
removeElement: Removes an element from this IOHIDDeviceTransactionInterface instance.
setDirection: Sets the direction for this IOHIDDeviceTransactionInterface instance.
setValue: Sets the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

addElement

Adds an element to this IOHIDDeviceTransactionInterface instance.

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

Parameters

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

clear

Clears element transaction values for an IOHIDDeviceTransactionInterface.

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

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
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 regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be preserved.

commit

Commits element transaction to an IOHIDDevice in this IOHIDDeviceTransactionInterface instance.

IOReturn ( *commit)(
    void *self,
    uint32_t timeout,
    IOHIDCallback callback,
    void *context,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
timeout: Timeout in milliseconds for issuing the transaction.
callback: Callback of type IOHIDCallback to be used when transaction has been completed. 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

In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be used if element values are not set. If neither are set, that element will be omitted from the commit. After a transaction is committed, transaction element values will be cleared and default values preserved.
Note: It is possible for elements from different reports to be present in a given transaction causing a commit to transcend multiple reports. Keep this in mind when setting a timeout.

containsElement

Checks whether an element has been added to this IOHIDDeviceTransactionInterface instance.

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

Parameters

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

getAsyncEventSource

Obtains the event source for this IOHIDDeviceTransactionInterface instance.

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

Parameters

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

getDirection

Obtains the direction for this IOHIDDeviceTransactionInterface instance.

IOReturn ( *getDirection)(
    void *self,
    IOHIDTransactionDirectionType *pDirection);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
pDirection: Pointer to a IOHIDTransactionDirectionType to obtain transaction direction.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

Direction constants are declared in IOHIDTransactionDirectionType.

getValue

Obtains the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

IOReturn ( *getValue)(
    void *self,
    IOHIDElementRef element,
    IOHIDValueRef *pValue,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
element: IOHIDElementRef referencing the element of interest.
pValue: Pointer to an IOHIDValueRef to return the element value of the transaction.
options: See IOHIDTransactionOption.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default element value.

removeElement

Removes an element from this IOHIDDeviceTransactionInterface instance.

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

Parameters

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

setDirection

Sets the direction for this IOHIDDeviceTransactionInterface instance.

IOReturn ( *setDirection)(
    void *self,
    IOHIDTransactionDirectionType direction,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
direction: Transaction direction of type IOHIDTransactionDirectionType.
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

Direction constants are declared in IOHIDTransactionDirectionType. Changing directions is useful when dealing with elements of type kIOHIDElementTypeFeature as you use the transaction to both set and get element values.

setValue

Sets the transaction value for an element in this IOHIDDeviceTransactionInterface instance.

IOReturn ( *setValue)(
    void *self,
    IOHIDElementRef element,
    IOHIDValueRef value,
    IOOptionBits options);

Parameters

self: Pointer to the IOHIDDeviceTransactionInterface.
element: IOHIDElementRef referencing the element of interest.
value: IOHIDValueRef referencing element value to be used in the transaction.
options: See IOHIDTransactionOption.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

This method is intended for use with transaction of direction kIOHIDTransactionDirectionTypeOutput. Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element value.

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