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_IOHIDDEVICEPLUGIN_H 25#define _IOKIT_HID_IOHIDDEVICEPLUGIN_H 26 27 28#include <sys/cdefs.h> 29#include <CoreFoundation/CoreFoundation.h> 30#if COREFOUNDATION_CFPLUGINCOM_SEPARATE 31#include <CoreFoundation/CFPlugInCOM.h> 32#endif 33 34#include <IOKit/IOTypes.h> 35#include <IOKit/IOReturn.h> 36#include <IOKit/IOCFPlugIn.h> 37#include <IOKit/hid/IOHIDBase.h> 38#include <IOKit/hid/IOHIDKeys.h> 39#include <IOKit/hid/IOHIDLibObsolete.h> 40 41__BEGIN_DECLS 42/*! @header IOHIDDevicePlugIn 43 This documentation describes the details of the programming interface for accessing Human Interface Devices and 44 interfaces from code running in user space. It is intended that user mode HID drivers properly inplement all 45 interfaces described here in order to be visible via the HID Manager. 46 <p> 47 This documentation assumes that you have a basic understanding 48 of the material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a> 49 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 50 in the "Device Access and the I/O Kit" chapter of <i>Accessing Hardware From Applications</i>. 51 52 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>. 53 Please review documentation before using this reference. 54 <p> 55 All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDLib.h</font> found at 56 <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDDevicePlugIn.h</font>. 57*/ 58 59 60/* 13AA9C44-6F1B-11D4-907C-0005028F18D5 */ 61/*! @defined kIOHIDDeviceFactoryID 62 @discussion This UUID constant is used internally by the system, and 63 should not have to be used by any driver code to access the device interfaces. 64*/ 65#define kIOHIDDeviceFactoryID CFUUIDGetConstantUUIDWithBytes(NULL, \ 66 0x13, 0xAA, 0x9C, 0x44, 0x6F, 0x1B, 0x11, 0xD4, \ 67 0x90, 0x7C, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5) 68 69/* 7DDEECA8-A7B4-11DA-8A0E-0014519758EF */ 70/*! @defined kIOHIDDeviceTypeID 71 @discussion This UUID constant is used to obtain a device interface corresponding to 72 an io_service_t corresponding to an IOHIDDevice in the kernel. Once you have 73 obtained the IOCFPlugInInterface for the service, you must use the QueryInterface 74 function to obtain the device interface for the user client itself. 75 76 Example: 77 <pre> 78 @textblock 79 io_service_t hidDeviceRef; // obtained earlier 80 81 IOCFPlugInInterface **iodev; // fetching this now 82 83 SInt32 score; // not used 84 IOReturn err; 85 86 err = IOCreatePlugInInterfaceForService(hidDeviceRef, 87 kIOHIDDeviceTypeID, 88 kIOCFPlugInInterfaceID, 89 &iodev, 90 &score); 91 @/textblock 92 </pre> 93*/ 94#define kIOHIDDeviceTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \ 95 0x7d, 0xde, 0xec, 0xa8, 0xa7, 0xb4, 0x11, 0xda, \ 96 0x8a, 0x0e, 0x00, 0x14, 0x51, 0x97, 0x58, 0xef) 97 98/* 474BDC8E-9F4A-11DA-B366-000D936D06D2 */ 99/*! @defined kIOHIDDeviceDeviceInterfaceID 100 @discussion This UUID constant is used to obtain a device interface corresponding 101 to an IOHIDDevice service in the kernel. The type of this device interface is IOHIDDeviceDeviceInterface. 102 This device interface is obtained after the IOCFPlugInInterface for the service itself has been obtained. 103 104 <b>Note:</b> Please note that subsequent calls to QueryInterface with the UUID 105 kIOHIDDeviceDeviceInterfaceID, will return a retained instance of an existing IOHIDDeviceDeviceInterface. 106 107 Example: 108 <pre> 109 @textblock 110 IOCFPluginInterface ** iodev; // obtained earlier 111 112 IOHIDDeviceDeviceInterface ** dev; // fetching this now 113 IOReturn err; 114 115 err = (*iodev)->QueryInterface(iodev, 116 CFUUIDGetUUIDBytes(kIOHIDDeviceDeviceInterfaceID), 117 (LPVoid)&dev); 118 @/textblock 119 </pre> 120*/ 121#define kIOHIDDeviceDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 122 0x47, 0x4b, 0xdc, 0x8e, 0x9f, 0x4a, 0x11, 0xda, \ 123 0xb3, 0x66, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2 ) 124 125/* B473256C-6A72-4E04-B694-C4001D202020 */ 126/*! @defined kIOHIDDeviceDeviceInterfaceID2 127 @discussion This UUID constant is used to obtain a device interface corresponding 128 to an IOHIDDevice service in the kernel, but only for timestamped report callbacks. 129 The type of this device interface is IOHIDDeviceTimeStampedDeviceInterface. 130 This device interface is obtained after the IOCFPlugInInterface for the service itself has been obtained. 131 132 <b>Note:</b> Please note that subsequent calls to QueryInterface with the UUID 133 kIOHIDDeviceDeviceInterfaceID2, will return a retained instance of an existing IOHIDDeviceTimeStampedDeviceInterface. 134 135 Example: 136 <pre> 137 @textblock 138 IOCFPluginInterface **iodev; // obtained earlier 139 140 IOHIDDeviceTimeStampedDeviceInterface **devTime;// fetching this now 141 IOReturn err; 142 143 err = (*iodev)->QueryInterface(iodev, 144 CFUUIDGetUUIDBytes(kIOHIDDeviceDeviceInterfaceID2), 145 (LPVoid)&devTime); 146 @/textblock 147 </pre> 148*/ 149#define kIOHIDDeviceDeviceInterfaceID2 CFUUIDGetConstantUUIDWithBytes(NULL, \ 150 0xB4, 0x73, 0x25, 0x6C, 0x6A, 0x72, 0x4E, 0x04, \ 151 0xB6, 0x94, 0xC4, 0x00, 0x1D, 0x20, 0x20, 0x20) 152 153/* 2EC78BDB-9F4E-11DA-B65C-000D936D06D2 */ 154/*! @defined kIOHIDDeviceQueueInterfaceID 155 @discussion This UUID constant is used to obtain a queue interface corresponding 156 to an IOHIDDevice service in the kernel. The type of this queue interface 157 is IOHIDDeviceQueueInterface. This device interface is obtained after the device interface 158 for the service itself has been obtained. 159 160 <b>Note:</b> Please note that subsequent calls to QueryInterface with the UUID 161 kIOHIDDeviceQueueInterfaceID, will return a retained instance of a new IOHIDDeviceQueueInterface. 162 163 Example: 164 <pre> 165 @textblock 166 IOCFPluginInterface ** iodev; // obtained earlier 167 168 IOHIDDeviceQueueInterface ** intf; // fetching this now 169 IOReturn err; 170 171 err = (*iodev)->QueryInterface(iodev, 172 CFUUIDGetUUIDBytes(kIOHIDDeviceQueueInterfaceID), 173 (LPVoid)&intf); 174 @/textblock 175 </pre> 176*/ 177#define kIOHIDDeviceQueueInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 178 0x2e, 0xc7, 0x8b, 0xdb, 0x9f, 0x4e, 0x11, 0xda, \ 179 0xb6, 0x5c, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2) 180 181/* 1F2E78FA-9FFA-11DA-90B4-000D936D06D2 */ 182/*! @defined kIOHIDDeviceTransactionInterfaceID 183 @discussion This UUID constant is used to obtain a transaction interface corresponding 184 to an IOHIDDevice service in the kernel. The type of this queue interface 185 is IOHIDDeviceTransactionInterface. This device interface is obtained after the device interface 186 for the service itself has been obtained. 187 188 <b>Note:</b> Please note that subsequent calls to QueryInterface with the UUID 189 kIOHIDDeviceTransactionInterfaceID, will return a retained instance of a new IOHIDDeviceTransactionInterface. 190 191 Example: 192 <pre> 193 @textblock 194 IOCFPluginInterface ** iodev; // obtained earlier 195 196 IOHIDDeviceTransactionInterface ** intf; // fetching this now 197 IOReturn err; 198 199 err = (*iodev)->QueryInterface(iodev, 200 CFUUIDGetUUIDBytes(kIOHIDDeviceTransactionInterfaceID), 201 (LPVoid)&intf); 202 @/textblock 203 </pre> 204*/ 205#define kIOHIDDeviceTransactionInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL, \ 206 0x1f, 0x2e, 0x78, 0xfa, 0x9f, 0xfa, 0x11, 0xda, \ 207 0x90, 0xb4, 0x00, 0x0d, 0x93, 0x6d, 0x06, 0xd2) 208 209 210#define IOHID_DEVICE_DEVICE_FUNCS_V1 \ 211 IOReturn (*open)(void * self, IOOptionBits options); \ 212 IOReturn (*close)(void * self, IOOptionBits options); \ 213 IOReturn (*getProperty)(void * self, CFStringRef key, CFTypeRef * pProperty); \ 214 IOReturn (*setProperty)(void * self, CFStringRef key, CFTypeRef property); \ 215 IOReturn (*getAsyncEventSource)(void * self, CFTypeRef * pSource); \ 216 IOReturn (*copyMatchingElements)(void * self, CFDictionaryRef matchingDict, CFArrayRef * pElements, IOOptionBits options); \ 217 IOReturn (*setValue)(void * self, IOHIDElementRef element, IOHIDValueRef value, uint32_t timeout, IOHIDValueCallback callback, void * context, IOOptionBits options); \ 218 IOReturn (*getValue)(void * self, IOHIDElementRef element, IOHIDValueRef * pValue, uint32_t timeout, IOHIDValueCallback callback, void * context, IOOptionBits options); \ 219 IOReturn (*setInputReportCallback)(void * self, uint8_t * report, CFIndex reportLength, IOHIDReportCallback callback, void * context, IOOptionBits options); \ 220 IOReturn (*setReport)(void * self, IOHIDReportType reportType, uint32_t reportID, const uint8_t * report, CFIndex reportLength, uint32_t timeout, IOHIDReportCallback callback, void * context, IOOptionBits options); \ 221 IOReturn (*getReport)(void * self, IOHIDReportType reportType, uint32_t reportID, uint8_t * report, CFIndex * pReportLength, uint32_t timeout, IOHIDReportCallback callback, void * context, IOOptionBits options) 222/*! @interface IOHIDDeviceDeviceInterface 223 @abstract The object you use to access HID devices from user space, returned by version 1.5 of the IOHIDFamily. 224 @discussion The functions listed here will work with any version of the IOHIDDeviceDeviceInterface. 225 226 <b>Note:</b> Please note that methods declared in this interface follow the copy/get/set conventions. 227*/ 228typedef struct IOHIDDeviceDeviceInterface { 229 IUNKNOWN_C_GUTS; 230#ifdef IOHID_DEVICE_DEVICE_FUNCS_V1 // { 231 IOHID_DEVICE_DEVICE_FUNCS_V1; 232#else // } { 233 /*! @function open 234 @abstract Opens the IOHIDDevice. 235 @discussion Before the client can issue commands that change the state of the device, it must have succeeded in 236 opening the device. This establishes a link between the client's task and the actual device. To 237 establish an exclusive link use the kIOHIDOptionsTypeSeizeDevice option. 238 @param self Pointer to the IOHIDDeviceDeviceInterface. 239 @param options Option bits to be passed down to the user client. 240 @result Returns kIOReturnSuccess if successful, some other mach error if the connection is no longer valid. 241 */ 242 IOReturn (*open)(void * self, IOOptionBits options); 243 244 /*! @function close 245 @abstract Closes the task's connection to the IOHIDDevice. 246 @discussion Releases the client's access to the IOHIDDevice. 247 @param self Pointer to the IOHIDDeviceDeviceInterface. 248 @param options Option bits to be passed down to the user client. 249 @result Returns kIOReturnSuccess if successful, kIOReturnNoDevice if there is no connection to an IOService. 250 */ 251 IOReturn (*close)(void * self, IOOptionBits options); 252 253 /*! @function getProperty 254 @abstract Obtains a property related to the IOHIDDevice. 255 @discussion Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h. 256 @param self Pointer to the IOHIDDeviceDeviceInterface. 257 @param key CFStringRef key 258 @param pProperty Pointer to a CFTypeRef property. 259 @result Returns kIOReturnSuccess if successful. 260 */ 261 IOReturn (*getProperty)(void * self, CFStringRef key, CFTypeRef * pProperty); 262 263 /*! @function setProperty 264 @abstract Sets a property related to the IOHIDDevice. 265 @discussion Property keys are prefixed by kIOHIDDevice and declared in IOHIDKeys.h. 266 @param self Pointer to the IOHIDDeviceDeviceInterface. 267 @param key CFStringRef key 268 @param property CFTypeRef property. 269 @result Returns kIOReturnSuccess if successful. 270 */ 271 IOReturn (*setProperty)(void * self, CFStringRef key, CFTypeRef property); 272 273 /*! @function getAsyncEventSource 274 @abstract Obtains the event source for this IOHIDDeviceDeviceInterface instance. 275 @discussion The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef. 276 @param self Pointer to the IOHIDDeviceDeviceInterface. 277 @param pSource Pointer to a CFType to return the run loop event source. 278 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 279 */ 280 IOReturn (*getAsyncEventSource)(void * self, CFTypeRef * pSource); 281 282 /*! @function copyMatchingElements 283 @abstract Obtains a CFArrayRef containing the IOHIDDeviceDeviceInterface elements that match 284 the passed matching dictionary. 285 @discussion Objects contained in the returned array are of type IOHIDElementRef. Please see 286 IOHIDElement.h for additional API information. Elemenet properties are prefixed by 287 kIOHIDElement and declared in IOHIDKeys.h. 288 @param self Pointer to the IOHIDDeviceDeviceInterface. 289 @param matchingDict CFDictionaryRef containing the element properties to match on. 290 @param pElements CFArrayRef containing matched elements. 291 @param options Reserved for future use. Ignored in current implementation. Set to zero. 292 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 293 */ 294 IOReturn (*copyMatchingElements)(void * self, CFDictionaryRef matchingDict, CFArrayRef * pElements, IOOptionBits options); 295 296 /*! @function setValue 297 @abstract Sets the value for an element. 298 @discussion If setting multiple element values, please consider using an IOHIDDeviceTransactionInterface 299 with the kIOHIDTransactionDirectionTypeOutput direction. 300 <br> 301 <b>Note:</b> In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource 302 must be added to a run loop. 303 @param self Pointer to the IOHIDDeviceDeviceInterface. 304 @param element IOHIDElementRef referencing the element of interest. 305 @param value IOHIDValueRef containing element value to be set. 306 @param timeout Time in milliseconds to wait before aborting request. 307 @param callback Callback of type IOHIDValueCallback to be used after report data has been sent to the device. 308 If null, this method will behave synchronously. 309 @param context Pointer to data to be passed to the callback. 310 @param options Reserved for future use. Ignored in current implementation. Set to zero. 311 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 312 */ 313 IOReturn (*setValue)(void * self, IOHIDElementRef element, IOHIDValueRef value, 314 uint32_t timeout, IOHIDValueCallback callback, void * context, IOOptionBits options); 315 316 /*! @function getValue 317 @abstract Obtains the current value for an element. 318 @discussion If an element of type kIOHIDElementTypeFeature is passed, this method will issue a request to the IOHIDDevice. 319 Otherwise, this will return the last value reported by the IOHIDDevice. If requesting multiple feature element 320 values, please consider using an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction. 321 <br> 322 <b>Note:</b> In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource 323 must be added to a run loop. 324 @param self Pointer to the IOHIDDeviceDeviceInterface. 325 @param element IOHIDElementRef referencing the element of interest. 326 @param pValue Pointer to a IOHIDValueRef to return the element value. 327 @param timeout Time in milliseconds to wait before aborting request. 328 @param callback Callback of type IOHIDReportCallback to be used when element value has been received from the device. 329 If null, this method will behave synchronously. 330 @param context Pointer to data to be passed to the callback. 331 @param options Reserved for future use. Ignored in current implementation. Set to zero. 332 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 333 */ 334 IOReturn (*getValue)(void * self, IOHIDElementRef element, IOHIDValueRef * pValue, 335 uint32_t timeout, IOHIDValueCallback callback, void * context, IOOptionBits options); 336 337 /*! 338 @function setInputReportCallback 339 @abstract Sets the input report callback to be used when data is received from the Input pipe. 340 @discussion In order to function properly, the event source obtained using getAsyncEventSource must be added to a run loop. 341 @param self Pointer to the IOHIDDeviceDeviceInterface. 342 @param report Pointer to a pre-allocated buffer to be filled and passed back via the callback. 343 @param reportLength Length of the report buffer. 344 @param callback Callback of type IOHIDReportCallback to be used when report data has been receieved by the IOHIDDevice. 345 @param context Pointer to data to be passed to the callback. 346 @param options Reserved for future use. Ignored in current implementation. Set to zero. 347 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 348 */ 349 IOReturn (*setInputReportCallback)(void * self, uint8_t * report, CFIndex reportLength, 350 IOHIDReportCallback callback, void * context, IOOptionBits options); 351 352 /*! @function setReport 353 @abstract Sends a report of type kIOHIDReportTypeOutput or kIOHIDReportTypeFeature to the IOHIDDevice. 354 @discussion This method is useful if specific knowledge of the unparsed report is known to the caller. Otherwise, using 355 an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeOutput direction is recommended. 356 <br> 357 <b>Note:</b> In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource 358 must be added to a run loop. 359 @param self Pointer to the IOHIDDeviceDeviceInterface. 360 @param reportType The report type. 361 @param reportID The report id. 362 @param report Pointer to a buffer containing the report data to be sent. 363 @param reportLength Length of the report buffer. 364 @param timeout Timeout in milliseconds for issuing the setReport. 365 @param callback Callback of type IOHIDReportCallback to be used after report data has been sent to the device. 366 If null, this method will behave synchronously. 367 @param context Pointer to data to be passed to the callback. 368 @param options Reserved for future use. Ignored in current implementation. Set to zero. 369 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 370 */ 371 IOReturn (*setReport)(void * self, IOHIDReportType reportType, uint32_t reportID, const uint8_t * report, CFIndex reportLength, 372 uint32_t timeout, IOHIDReportCallback callback, void * context, IOOptionBits options); 373 374 /*! @function getReport 375 @abstract Obtains a report of type kIOHIDReportTypeInput or kIOHIDReportTypeFeature from the IOHIDDevice. 376 @discussion This method is useful if specific knowledge of the unparsed report is known to the caller. Otherwise, using 377 an IOHIDDeviceTransactionInterface with the kIOHIDTransactionDirectionTypeInput direction is recommended. 378 <br> 379 <b>Note:</b> In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource 380 must be added to a run loop. 381 @param self Pointer to the IOHIDDeviceDeviceInterface. 382 @param reportType The report type. 383 @param reportID The report id. 384 @param report Pointer to a pre-allocated buffer to be filled. 385 @param pReportLength Length of the report buffer. When finished, this will contain the actual length of the report. 386 @param timeout Timeout in milliseconds for issuing the getReport. 387 @param callback Callback of type IOHIDReportCallback to be used when report data has been received from the device. 388 If null, this method will behave synchronously. 389 @param context Pointer to data to be passed to the callback. 390 @param options Reserved for future use. Ignored in current implementation. Set to zero. 391 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 392 */ 393 IOReturn (*getReport)(void * self, IOHIDReportType reportType, uint32_t reportID, uint8_t * report, CFIndex * pReportLength, 394 uint32_t timeout, IOHIDReportCallback callback, void * context, IOOptionBits options); 395#endif // } 396} IOHIDDeviceDeviceInterface; 397 398#define IOHID_DEVICE_DEVICE_FUNCS_V2 \ 399 IOReturn (*setInputReportWithTimeStampCallback)(void * self, uint8_t * report, CFIndex reportLength, IOHIDReportWithTimeStampCallback callback, void * context, IOOptionBits options) 400/*! @interface IOHIDDeviceTimeStampedDeviceInterface 401 @abstract The object you use to access HID devices from user space, returned by version 2.1 of the IOHIDFamily. 402 @discussion The functions listed here include all of the functions from the IOHIDDeviceDeviceInterface. 403 404 <b>Note:</b> Please note that methods declared in this interface follow the copy/get/set conventions. 405*/ 406typedef struct IOHIDDeviceTimeStampedDeviceInterface { 407 IUNKNOWN_C_GUTS; 408 IOHID_DEVICE_DEVICE_FUNCS_V1; 409#ifdef IOHID_DEVICE_DEVICE_FUNCS_V2 // { 410 IOHID_DEVICE_DEVICE_FUNCS_V2; 411#else // } { 412/*! 413 @function setInputReportWithTimeStampCallback 414 @abstract Sets the input report callback to be used when data is received from the Input pipe. 415 @discussion In order to function properly, the event source obtained using getAsyncEventSource must be added to a run loop. 416 @param self Pointer to the IOHIDDeviceDeviceInterface. 417 @param report Pointer to a pre-allocated buffer to be filled and passed back via the callback. 418 @param reportLength Length of the report buffer. 419 @param callback Callback of type IOHIDReportWithTimeStampCallback to be used when report data has been receieved by the IOHIDDevice. 420 @param context Pointer to data to be passed to the callback. 421 @param options Reserved for future use. Ignored in current implementation. Set to zero. 422 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 423*/ 424IOReturn (*setInputReportWithTimeStampCallback)(void * self, uint8_t * report, CFIndex reportLength, 425 IOHIDReportWithTimeStampCallback callback, void * context, IOOptionBits options); 426 427#endif // } 428} IOHIDDeviceTimeStampedDeviceInterface; 429 430/*! 431 @interface IOHIDDeviceQueueInterface 432 @abstract The object you use to access a HID queue from user space, returned by version 1.5 of the IOHIDFamily. 433 @discussion The functions listed here will work with any version of the IOHIDDeviceQueueInterface. This behavior is useful when you 434 need to keep track of all values of an input element, rather than just the most recent one. 435 <br> 436 <b>Note:</b>Absolute element values (based on a fixed origin) will only be placed on a queue if there is a change in value. 437*/ 438typedef struct IOHIDDeviceQueueInterface { 439 IUNKNOWN_C_GUTS; 440 441 /*! @function getAsyncEventSource 442 @abstract Obtains the event source for this IOHIDDeviceQueueInterface instance. 443 @discussion The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef. 444 @param self Pointer to the IOHIDDeviceQueueInterface. 445 @param pSource Pointer to a CFType to return the run loop event source. 446 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 447 */ 448 IOReturn (*getAsyncEventSource)(void * self, CFTypeRef * pSource); 449 450 /*! @function setDepth 451 @abstract Sets the depth for this IOHIDDeviceQueueInterface instance. 452 @discussion Regardless of element value size, queue will guarantee n=depth elements will be serviced. 453 @param self Pointer to the IOHIDDeviceTransactionInterface. 454 @param depth The maximum number of elements in the queue before the oldest elements in the queue begin to be lost. 455 @param options Reserved for future use. Ignored in current implementation. Set to zero. 456 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 457 */ 458 IOReturn (*setDepth)(void *self, uint32_t depth, IOOptionBits options); 459 460 /*! @function getDepth 461 @abstract Obtains the queue depth for this IOHIDDeviceQueueInterface instance. 462 @param self Pointer to the IOHIDDeviceQueueInterface. 463 @param pDepth Pointer to a uint32_t to obtain the number of elements that can be serviced by the queue. 464 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 465 */ 466 IOReturn (*getDepth)(void *self, uint32_t * pDepth); 467 468 /*! @function addElement 469 @abstract Adds an element to this IOHIDDeviceQueueInterface instance. 470 @param self Pointer to the IOHIDDeviceQueueInterface. 471 @param element IOHIDElementRef referencing the element to be added to the queue. 472 @param options Reserved for future use. Ignored in current implementation. Set to zero. 473 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 474 */ 475 IOReturn (*addElement)(void * self, IOHIDElementRef element, IOOptionBits options); 476 477 /*! @function removeElement 478 @abstract Removes an element from this IOHIDDeviceQueueInterface instance. 479 @param self Pointer to the IOHIDDeviceQueueInterface. 480 @param element IOHIDElementRef referencing the element to be removed from the queue. 481 @param options Reserved for future use. Ignored in current implementation. Set to zero. 482 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 483 */ 484 IOReturn (*removeElement)(void * self, IOHIDElementRef element, IOOptionBits options); 485 486 /*! @function containsElement 487 @abstract Determines whether an element has been added to this IOHIDDeviceQueueInterface instance. 488 @param self Pointer to the IOHIDDeviceQueueInterface. 489 @param element IOHIDElementRef referencing the element to be be found in the queue. 490 @param pValue Pointer to a Boolean to return whether or not the element was found in the queue. 491 @param options Reserved for future use. Ignored in current implementation. Set to zero. 492 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 493 */ 494 IOReturn (*containsElement)(void * self, IOHIDElementRef element, Boolean * pValue, IOOptionBits options); 495 496 /*! @function start 497 @abstract Starts element value delivery to the queue. 498 @param self Pointer to the IOHIDDeviceQueueInterface. 499 @param options Reserved for future use. Ignored in current implementation. Set to zero. 500 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 501 */ 502 IOReturn (*start)(void * self, IOOptionBits options); 503 504 /*! @function stop 505 @abstract Stops element value delivery to the queue. 506 @param self Pointer to the IOHIDDeviceQueueInterface. 507 @param options Reserved for future use. Ignored in current implementation. Set to zero. 508 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 509 */ 510 IOReturn (*stop)(void * self, IOOptionBits options); 511 512 /*! @function setValueAvailableCallback 513 @abstract Sets callback to be used when the queue transitions to non-empty. 514 @discussion In order to make use of asynchronous behavior, the event source obtained using getAsyncEventSource 515 must be added to a run loop. 516 @param self Pointer to the IOHIDDeviceQueueInterface. 517 @param callback Callback of type IOHIDCallback to be used when data is placed on the queue. 518 @param context Pointer to data to be passed to the callback. 519 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 520 */ 521 IOReturn (*setValueAvailableCallback)(void * self, IOHIDCallback callback, void * context); 522 523 /*! @function copyNextValue 524 @abstract Dequeues a retained copy of an element value from the head of an IOHIDDeviceQueueInterface. 525 @discussion Because the value is a retained copy, it is up to the caller to release the value using CFRelease. 526 Use with setValueCallback to avoid polling the queue for data. 527 @param self Pointer to the IOHIDDeviceQueueInterface. 528 @param pValue Pointer to a IOHIDValueRef to return the value at the head of the queue. 529 @param timeout Timeout in milliseconds before aborting an attempt to dequeue a value from the head of a queue. 530 @param options Reserved for future use. Ignored in current implementation. Set to zero. 531 @result Returns kIOReturnSuccess if successful, kIOReturnUnderrun if data is unavailble, or a kern_return_t if unsuccessful. 532 */ 533 IOReturn (*copyNextValue)(void * self, IOHIDValueRef * pValue, uint32_t timeout, IOOptionBits options); 534} IOHIDDeviceQueueInterface; 535 536 537/*! 538 @interface IOHIDDeviceTransactionInterface 539 @abstract The object you use to access a HID transaction from user space, returned by version 1.5 of the IOHIDFamily. 540 @discussion The functions listed here will work with any version of the IOHIDDeviceTransactionInterface. This functionality 541 is useful when either setting or getting the values for multiple parsed elements. 542*/ 543typedef struct IOHIDDeviceTransactionInterface { 544 IUNKNOWN_C_GUTS; 545 546 /*! @function getAsyncEventSource 547 @abstract Obtains the event source for this IOHIDDeviceTransactionInterface instance. 548 @discussion The returned event source can be of type CFRunLoopSourceRef or CFRunLoopTimerRef. 549 @param self Pointer to the IOHIDDeviceTransactionInterface. 550 @param pSource Pointer to a CFType to return the run loop event source. 551 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 552 */ 553 IOReturn (*getAsyncEventSource)(void * self, CFTypeRef * pSource); 554 555 /*! @function setDirection 556 @abstract Sets the direction for this IOHIDDeviceTransactionInterface instance. 557 @discussion Direction constants are declared in IOHIDTransactionDirectionType. Changing directions 558 is useful when dealing with elements of type kIOHIDElementTypeFeature as you use the 559 transaction to both set and get element values. 560 @param self Pointer to the IOHIDDeviceTransactionInterface. 561 @param direction Transaction direction of type IOHIDTransactionDirectionType. 562 @param options Reserved for future use. Ignored in current implementation. Set to zero. 563 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 564 */ 565 IOReturn (*setDirection)(void * self, IOHIDTransactionDirectionType direction, IOOptionBits options); 566 567 /*! @function getDirection 568 @abstract Obtains the direction for this IOHIDDeviceTransactionInterface instance. 569 @discussion Direction constants are declared in IOHIDTransactionDirectionType. 570 @param self Pointer to the IOHIDDeviceTransactionInterface. 571 @param pDirection Pointer to a IOHIDTransactionDirectionType to obtain transaction direction. 572 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 573 */ 574 IOReturn (*getDirection)(void * self, IOHIDTransactionDirectionType * pDirection); 575 576 /*! @function addElement 577 @abstract Adds an element to this IOHIDDeviceTransactionInterface instance. 578 @param self Pointer to the IOHIDDeviceTransactionInterface. 579 @param element IOHIDElementRef referencing the element to be added to the transaction. 580 @param options Reserved for future use. Ignored in current implementation. Set to zero. 581 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 582 */ 583 IOReturn (*addElement)(void * self, IOHIDElementRef element, IOOptionBits options); 584 585 /*! @function removeElement 586 @abstract Removes an element from this IOHIDDeviceTransactionInterface instance. 587 @param self Pointer to the IOHIDDeviceTransactionInterface. 588 @param element IOHIDElementRef referencing the element to be removed from the transaction. 589 @param options Reserved for future use. Ignored in current implementation. Set to zero. 590 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 591 */ 592 IOReturn (*removeElement)(void * self, IOHIDElementRef element, IOOptionBits options); 593 594 /*! @function containsElement 595 @abstract Checks whether an element has been added to this IOHIDDeviceTransactionInterface instance. 596 @param self Pointer to the IOHIDDeviceTransactionInterface. 597 @param element IOHIDElementRef referencing the element to be be found in the transaction. 598 @param pValue Pointer to a Boolean to return whether or not the element was found in the transaction. 599 @param options Reserved for future use. Ignored in current implementation. Set to zero. 600 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 601 */ 602 IOReturn (*containsElement)(void * self, IOHIDElementRef element, Boolean * pValue, IOOptionBits options); 603 604 /*! @function setValue 605 @abstract Sets the transaction value for an element in this IOHIDDeviceTransactionInterface instance. 606 @discussion This method is intended for use with transaction of direction kIOHIDTransactionDirectionTypeOutput. 607 Use the kIOHIDTransactionOptionDefaultOutputValue option to set the default element value. 608 @param self Pointer to the IOHIDDeviceTransactionInterface. 609 @param element IOHIDElementRef referencing the element of interest. 610 @param value IOHIDValueRef referencing element value to be used in the transaction. 611 @param options See IOHIDTransactionOption. 612 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 613 */ 614 IOReturn (*setValue)(void * self, IOHIDElementRef element, IOHIDValueRef value, IOOptionBits options); 615 616 /*! @function getValue 617 @abstract Obtains the transaction value for an element in this IOHIDDeviceTransactionInterface instance. 618 @discussion Use the kIOHIDTransactionOptionDefaultOutputValue option to get the default element value. 619 @param self Pointer to the IOHIDDeviceTransactionInterface. 620 @param element IOHIDElementRef referencing the element of interest. 621 @param pValue Pointer to an IOHIDValueRef to return the element value of the transaction. 622 @param options See IOHIDTransactionOption. 623 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 624 */ 625 IOReturn (*getValue)(void * self, IOHIDElementRef element, IOHIDValueRef *pValue, IOOptionBits options); 626 627 /*! @function commit 628 @abstract Commits element transaction to an IOHIDDevice in this IOHIDDeviceTransactionInterface instance. 629 @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be used if 630 element values are not set. If neither are set, that element will be omitted from the commit. After 631 a transaction is committed, transaction element values will be cleared and default values preserved. 632 <br> 633 <b>Note:</b> It is possible for elements from different reports to be present in a given transaction 634 causing a commit to transcend multiple reports. Keep this in mind when setting a timeout. 635 @param self Pointer to the IOHIDDeviceTransactionInterface. 636 @param timeout Timeout in milliseconds for issuing the transaction. 637 @param callback Callback of type IOHIDCallback to be used when transaction has been completed. If null, 638 this method will behave synchronously. 639 @param context Pointer to data to be passed to the callback. 640 @param options Reserved for future use. Ignored in current implementation. Set to zero. 641 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 642 */ 643 IOReturn (*commit)(void * self, uint32_t timeout, IOHIDCallback callback, void * context, IOOptionBits options); 644 645 /*! @function clear 646 @abstract Clears element transaction values for an IOHIDDeviceTransactionInterface. 647 @discussion In regards to kIOHIDTransactionDirectionTypeOutput direction, default element values will be preserved. 648 @param self Pointer to the IOHIDDeviceTransactionInterface. 649 @param options Reserved for future use. Ignored in current implementation. Set to zero. 650 @result Returns kIOReturnSuccess if successful or a kern_return_t if unsuccessful. 651 */ 652 IOReturn (*clear)(void * self, IOOptionBits options); 653} IOHIDDeviceTransactionInterface; 654 655__END_DECLS 656 657#endif /* _IOKIT_HID_IOHIDDEVICEPLUGIN_H */ 658