1/* 2 * Copyright (c) 1999-2008 Apple Computer, Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24#ifndef _IOKIT_HID_IOHIDTRANSACTION_USER_H 25#define _IOKIT_HID_IOHIDTRANSACTION_USER_H 26 27#include <CoreFoundation/CoreFoundation.h> 28#include <IOKit/hid/IOHIDBase.h> 29 30/*! 31 @header IOHIDTransaction 32 IOHIDTransaction defines an object used to manipulate multiple parsed items 33 (IOHIDElement) contained within a Human Interface Device (HID) object. It 34 is used to minimize device communication when interacting with feature and 35 output type elements that are grouped by their report IDs. IOHIDTransaction 36 is a CFType object and as such conforms to all the conventions expected such 37 object. 38 <p> 39 This documentation assumes that you have a basic understanding of the material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a> 40 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 41 in the "Device Access and the I/O Kit" chapter of <i>Accessing Hardware From Applications</i>. 42 43 This documentation also assumes you have read <a href="http://developer.apple.com/documentation/DeviceDrivers/HumanInterfaceDeviceForceFeedback-date.html"><i>Human Interface Device & Force Feedback</i></a>. 44 Please review documentation before using this reference. 45 <p> 46 All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDTransaction.h</font> found at 47 <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDTransaction.h</font>. 48*/ 49 50__BEGIN_DECLS 51 52/*! @typedef IOHIDTransactionRef 53 This is the type of a reference to the IOHIDTransaction. 54*/ 55typedef struct __IOHIDTransaction * IOHIDTransactionRef; 56 57/*! 58 @function IOHIDTransactionGetTypeID 59 @abstract Returns the type identifier of all IOHIDTransaction instances. 60*/ 61CF_EXPORT 62CFTypeID IOHIDTransactionGetTypeID(void) 63AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 64 65/*! 66 @function IOHIDTransactionCreate 67 @abstract Creates an IOHIDTransaction object for the specified device. 68 @discussion IOHIDTransaction objects can be used to either send or receive 69 multiple element values. As such the direction used should 70 represent they type of objects added to the transaction. 71 @param allocator Allocator to be used during creation. 72 @param device IOHIDDevice object 73 @param direction The direction, either in or out, for the transaction. 74 @param options Reserved for future use. 75 @result Returns a new IOHIDTransactionRef. 76*/ 77CF_EXPORT 78IOHIDTransactionRef IOHIDTransactionCreate( 79 CFAllocatorRef allocator, 80 IOHIDDeviceRef device, 81 IOHIDTransactionDirectionType direction, 82 IOOptionBits options) 83AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 84 85 86/*! 87 @function IOHIDTransactionGetDevice 88 @abstract Obtain the device associated with the transaction. 89 @param transaction IOHIDTransaction to be queried. 90 @result Returns the a reference to the device. 91*/ 92CF_EXPORT 93IOHIDDeviceRef IOHIDTransactionGetDevice( 94 IOHIDTransactionRef transaction) 95AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 96 97/*! 98 @function IOHIDTransactionGetDirection 99 @abstract Obtain the direction of the transaction. 100 @param transaction IOHIDTransaction to be queried. 101 @result Returns the transaction direction. 102*/ 103CF_EXPORT 104IOHIDTransactionDirectionType IOHIDTransactionGetDirection( 105 IOHIDTransactionRef transaction) 106AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 107 108/*! 109 @function IOHIDTransactionSetDirection 110 @abstract Sets the direction of the transaction 111 @disussion This method is useful for manipulating bi-direction (feature) 112 elements such that you can set or get element values without 113 creating an additional transaction object. 114 @param transaction IOHIDTransaction object to be modified. 115 @param direction The new transaction direction. 116*/ 117CF_EXPORT 118void IOHIDTransactionSetDirection( 119 IOHIDTransactionRef transaction, 120 IOHIDTransactionDirectionType direction) 121AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 122 123/*! 124 @function IOHIDTransactionAddElement 125 @abstract Adds an element to the transaction 126 @disussion To minimize device traffic it is important to add elements that 127 share a common report type and report id. 128 @param transaction IOHIDTransaction object to be modified. 129 @param element Element to be added to the transaction. 130*/ 131CF_EXPORT 132void IOHIDTransactionAddElement( 133 IOHIDTransactionRef transaction, 134 IOHIDElementRef element) 135AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 136 137/*! 138 @function IOHIDTransactionRemoveElement 139 @abstract Removes an element to the transaction 140 @param transaction IOHIDTransaction object to be modified. 141 @param element Element to be removed to the transaction. 142*/ 143CF_EXPORT 144void IOHIDTransactionRemoveElement( 145 IOHIDTransactionRef transaction, 146 IOHIDElementRef element) 147AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 148 149/*! 150 @function IOHIDTransactionContainsElement 151 @abstract Queries the transaction to determine if elemement has been added. 152 @param transaction IOHIDTransaction object to be queried. 153 @param element Element to be queried. 154 @result Returns true or false depending if element is present. 155*/ 156CF_EXPORT 157Boolean IOHIDTransactionContainsElement( 158 IOHIDTransactionRef transaction, 159 IOHIDElementRef element) 160AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 161 162/*! 163 @function IOHIDTransactionScheduleWithRunLoop 164 @abstract Schedules transaction with run loop. 165 @discussion Formally associates transaction with client's run loop. 166 Scheduling this transaction with the run loop is necessary 167 before making use of any asynchronous APIs. 168 @param transaction IOHIDTransaction object to be modified. 169 @param runLoop RunLoop to be used when scheduling any asynchronous 170 activity. 171 @param runLoopMode Run loop mode to be used when scheduling any 172 asynchronous activity. 173*/ 174CF_EXPORT 175void IOHIDTransactionScheduleWithRunLoop( 176 IOHIDTransactionRef transaction, 177 CFRunLoopRef runLoop, 178 CFStringRef runLoopMode) 179AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 180 181/*! 182 @function IOHIDTransactionUnscheduleFromRunLoop 183 @abstract Unschedules transaction with run loop. 184 @discussion Formally disassociates transaction with client's run loop. 185 @param transaction IOHIDTransaction object to be modified. 186 @param runLoop RunLoop to be used when scheduling any asynchronous 187 activity. 188 @param runLoopMode Run loop mode to be used when scheduling any 189 asynchronous activity. 190*/ 191CF_EXPORT 192void IOHIDTransactionUnscheduleFromRunLoop( 193 IOHIDTransactionRef transaction, 194 CFRunLoopRef runLoop, 195 CFStringRef runLoopMode) 196AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 197 198/*! 199 @function IOHIDTransactionSetValue 200 @abstract Sets the value for a transaction element. 201 @discussion The value set is pended until the transaction is committed and 202 is only used if the transaction direction is 203 kIOHIDTransactionDirectionTypeOutput. Use the 204 kIOHIDTransactionOptionDefaultOutputValue option to set the 205 default element value. 206 @param transaction IOHIDTransaction object to be modified. 207 @param element Element to be modified after a commit. 208 @param value Value to be set for the given element. 209 @param options See IOHIDTransactionOption. 210*/ 211CF_EXPORT 212void IOHIDTransactionSetValue( 213 IOHIDTransactionRef transaction, 214 IOHIDElementRef element, 215 IOHIDValueRef value, 216 IOOptionBits options) 217AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 218 219/*! 220 @function IOHIDTransactionGetValue 221 @abstract Obtains the value for a transaction element. 222 @discussion If the transaction direction is 223 kIOHIDTransactionDirectionTypeInput the value represents what 224 was obtained from the device from the transaction. Otherwise, 225 if the transaction direction is 226 kIOHIDTransactionDirectionTypeOutput the value represents the 227 pending value to be sent to the device. Use the 228 kIOHIDTransactionOptionDefaultOutputValue option to get the 229 default element value. 230 @param transaction IOHIDTransaction object to be queried. 231 @param element Element to be queried. 232 @param options See IOHIDTransactionOption. 233 @result Returns IOHIDValueRef for the given element. 234*/ 235CF_EXPORT 236IOHIDValueRef IOHIDTransactionGetValue( 237 IOHIDTransactionRef transaction, 238 IOHIDElementRef element, 239 IOOptionBits options) 240AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 241 242/*! 243 @function IOHIDTransactionCommit 244 @abstract Synchronously commits element transaction to the device. 245 @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, 246 default element values will be used if element values are not 247 set. If neither are set, that element will be omitted from the 248 commit. After a transaction is committed, transaction element 249 values will be cleared and default values preserved. 250 @param transaction IOHIDTransaction object to be modified. 251 @result Returns kIOReturnSuccess if successful or a kern_return_t if 252 unsuccessful. 253*/ 254CF_EXPORT 255IOReturn IOHIDTransactionCommit( 256 IOHIDTransactionRef transaction) 257AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 258 259/*! 260 @function IOHIDTransactionCommitWithCallback 261 @abstract Commits element transaction to the device. 262 @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, 263 default element values will be used if element values are not 264 set. If neither are set, that element will be omitted from the 265 commit. After a transaction is committed, transaction element 266 values will be cleared and default values preserved. 267 <br> 268 <b>Note:</b> It is possible for elements from different reports 269 to be present in a given transaction causing a commit to 270 transcend multiple reports. Keep this in mind when setting a 271 appropriate timeout. 272 @param transaction IOHIDTransaction object to be modified. 273 @param timeout Timeout for issuing the transaction. 274 @param callback Callback of type IOHIDCallback to be used when 275 transaction has been completed. If null, this method will 276 behave synchronously. 277 @param context Pointer to data to be passed to the callback. 278 @result Returns kIOReturnSuccess if successful or a kern_return_t if 279 unsuccessful. 280*/ 281CF_EXPORT 282IOReturn IOHIDTransactionCommitWithCallback( 283 IOHIDTransactionRef transaction, 284 CFTimeInterval timeout, 285 IOHIDCallback callback, 286 void * context) 287AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 288 289/*! 290 @function IOHIDTransactionClear 291 @abstract Clears element transaction values. 292 @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, 293 default element values will be preserved. 294 @param transaction IOHIDTransaction object to be modified. 295*/ 296CF_EXPORT 297void IOHIDTransactionClear( 298 IOHIDTransactionRef transaction) 299AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 300 301__END_DECLS 302 303#endif /* _IOKIT_HID_IOHIDTRANSACTION_USER_H */