src/joystick/darwin/10.3.9-FIX/IOHIDLib.h

   1 /* *INDENT-OFF* */
   2 /*
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _IOKIT_HID_IOHIDLIB_H_
  27 #define _IOKIT_HID_IOHIDLIB_H_
  28
  29 #include <sys/cdefs.h>
  30
  31 __BEGIN_DECLS
  32 #include <CoreFoundation/CoreFoundation.h>
  33 #if COREFOUNDATION_CFPLUGINCOM_SEPARATE
  34 #include <CoreFoundation/CFPlugInCOM.h>
  35 #endif
  36
  37 #include <IOKit/IOTypes.h>
  38 #include <IOKit/IOReturn.h>
  39
  40 #include <IOKit/hid/IOHIDKeys.h>
  41
  42 struct IOHIDEventStruct
  43 {
  44     IOHIDElementType    type;
  45     IOHIDElementCookie  elementCookie;
  46     SInt32              value;
  47     AbsoluteTime        timestamp;
  48     UInt32              longValueSize;
  49     void *              longValue;
  50 };
  51 typedef struct IOHIDEventStruct IOHIDEventStruct;
  52
  53 /* FA12FA38-6F1A-11D4-BA0C-0005028F18D5 */
  54 #define kIOHIDDeviceUserClientTypeID CFUUIDGetConstantUUIDWithBytes(NULL, \
  55     0xFA, 0x12, 0xFA, 0x38, 0x6F, 0x1A, 0x11, 0xD4,                     \
  56     0xBA, 0x0C, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)
  57
  58 /* 13AA9C44-6F1B-11D4-907C-0005028F18D5 */
  59 #define kIOHIDDeviceFactoryID CFUUIDGetConstantUUIDWithBytes(NULL,      \
  60     0x13, 0xAA, 0x9C, 0x44, 0x6F, 0x1B, 0x11, 0xD4,                     \
  61     0x90, 0x7C, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)
  62
  63 /* 78BD420C-6F14-11D4-9474-0005028F18D5 */
  64 /*! @defined kIOHIDDeviceInterfaceID
  65     @discussion Interface ID for the IOHIDDeviceInterface. Corresponds to an
  66                  available HID device. */
  67 #define kIOHIDDeviceInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL,    \
  68     0x78, 0xBD, 0x42, 0x0C, 0x6F, 0x14, 0x11, 0xD4,                     \
  69     0x94, 0x74, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)
  70
  71 /* 7D0B510E-16D5-11D7-9E9B-000393992E38 */
  72 /*! @defined kIOHIDDeviceInterfaceID121
  73     @discussion Interface ID for the IOHIDDeviceInterface121. Corresponds to
  74                 an available HID device that includes methods from
  75                 IOHIDDeviceInterface.  This interface is available on
  76                 IOHIDLib 1.2.1 and Mac OS X 10.2.3 or later.*/
  77 #define kIOHIDDeviceInterfaceID121 CFUUIDGetConstantUUIDWithBytes(NULL, \
  78     0x7d, 0xb, 0x51, 0xe, 0x16, 0xd5, 0x11, 0xd7,                       \
  79     0x9e, 0x9b, 0x0, 0x3, 0x93, 0x99, 0x2e, 0x38)
  80
  81 /* B70ABF31-16D5-11D7-AB35-000393992E38 */
  82 /*! @defined kIOHIDDeviceInterfaceID122
  83     @discussion Interface ID for the IOHIDDeviceInterface122. Corresponds to
  84                 an available HID device that includes methods from
  85                 IOHIDDeviceInterface and IOHIDDeviceInterface121. This
  86                 interface is available on IOHIDLib 1.2.2 and Mac OS X 10.3
  87                 or later.*/
  88 #define kIOHIDDeviceInterfaceID122 CFUUIDGetConstantUUIDWithBytes(NULL, \
  89     0xb7, 0xa, 0xbf, 0x31, 0x16, 0xd5, 0x11, 0xd7,                      \
  90     0xab, 0x35, 0x0, 0x3, 0x93, 0x99, 0x2e, 0x38)
  91
  92 /* 8138629E-6F14-11D4-970E-0005028F18D5 */
  93 /*! @defined kIOHIDQueueInterfaceID
  94     @discussion Interface ID for the kIOHIDQueueInterfaceID. Corresponds to a
  95                 queue for a specific HID device. */
  96 #define kIOHIDQueueInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL,     \
  97     0x81, 0x38, 0x62, 0x9E, 0x6F, 0x14, 0x11, 0xD4,                     \
  98     0x97, 0x0E, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)
  99
 100 /* 80CDCC00-755D-11D4-8E0F-0005028F18D5 */
 101 /*! @defined kIOHIDOutputTransactionInterfaceID
 102     @discussion Interface ID for the kIOHIDOutputTransactionInterfaceID.
 103                 Corresponds to an output transaction for one or more report IDs
 104                 on a specific device. */
 105 #define kIOHIDOutputTransactionInterfaceID CFUUIDGetConstantUUIDWithBytes(NULL,\
 106     0x80, 0xCD, 0xCC, 0x00, 0x75, 0x5D, 0x11, 0xD4,                     \
 107     0x80, 0xEF, 0x00, 0x05, 0x02, 0x8F, 0x18, 0xD5)
 108
 109 /*! @typedef IOHIDCallbackFunction
 110     @discussion Type and arguments of callout C function that is used when a
 111                 completion routine is called, see
 112                 IOHIDLib.h:setRemovalCallback().
 113     @param target void * pointer to your data, often a pointer to an object.
 114     @param result Completion result of desired operation.
 115     @param refcon void * pointer to more data.
 116     @param sender Interface instance sending the completion routine.
 117 */
 118 typedef void (*IOHIDCallbackFunction)
 119               (void * target, IOReturn result, void * refcon, void * sender);
 120
 121 /*! @typedef IOHIDElementCallbackFunction
 122     @discussion Type and arguments of callout C function that is used when a
 123                 completion routine is called, see IOHIDLib.h:setElementValue().
 124     @param target void * pointer to your data, often a pointer to an object.
 125     @param result Completion result of desired operation.
 126     @param refcon void * pointer to more data.
 127     @param sender Interface instance sending the completion routine.
 128     @param elementCookie Element within interface instance sending completion.
 129 */
 130 typedef void (*IOHIDElementCallbackFunction)
 131               (void *                   target,
 132                IOReturn                 result,
 133                void *                   refcon,
 134                void *                   sender,
 135                IOHIDElementCookie       elementCookie);
 136
 137 /*! @typedef IOHIDReportCallbackFunction
 138     @discussion Type and arguments of callout C function that is used when a
 139                 completion routine is called, see IOHIDLib.h:setReport().
 140     @param target void * pointer to your data, often a pointer to an object.
 141     @param result Completion result of desired operation.
 142     @param refcon void * pointer to more data.
 143     @param sender Interface instance sending the completion routine.
 144     @param bufferSize Size of the buffer received upon completion.
 145 */
 146 typedef void (*IOHIDReportCallbackFunction)
 147               (void *                   target,
 148                IOReturn                 result,
 149                void *                   refcon,
 150                void *                   sender,
 151                UInt32                   bufferSize);
 152
 153
 154 /* Forward declarations of the queue and output transaction interfaces */
 155 struct IOHIDQueueInterface;
 156 struct IOHIDOutputTransactionInterface;
 157 typedef struct IOHIDQueueInterface IOHIDQueueInterface;
 158 typedef struct IOHIDOutputTransactionInterface IOHIDOutputTransactionInterface;
 159
 160 //
 161 // IOHIDDeviceInterface Functions available in version 1.0 (10.0) and higher of Mac OS X
 162 //
 163 #define IOHIDDEVICEINTERFACE_FUNCS_100                                                  \
 164     IOReturn (*createAsyncEventSource)(void * self, CFRunLoopSourceRef * source);       \
 165     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);                             \
 166     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);                       \
 167     mach_port_t (*getAsyncPort)(void * self);                                           \
 168     IOReturn (*open)(void * self, UInt32 flags);                                        \
 169     IOReturn (*close)(void * self);                                                     \
 170     IOReturn (*setRemovalCallback)(void * self, IOHIDCallbackFunction removalCallback,  \
 171                                    void * removalTarget, void * removalRefcon);         \
 172     IOReturn (*getElementValue)(void * self, IOHIDElementCookie elementCookie,          \
 173                                 IOHIDEventStruct * valueEvent);                         \
 174     IOReturn (*setElementValue)(void * self, IOHIDElementCookie elementCookie,          \
 175                                 IOHIDEventStruct * valueEvent, UInt32 timeoutMS,        \
 176                                 IOHIDElementCallbackFunction callback,                  \
 177                                 void * callbackTarget, void * callbackRefcon);          \
 178     IOReturn (*queryElementValue)(void * self, IOHIDElementCookie elementCookie,        \
 179                                 IOHIDEventStruct * valueEvent, UInt32 timeoutMS,        \
 180                                 IOHIDElementCallbackFunction callback,                  \
 181                                 void * callbackTarget, void * callbackRefcon);          \
 182     IOReturn (*startAllQueues)(void * self);                                            \
 183     IOReturn (*stopAllQueues)(void * self);                                             \
 184     IOHIDQueueInterface ** (*allocQueue) (void *self);                                  \
 185     IOHIDOutputTransactionInterface ** (*allocOutputTransaction) (void *self)
 186
 187 //
 188 // IOHIDDeviceInterface Functions available in version 1.2.1 (10.2.3) and higher of Mac OS X
 189 //
 190 #define IOHIDDEVICEINTERFACE_FUNCS_121                                                  \
 191     IOReturn (*setReport)(void * self, IOHIDReportType reportType, UInt32 reportID,     \
 192                                 void * reportBuffer, UInt32 reportBufferSize,           \
 193                                 UInt32 timeoutMS, IOHIDReportCallbackFunction callback, \
 194                                 void * callbackTarget, void * callbackRefcon);          \
 195     IOReturn (*getReport)(void * self, IOHIDReportType reportType,                      \
 196                                 UInt32 reportID, void * reportBuffer,                   \
 197                                 UInt32 * reportBufferSize, UInt32 timeoutMS,            \
 198                                 IOHIDReportCallbackFunction callback,                   \
 199                                 void * callbackTarget, void * callbackRefcon)
 200
 201 //
 202 // IOHIDDeviceInterface Functions available in version 1.2.2 (10.3) and higher of Mac OS X
 203 //
 204 #define IOHIDDEVICEINTERFACE_FUNCS_122                                                  \
 205     IOReturn (*copyMatchingElements)(void * self, CFDictionaryRef matchingDict,         \
 206                                 CFArrayRef * elements);                                 \
 207     IOReturn (*setInterruptReportHandlerCallback)(void * self, void * reportBuffer,             \
 208                                 UInt32 reportBufferSize,                                \
 209                                 IOHIDReportCallbackFunction callback,                   \
 210                                 void * callbackTarget, void * callbackRefcon)
 211
 212 typedef struct IOHIDDeviceInterface
 213 {
 214     IUNKNOWN_C_GUTS;
 215     IOHIDDEVICEINTERFACE_FUNCS_100;
 216     IOHIDDEVICEINTERFACE_FUNCS_121;
 217 } IOHIDDeviceInterface;
 218
 219 typedef struct IOHIDDeviceInterface121
 220 {
 221     IUNKNOWN_C_GUTS;
 222     IOHIDDEVICEINTERFACE_FUNCS_100;
 223     IOHIDDEVICEINTERFACE_FUNCS_121;
 224 } IOHIDDeviceInterface121;
 225
 226 typedef struct IOHIDDeviceInterface122
 227 {
 228     IUNKNOWN_C_GUTS;
 229     IOHIDDEVICEINTERFACE_FUNCS_100;
 230     IOHIDDEVICEINTERFACE_FUNCS_121;
 231     IOHIDDEVICEINTERFACE_FUNCS_122;
 232 } IOHIDDeviceInterface122;
 233
 234
 235 //
 236 // IOHIDQueueInterface Functions available in version 1.0 (10.0) and higher of Mac OS X
 237 //
 238 #define IOHIDQUEUEINTERFACE_FUNCS_100                                                   \
 239     IOReturn (*createAsyncEventSource)(void * self, CFRunLoopSourceRef * source);       \
 240     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);                             \
 241     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);                       \
 242     mach_port_t (*getAsyncPort)(void * self);                                           \
 243     IOReturn (*create)(void * self, UInt32 flags, UInt32 depth);                        \
 244     IOReturn (*dispose)(void * self);                                                   \
 245     IOReturn (*addElement)(void * self, IOHIDElementCookie elementCookie, UInt32 flags);\
 246     IOReturn (*removeElement)(void * self, IOHIDElementCookie elementCookie);           \
 247     Boolean (*hasElement)(void * self, IOHIDElementCookie elementCookie);               \
 248     IOReturn (*start)(void * self);                                                     \
 249     IOReturn (*stop)(void * self);                                                      \
 250     IOReturn (*getNextEvent)(void * self, IOHIDEventStruct * event,                     \
 251                                 AbsoluteTime maxTime, UInt32 timeoutMS);                \
 252     IOReturn (*setEventCallout)(void * self, IOHIDCallbackFunction callback,            \
 253                                 void * callbackTarget,  void * callbackRefcon);         \
 254     IOReturn (*getEventCallout)(void * self, IOHIDCallbackFunction * outCallback,       \
 255                                 void ** outCallbackTarget, void ** outCallbackRefcon)
 256
 257 struct IOHIDQueueInterface
 258 {
 259     IUNKNOWN_C_GUTS;
 260     IOHIDQUEUEINTERFACE_FUNCS_100;
 261 };
 262
 263 //
 264 // IOHIDOutputTransactionInterface Functions available in version 1.2 (10.2) and higher of Mac OS X
 265 //
 266 #define IOHIDOUTPUTTRANSACTIONINTERFACE_FUNCS_120                                       \
 267     IOReturn (*createAsyncEventSource)(void * self, CFRunLoopSourceRef * source);       \
 268     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);                             \
 269     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);                       \
 270     mach_port_t (*getAsyncPort)(void * self);                                           \
 271     IOReturn (*create)(void * self);                                                    \
 272     IOReturn (*dispose)(void * self);                                                   \
 273     IOReturn (*addElement)(void * self, IOHIDElementCookie elementCookie);              \
 274     IOReturn (*removeElement)(void * self, IOHIDElementCookie elementCookie);           \
 275     Boolean  (*hasElement)(void * self, IOHIDElementCookie elementCookie);              \
 276     IOReturn (*setElementDefault)(void *self, IOHIDElementCookie elementCookie,         \
 277                                 IOHIDEventStruct * valueEvent);                         \
 278     IOReturn (*getElementDefault)(void * self, IOHIDElementCookie elementCookie,        \
 279                                 IOHIDEventStruct * outValueEvent);                      \
 280     IOReturn (*setElementValue)(void * self, IOHIDElementCookie elementCookie,          \
 281                                 IOHIDEventStruct * valueEvent);                         \
 282     IOReturn (*getElementValue)(void * self, IOHIDElementCookie elementCookie,          \
 283                                 IOHIDEventStruct * outValueEvent);                      \
 284     IOReturn (*commit)(void * self, UInt32 timeoutMS, IOHIDCallbackFunction callback,   \
 285                                 void * callbackTarget, void * callbackRefcon);          \
 286     IOReturn (*clear)(void * self)
 287
 288 struct IOHIDOutputTransactionInterface
 289 {
 290     IUNKNOWN_C_GUTS;
 291     IOHIDOUTPUTTRANSACTIONINTERFACE_FUNCS_120;
 292 };
 293
 294
 295 //
 296 //  BEGIN READABLE STRUCTURE DEFINITIONS
 297 //
 298 //  This portion of uncompiled code provides a more reader friendly representation of
 299 //  the CFPlugin methods defined above.
 300
 301 #if 0
 302 /*! @class IOHIDDeviceInterface
 303     @discussion CFPlugin object subclass which provides the primary interface to
 304                 HID devices.
 305 */
 306 typedef struct IOHIDDeviceInterface
 307 {
 308
 309     IUNKNOWN_C_GUTS;
 310
 311 /*! @function createAsyncEventSource
 312     @abstract Creates async eventsource.
 313     @discussion This method will create an async mach port, if one
 314         has not already been created.
 315     @param source Reference to CFRunLoopSourceRef that is created.
 316     @result Returns an IOReturn code.
 317 */
 318     IOReturn (*createAsyncEventSource)(void *                   self,
 319                                        CFRunLoopSourceRef *     source);
 320
 321 /*! @function getAsyncEventSource
 322     @abstract Gets the created async event source.
 323     @result Returns a CFRunLoopSourceRef.
 324 */
 325     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
 326
 327 /*! @function createAsyncPort
 328     @abstract Creates an async port.
 329     @discussion The port must be created before any callbacks can be used.
 330     @param port Reference to mach port that is created.
 331     @result Returns an IOReturn code.
 332 */
 333     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
 334
 335 /*! @function getAsyncPort
 336     @abstract Gets the current async port.
 337     @result Returns a mach_port_t.
 338 */
 339     mach_port_t (*getAsyncPort)(void * self);
 340
 341 /*! @function open
 342     @abstract Opens the device.
 343     @param flags Flags to be passed down to the user client.
 344     @result Returns an IOReturn code.
 345 */
 346     IOReturn (*open)(void * self, UInt32 flags);
 347
 348 /*! @function close
 349     @abstract Closes the device.
 350     @result Returns an IOReturn code.
 351 */
 352     IOReturn (*close)(void * self);
 353
 354 /*! @function setRemovalCallback
 355     @abstract Sets callback to be used when device is removed.
 356     @param removalCallback Called when the device is removed.
 357     @param removeTarget Passed to the callback.
 358     @param removalRefcon Passed to the callback.
 359     @result Returns an IOReturn code.
 360 */
 361     IOReturn (*setRemovalCallback)(void *                       self,
 362                                    IOHIDCallbackFunction        removalCallback,
 363                                    void *                       removalTarget,
 364                                    void *                       removalRefcon);
 365
 366 /*! @function getElementValue
 367     @abstract Obtains the most recent value of an element.
 368     @discussion This call is most useful for interrupt driven elements,
 369         such as input type elements.  Since feature type element values
 370         need to be polled from the device, it is recommended to use the
 371         queryElementValue method to obtain the current value.  The
 372         timestamp field in the event details the last time the element
 373         value was altered.
 374     @param elementCookie The element of interest.
 375     @param valueEvent The event that will be filled.   If a long value is
 376         present, it is up to the caller to deallocate it.
 377     @result Returns an IOReturn code.
 378 */
 379     IOReturn (*getElementValue)(void *                  self,
 380                                 IOHIDElementCookie      elementCookie,
 381                                 IOHIDEventStruct *      valueEvent);
 382
 383 /*! @function setElementValue
 384     @abstract Sets an element value on the device.
 385     @discussion This call is most useful for feature type elements.  It is
 386         recommended to use IOOutputTransaction for output type elements.
 387     @param elementCookie The element of interest.
 388     @param valueEvent The event that will be filled.  If a long value is
 389         present, it will be copied.
 390     @param timeoutMS UNSUPPORTED.
 391     @param callback UNSUPPORTED.
 392     @param callbackTarget UNSUPPORTED.
 393     @param callbackRefcon UNSUPPORTED.
 394     @result Returns an IOReturn code.
 395 */
 396     IOReturn (*setElementValue)(void *                          self,
 397                                 IOHIDElementCookie              elementCookie,
 398                                 IOHIDEventStruct *              valueEvent,
 399                                 UInt32                          timeoutMS,
 400                                 IOHIDElementCallbackFunction    callback,
 401                                 void *                          callbackTarget,
 402                                 void *                          callbackRefcon);
 403
 404 /*! @function queryElementValue
 405     @abstract Obtains the current value of an element.
 406     @discussion This call is most useful for feature type elements.  This
 407         method will poll the device for the current element value.
 408     @param elementCookie The element of interest.
 409     @param valueEvent The event that will be filled.  If a long value is
 410         present, it is up to the caller to deallocate it.
 411     @param timeoutMS UNSUPPORTED.
 412     @param callback UNSUPPORTED.
 413     @param callbackTarget UNSUPPORTED.
 414     @param callbackRefcon UNSUPPORTED.
 415     @result Returns an IOReturn code.
 416 */
 417     IOReturn (*queryElementValue)(void *                        self,
 418                                 IOHIDElementCookie              elementCookie,
 419                                 IOHIDEventStruct *              valueEvent,
 420                                 UInt32                          timeoutMS,
 421                                 IOHIDElementCallbackFunction    callback,
 422                                 void *                          callbackTarget,
 423                                 void *                          callbackRefcon);
 424
 425 /*! @function startAllQueues
 426     @abstract Starts data delivery on all queues for this device.
 427     @result Returns an IOReturn code.
 428 */
 429     IOReturn (*startAllQueues)(void * self);
 430
 431 /*! @function stopAllQueues
 432     @abstract Stops data delivery on all queues for this device.
 433     @result Returns an IOReturn code.
 434 */
 435     IOReturn (*stopAllQueues)(void * self);
 436
 437 /*! @function allocQueue
 438     @abstract Wrapper to return instances of the IOHIDQueueInterface.
 439     @result Returns the created IOHIDQueueInterface.
 440 */
 441     IOHIDQueueInterface ** (*allocQueue) (void *self);
 442
 443 /*! @function allocOutputTransaction
 444     @abstract Wrapper to return instances of the IOHIDOutputTransactionInterface.
 445     @result Returns the created IOHIDOutputTransactionInterface.
 446 */
 447     IOHIDOutputTransactionInterface ** (*allocOutputTransaction) (void *self);
 448
 449 } IOHIDDeviceInterface;
 450
 451 /*! @class IOHIDDeviceInterface121
 452     @discussion CFPlugin object subclass which provides the primary interface to
 453                 HID devices.  This class is a subclass of IOHIDDeviceInterface.
 454 */
 455 typedef struct IOHIDDeviceInterface121
 456 {
 457
 458     IUNKNOWN_C_GUTS;
 459     IOHIDDEVICEINTERFACE_FUNCS_100;
 460
 461 /*! @function setReport
 462     @abstract Sends a report to the device.
 463     @param reportType The report type.
 464     @param reportID The report id.
 465     @param reportBuffer Pointer to a preallocated buffer.
 466     @param reportBufferSize Size of the reportBuffer in bytes.
 467     @param timeoutMS
 468     @param callback If null, this method will behave synchronously.
 469     @param callbackTarget The callback target passed to the callback.
 470     @param callbackRefcon The callback refcon passed to the callback.
 471     @result Returns an IOReturn code.
 472 */
 473     IOReturn (*setReport)       (void *                         self,
 474                                 IOHIDReportType                 reportType,
 475                                 UInt32                          reportID,
 476                                 void *                          reportBuffer,
 477                                 UInt32                          reportBufferSize,
 478                                 UInt32                          timeoutMS,
 479                                 IOHIDReportCallbackFunction     callback,
 480                                 void *                          callbackTarget,
 481                                 void *                          callbackRefcon);
 482
 483 /*! @function getReport
 484     @abstract Obtains a report from the device.
 485     @param reportType The report type.
 486     @param reportID The report ID.
 487     @param reportBuffer Pointer to a preallocated buffer.
 488     @param reportBufferSize Size of the reportBuffer in bytes.
 489         When finished, will contain the actual size of the report.
 490     @param timeoutMS
 491     @param callback If null, this method will behave synchronously.
 492     @param callbackTarget The callback target passed to the callback.
 493     @param callbackRefcon The callback refcon passed to the callback.
 494     @result Returns an IOReturn code.
 495 */
 496     IOReturn (*getReport)       (void *                         self,
 497                                 IOHIDReportType                 reportType,
 498                                 UInt32                          reportID,
 499                                 void *                          reportBuffer,
 500                                 UInt32 *                        reportBufferSize,
 501                                 UInt32                          timeoutMS,
 502                                 IOHIDReportCallbackFunction     callback,
 503                                 void *                          callbackTarget,
 504                                 void *                          callbackRefcon);
 505
 506 }IOHIDDeviceInterface121;
 507
 508 /*! @class IOHIDDeviceInterface122
 509     @discussion CFPlugin object subclass which provides the primary interface to
 510                 HID devices.  This class is a subclass of IOHIDDeviceInterface121.
 511 */
 512 typedef struct IOHIDDeviceInterface122
 513 {
 514
 515     IUNKNOWN_C_GUTS;
 516     IOHIDDEVICEINTERFACE_FUNCS_100;
 517     IOHIDDEVICEINTERFACE_FUNCS_121;
 518
 519 /*! @function copyMatchingElements
 520     @abstract Obtains specific elements defined by the device.
 521     @discussion Using keys defined in IOHIDKeys.h for elements, create a
 522             matching dictonary containing items that you wish to search for.
 523             A null array indicates that no elements matching that criteria
 524             were found. Each item in the array is a reference to the same
 525             dictionary item that represents each element in the I/O Registry.
 526             It is up to the caller to release the returned array of elements.
 527     @param matchingDict Dictionary containg key/value pairs to match on.  Pass
 528             a null value to match on all elements.
 529     @param elements Pointer to a CFArrayRef that will be returned by this
 530             method.  It is up to the caller to release it when finished.
 531     @result Returns an IOReturn code.
 532 */
 533     IOReturn (*copyMatchingElements)(void *                     self,
 534                                 CFDictionaryRef                 matchingDict,
 535                                 CFArrayRef *                    elements);
 536
 537 /*! @function setInterruptReportHandlerCallback
 538     @abstract Sets the report handler callout to be called when the data
 539         is received from the Interrupt-In pipe.
 540     @discussion In order for this to work correctly, you must call
 541         createAsyncPort and createAsyncEventSource.
 542     @param reportBuffer Pointer to a preallocated buffer.
 543     @param reportBufferSize Size of the reportBuffer in bytes.
 544     @param callback If non-NULL, is a callback to be called when data
 545         is received from the device.
 546     @param callbackTarget The callback target passed to the callback
 547     @param callbackRefcon The callback refcon passed to the callback.
 548     @result Returns an IOReturn code.
 549 */
 550     IOReturn (*setInterruptReportHandlerCallback)(
 551                             void *                              self,
 552                             void *                              reportBuffer,
 553                             UInt32                              reportBufferSize,
 554                             IOHIDReportCallbackFunction         callback,
 555                             void *                              callbackTarget,
 556                             void *                              callbackRefcon);
 557
 558 }IOHIDDeviceInterface122;
 559
 560 /*! @class IOHIDQueueInterface
 561     @discussion CFPlugin object subclass which provides an interface for input
 562                 queues from HID devices. Created by an IOHIDDeviceInterface
 563                 object.
 564 */
 565 typedef struct IOHIDQueueInterface
 566 {
 567
 568     IUNKNOWN_C_GUTS;
 569
 570 /*! @function createAsyncEventSource
 571     @abstract Creates an async event source.
 572     @discussion This will be used with setEventCallout.
 573     @param source The newly created event source.
 574     @result Returns an IOReturn code.
 575 */
 576     IOReturn (*createAsyncEventSource)(void *                   self,
 577                                         CFRunLoopSourceRef *    source);
 578
 579 /*! @function getAsyncEventSource
 580     @abstract Obtains the current event source.
 581     @result Returns a CFRunLoopSourceRef.
 582 */
 583     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
 584
 585 /*! @function createAsyncPort
 586     @abstract Creates an async port.
 587     @discussion This will be used with createAsyncEventSource.
 588     @param port The newly created async port.
 589     @result Returns an IOReturn code.
 590 */
 591     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
 592
 593 /*! @function getAsyncPort
 594     @abstract Obtains the current async port.
 595     @result Returns a mach_port_t.
 596 */
 597     mach_port_t (*getAsyncPort)(void * self);
 598
 599 /*! @function create
 600     @abstract Creates the current queue.
 601     @param flags
 602     @param depth The maximum number of elements in the queue
 603         before the oldest elements in the queue begin to be lost.
 604     @result Returns an IOReturn code.
 605 */
 606     IOReturn (*create)(void *                   self,
 607                         UInt32                  flags,
 608                         UInt32                  depth);
 609
 610 /*! @function create
 611     @abstract Disposes of the current queue.
 612     @result Returns an IOReturn code.
 613 */
 614     IOReturn (*dispose)(void * self);
 615
 616 /*! @function addElement
 617     @abstract Adds an element to the queue.
 618     @discussion If the element has already been added to queue,
 619         an error will be returned.
 620     @param elementCookie The element of interest.
 621     @param flags
 622     @result Returns an IOReturn code.
 623 */
 624     IOReturn (*addElement)(void * self,
 625                            IOHIDElementCookie elementCookie,
 626                            UInt32 flags);
 627
 628 /*! @function removeElement
 629     @abstract Removes an element from the queue.
 630     @discussion If the element has not been added to queue,
 631         an error will be returned.
 632     @param elementCookie The element of interest.
 633     @result Returns an IOReturn code.
 634 */
 635     IOReturn (*removeElement)(void * self, IOHIDElementCookie elementCookie);
 636
 637 /*! @function hasElement
 638     @abstract Checks whether an element has been added to
 639         the queue.
 640     @discussion Will return true if present, otherwise will return false.
 641     @param elementCookie The element of interest.
 642     @result Returns a Boolean value.
 643 */
 644     Boolean (*hasElement)(void * self, IOHIDElementCookie elementCookie);
 645
 646 /*! @function start
 647     @abstract Starts event delivery to the queue.
 648     @result Returns an IOReturn code.
 649 */
 650     IOReturn (*start)(void * self);
 651
 652 /*! @function stop
 653     @abstract Stops event delivery to the queue.
 654     @result Returns an IOReturn code.
 655 */
 656     IOReturn (*stop)(void * self);
 657
 658 /*! @function getNextEvent
 659     @abstract Reads next event from the queue.
 660     @param event The event that will be filled.  If a long value is
 661         present, it is up to the caller to deallocate it.
 662     @param maxtime UNSUPPORTED.  If non-zero, limits read events to
 663         those that occured on or before maxTime.
 664     @param timoutMS UNSUPPORTED.  The timeout in milliseconds, a zero
 665         timeout will cause this call to be non-blocking (returning
 666         queue empty) if there is a NULL callback, and blocking forever
 667         until the queue is non-empty if there is a valid callback.
 668     @result Returns an IOReturn code.
 669 */
 670     IOReturn (*getNextEvent)(void *                     self,
 671                             IOHIDEventStruct *          event,
 672                             AbsoluteTime                maxTime,
 673                             UInt32                      timeoutMS);
 674
 675 /*! @function setEventCallout
 676     @abstract Sets the event callout to be called when the queue
 677         transitions to non-empty.
 678     @discussion In order for this to work correctly, you must call
 679         createAsyncPort and createAsyncEventSource.
 680     @param callback if non-NULL is a callback to be called when data
 681         is  inserted to the queue
 682     @param callbackTarget The callback target passed to the callback
 683     @param callbackRefcon The callback refcon passed to the callback.
 684     @result Returns an IOReturn code.
 685 */
 686     IOReturn (*setEventCallout)(void *                  self,
 687                                 IOHIDCallbackFunction   callback,
 688                                 void *                  callbackTarget,
 689                                 void *                  callbackRefcon);
 690
 691 /*! @function getEventCallout
 692     @abstract Gets the event callout.
 693     @discussion This callback will be called the queue transitions
 694         to non-empty.
 695     @param callback if non-NULL is a callback to be called when data
 696         is  inserted to the queue
 697     @param callbackTarget The callback target passed to the callback
 698     @param callbackRefcon The callback refcon passed to the callback
 699     @result Returns an IOReturn code.
 700 */
 701     IOReturn (*getEventCallout)(void *                  self,
 702                                 IOHIDCallbackFunction * outCallback,
 703                                 void **                 outCallbackTarget,
 704                                 void **                 outCallbackRefcon);
 705 } IOHIDQueueInterface;
 706
 707 /*! @class IOHIDOutputTransactionInterface
 708     @discussion CFPlugin object subclass which privides interface for output
 709                 transactions to HID devices. Created by a IOHIDDeviceInterface
 710                 object. */
 711
 712 typedef struct IOHIDOutputTransactionInterface
 713 {
 714     IUNKNOWN_C_GUTS;
 715
 716 /*! @function createAsyncEventSource
 717     @abstract Creates an async event source.
 718     @discussion This will be used with setEventCallout.
 719     @param source The newly created event source
 720     @result Returns an IOReturn code.
 721 */
 722     IOReturn (*createAsyncEventSource)(void *                   self,
 723                                         CFRunLoopSourceRef *    source);
 724
 725 /*! @function getAsyncEventSource
 726     @abstract Obtains the current event source.
 727     @result Returns a CFRunLoopSourceRef.
 728 */
 729     CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
 730
 731 /*! @function createAsyncPort
 732     @abstract Creates an async port.
 733     @discussion This will be used with createAsyncEventSource.
 734     @param port The newly created async port.
 735     @result Returns an IOReturn code.
 736 */
 737     IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
 738
 739 /*! @function getAsyncPort
 740     @abstract Obtains the current async port.
 741     @result Returns a mach_port_t.
 742 */
 743     mach_port_t (*getAsyncPort)(void * self);
 744
 745 /*! @function create
 746     @abstract Creates the current transaction.
 747     @discussion This method will free any memory that has been
 748         allocated for this transaction.
 749     @result Returns an IOReturn code.
 750 */
 751     IOReturn (*create)(void * self);
 752
 753 /*! @function dispose
 754     @abstract Disposes of the current transaction.
 755     @discussion The transaction will have to be recreated, in order
 756         to perform any operations on the transaction.
 757     @result Returns an IOReturn code.
 758 */
 759     IOReturn (*dispose)(void * self);
 760
 761 /*! @function addElement
 762     @abstract Adds an element to the transaction.
 763     @discussion If the element has already been added to transaction,
 764         an error will be returned.
 765     @param elementCookie The element of interest.
 766     @result Returns an IOReturn code.
 767 */
 768     IOReturn (*addElement)      (void * self, IOHIDElementCookie elementCookie);
 769
 770 /*! @function removeElement
 771     @abstract Removes an element from the transaction.
 772     @discussion If the element has not been added to transaction,
 773         an error will be returned.
 774     @param elementCookie The element of interest.
 775     @result Returns an IOReturn code.
 776 */
 777     IOReturn (*removeElement)   (void * self, IOHIDElementCookie elementCookie);
 778
 779 /*! @function hasElement
 780     @abstract Checks whether an element has been added to
 781         the transaction.
 782     @discussion Will return true if present, otherwise will return false.
 783     @param elementCookie The element of interest.
 784     @result Returns a Boolean value.
 785 */
 786     Boolean  (*hasElement)      (void * self, IOHIDElementCookie elementCookie);
 787
 788 /*! @function setElementDefault
 789     @abstract Sets the default value of an element in a
 790         transaction.
 791     @discussion An error will be returned if the element has not been
 792         added to the transaction.
 793     @param elementCookie The element of interest.
 794     @param valueEvent The event that will be filled.  If a long value is
 795         present, it will be copied.
 796     @result Returns an IOReturn code.
 797 */
 798     IOReturn (*setElementDefault)(void *                self,
 799                                     IOHIDElementCookie  elementCookie,
 800                                     IOHIDEventStruct *  valueEvent);
 801
 802 /*! @function getElementDefault
 803     @abstract Obtains the default value of an element in a
 804         transaction.
 805     @discussion An error will be returned if the element has not been
 806         added to the transaction.
 807     @param elementCookie The element of interest.
 808     @param outValueEvent The event that will be filled.  If a long value is
 809         present, it is up to the caller to deallocate it.
 810     @result Returns an IOReturn code.
 811 */
 812     IOReturn (*getElementDefault)(void *                self,
 813                                     IOHIDElementCookie  elementCookie,
 814                                     IOHIDEventStruct *  outValueEvent);
 815
 816 /*! @function setElementValue
 817     @abstract Sets the value of an element in a transaction.
 818     @discussion An error will be returned if the element has not been
 819         added to the transaction.
 820     @param elementCookie The element of interest.
 821     @param valueEvent The event that will be filled.  If a long value is
 822         present, it will be copied.
 823     @result Returns an IOReturn code.
 824 */
 825     IOReturn (*setElementValue)(void *                  self,
 826                                 IOHIDElementCookie      elementCookie,
 827                                 IOHIDEventStruct *      valueEvent);
 828
 829 /*! @function getElementValue
 830     @abstract Obtains the value of an element in a transaction.
 831     @discussion An error will be returned if the element has not been
 832         added to the transaction.
 833     @param elementCookie The element of interest.
 834     @param outValueEvent The event that will be filled.  If a long value is
 835         present, it is up to the caller to deallocate it.
 836     @result Returns an IOReturn code.
 837 */
 838     IOReturn (*getElementValue)(void *                  self,
 839                                 IOHIDElementCookie      elementCookie,
 840                                 IOHIDEventStruct *      outValueEvent);
 841
 842 /*! @function commit
 843     @abstract Commits the transaction.
 844     @discussion Transaction element values, if set, will be sent to the
 845         device.  Otherwise, the default element value will be used.  If
 846         neither are set, that element will be omitted from the commit.
 847         After a transaction is committed, transaction element values
 848         will be cleared.  Default values will be preserved.
 849     @param timeoutMS UNSUPPORTED
 850     @param callback UNSUPPORTED
 851     @param callbackTarget UNSUPPORTED
 852     @param callbackRefcon UNSUPPORTED
 853     @result Returns an IOReturn code.
 854 */
 855     IOReturn (*commit)(void *                   self,
 856                         UInt32                  timeoutMS,
 857                         IOHIDCallbackFunction   callback,
 858                         void *                  callbackTarget,
 859                         void *                  callbackRefcon);
 860
 861 /*! @function clear
 862     @abstract Clears the transaction.
 863     @discussion Transaction element values will cleared.   Default
 864         values will be preserved.
 865     @result Returns an IOReturn code.
 866 */
 867     IOReturn (*clear)(void * self);
 868 } IOHIDOutputTransactionInterface;
 869
 870 #endif
 871
 872 __END_DECLS
 873
 874 #endif /* !_IOKIT_HID_IOHIDLIB_H_ */