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

IOHIDTransaction.h

Includes:

Overview

IOHIDTransaction defines an object used to manipulate multiple parsed items (IOHIDElement) contained within a Human Interface Device (HID) object. It is used to minimize device communication when interacting with feature and output type elements that are grouped by their report IDs. IOHIDTransaction is 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 in 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 IOHIDTransaction.h found at /System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDTransaction.h.

Functions

IOHIDTransactionAddElement: Adds an element to the transaction @disussion To minimize device traffic it is important to add elements that share a common report type and report id.
IOHIDTransactionClear: Clears element transaction values.
IOHIDTransactionCommit: Synchronously commits element transaction to the device.
IOHIDTransactionCommitWithCallback: Commits element transaction to the device.
IOHIDTransactionContainsElement: Queries the transaction to determine if elemement has been added.
IOHIDTransactionCreate: Creates an IOHIDTransaction object for the specified device.
IOHIDTransactionGetDevice: Obtain the device associated with the transaction.
IOHIDTransactionGetDirection: Obtain the direction of the transaction.
IOHIDTransactionGetTypeID: Returns the type identifier of all IOHIDTransaction instances.
IOHIDTransactionGetValue: Obtains the value for a transaction element.
IOHIDTransactionRemoveElement: Removes an element to the transaction
IOHIDTransactionScheduleWithRunLoop: Schedules transaction with run loop.
IOHIDTransactionSetDirection: Sets the direction of the transaction @disussion This method is useful for manipulating bi-direction (feature) elements such that you can set or get element values without creating an additional transaction object.
IOHIDTransactionSetValue: Sets the value for a transaction element.
IOHIDTransactionUnscheduleFromRunLoop: Unschedules transaction with run loop.

IOHIDTransactionAddElement

Adds an element to the transaction @disussion To minimize device traffic it is important to add elements that share a common report type and report id.

CF_EXPORT void IOHIDTransactionAddElement( 
    IOHIDTransactionRef transaction, 
    IOHIDElementRef element) ;

Parameters

transaction: IOHIDTransaction object to be modified.
element: Element to be added to the transaction.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionClear

Clears element transaction values.

CF_EXPORT void IOHIDTransactionClear( 
    IOHIDTransactionRef transaction) ;

Parameters

transaction: IOHIDTransaction object to be modified.

Discussion

In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be preserved.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionCommit

Synchronously commits element transaction to the device.

CF_EXPORT IOReturn IOHIDTransactionCommit( 
    IOHIDTransactionRef transaction) ;

Parameters

transaction: IOHIDTransaction object to be modified.

Return Value

Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful.

Discussion

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionCommitWithCallback

Commits element transaction to the device.

CF_EXPORT IOReturn IOHIDTransactionCommitWithCallback( 
    IOHIDTransactionRef transaction, 
    CFTimeInterval timeout, 
    IOHIDCallback callback, 
    void *context) ;

Parameters

transaction: IOHIDTransaction object to be modified.
timeout: Timeout 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.

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 appropriate timeout.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionContainsElement

Queries the transaction to determine if elemement has been added.

CF_EXPORT Boolean IOHIDTransactionContainsElement( 
    IOHIDTransactionRef transaction, 
    IOHIDElementRef element) ;

Parameters

transaction: IOHIDTransaction object to be queried.
element: Element to be queried.

Return Value

Returns true or false depending if element is present.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionCreate

Creates an IOHIDTransaction object for the specified device.

CF_EXPORT IOHIDTransactionRef IOHIDTransactionCreate( 
    CFAllocatorRef allocator, 
    IOHIDDeviceRef device, 
    IOHIDTransactionDirectionType direction, 
    IOOptionBits options) ;

Parameters

allocator: Allocator to be used during creation.
device: IOHIDDevice object
direction: The direction, either in or out, for the transaction.
options: Reserved for future use.

Return Value

Returns a new IOHIDTransactionRef.

Discussion

IOHIDTransaction objects can be used to either send or receive multiple element values. As such the direction used should represent they type of objects added to the transaction.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionGetDevice

Obtain the device associated with the transaction.

CF_EXPORT IOHIDDeviceRef IOHIDTransactionGetDevice( 
    IOHIDTransactionRef transaction) ;

Parameters

transaction: IOHIDTransaction to be queried.

Return Value

Returns the a reference to the device.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionGetDirection

Obtain the direction of the transaction.

CF_EXPORT IOHIDTransactionDirectionType IOHIDTransactionGetDirection( 
    IOHIDTransactionRef transaction) ;

Parameters

transaction: IOHIDTransaction to be queried.

Return Value

Returns the transaction direction.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionGetTypeID

Returns the type identifier of all IOHIDTransaction instances.

CF_EXPORT CFTypeID IOHIDTransactionGetTypeID(
    void) ;

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionGetValue

Obtains the value for a transaction element.

CF_EXPORT IOHIDValueRef IOHIDTransactionGetValue( 
    IOHIDTransactionRef transaction, 
    IOHIDElementRef element, 
    IOOptionBits options) ;

Parameters

transaction: IOHIDTransaction object to be queried.
element: Element to be queried.
options: See IOHIDTransactionOption.

Return Value

Returns IOHIDValueRef for the given element.

Discussion

If the transaction direction is kIOHIDTransactionDirectionTypeInput the value represents what was obtained from the device from the transaction. Otherwise, if the transaction direction is kIOHIDTransactionDirectionTypeOutput the value represents the pending value to be sent to the device. Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default element value.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionRemoveElement

Removes an element to the transaction

CF_EXPORT void IOHIDTransactionRemoveElement( 
    IOHIDTransactionRef transaction, 
    IOHIDElementRef element) ;

Parameters

transaction: IOHIDTransaction object to be modified.
element: Element to be removed to the transaction.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionScheduleWithRunLoop

Schedules transaction with run loop.

CF_EXPORT void IOHIDTransactionScheduleWithRunLoop( 
    IOHIDTransactionRef transaction, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

transaction: IOHIDTransaction object to be modified.
runLoop: RunLoop to be used when scheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when scheduling any asynchronous activity.

Discussion

Formally associates transaction with client's run loop. Scheduling this transaction with the run loop is necessary before making use of any asynchronous APIs.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionSetDirection

Sets the direction of the transaction @disussion This method is useful for manipulating bi-direction (feature) elements such that you can set or get element values without creating an additional transaction object.

CF_EXPORT void IOHIDTransactionSetDirection( 
    IOHIDTransactionRef transaction, 
    IOHIDTransactionDirectionType direction) ;

Parameters

transaction: IOHIDTransaction object to be modified.
direction: The new transaction direction.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionSetValue

Sets the value for a transaction element.

CF_EXPORT void IOHIDTransactionSetValue( 
    IOHIDTransactionRef transaction, 
    IOHIDElementRef element, 
    IOHIDValueRef value, 
    IOOptionBits options) ;

Parameters

transaction: IOHIDTransaction object to be modified.
element: Element to be modified after a commit.
value: Value to be set for the given element.
options: See IOHIDTransactionOption.

Discussion

The value set is pended until the transaction is committed and is only used if the transaction direction is kIOHIDTransactionDirectionTypeOutput. Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element value.

Availability: Introduced in Mac OS X v10.5.

IOHIDTransactionUnscheduleFromRunLoop

Unschedules transaction with run loop.

CF_EXPORT void IOHIDTransactionUnscheduleFromRunLoop( 
    IOHIDTransactionRef transaction, 
    CFRunLoopRef runLoop, 
    CFStringRef runLoopMode) ;

Parameters

transaction: IOHIDTransaction object to be modified.
runLoop: RunLoop to be used when scheduling any asynchronous activity.
runLoopMode: Run loop mode to be used when scheduling any asynchronous activity.

Discussion

Formally disassociates transaction with client's run loop.

Availability: Introduced in Mac OS X v10.5.

Typedefs

IOHIDTransactionRef

typedef struct __IOHIDTransaction * IOHIDTransactionRef;

Discussion

This is the type of a reference to the IOHIDTransaction.

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