4 * @APPLE_LICENSE_HEADER_START@
6 * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
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
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.
23 * @APPLE_LICENSE_HEADER_END@
26 #ifndef _IOKIT_HID_IOHIDLIB_H_
27 #define _IOKIT_HID_IOHIDLIB_H_
29 #include <sys/cdefs.h>
32 #include <CoreFoundation/CoreFoundation.h>
33 #if COREFOUNDATION_CFPLUGINCOM_SEPARATE
34 #include <CoreFoundation/CFPlugInCOM.h>
37 #include <IOKit/IOTypes.h>
38 #include <IOKit/IOReturn.h>
40 #include <IOKit/hid/IOHIDKeys.h>
42 struct IOHIDEventStruct
44 IOHIDElementType type;
45 IOHIDElementCookie elementCookie;
47 AbsoluteTime timestamp;
51 typedef struct IOHIDEventStruct IOHIDEventStruct;
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)
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)
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)
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)
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
88 #define kIOHIDDeviceInterfaceID122 CFUUIDGetConstantUUIDWithBytes(NULL, \
89 0xb7, 0xa, 0xbf, 0x31, 0x16, 0xd5, 0x11, 0xd7, \
90 0xab, 0x35, 0x0, 0x3, 0x93, 0x99, 0x2e, 0x38)
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)
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)
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.
118 typedef void (*IOHIDCallbackFunction)
119 (void * target, IOReturn result, void * refcon, void * sender);
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.
130 typedef void (*IOHIDElementCallbackFunction)
135 IOHIDElementCookie elementCookie);
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.
146 typedef void (*IOHIDReportCallbackFunction)
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;
161 // IOHIDDeviceInterface Functions available in version 1.0 (10.0) and higher of Mac OS X
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)
188 // IOHIDDeviceInterface Functions available in version 1.2.1 (10.2.3) and higher of Mac OS X
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)
202 // IOHIDDeviceInterface Functions available in version 1.2.2 (10.3) and higher of Mac OS X
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)
212 typedef struct IOHIDDeviceInterface
215 IOHIDDEVICEINTERFACE_FUNCS_100;
216 IOHIDDEVICEINTERFACE_FUNCS_121;
217 } IOHIDDeviceInterface;
219 typedef struct IOHIDDeviceInterface121
222 IOHIDDEVICEINTERFACE_FUNCS_100;
223 IOHIDDEVICEINTERFACE_FUNCS_121;
224 } IOHIDDeviceInterface121;
226 typedef struct IOHIDDeviceInterface122
229 IOHIDDEVICEINTERFACE_FUNCS_100;
230 IOHIDDEVICEINTERFACE_FUNCS_121;
231 IOHIDDEVICEINTERFACE_FUNCS_122;
232 } IOHIDDeviceInterface122;
236 // IOHIDQueueInterface Functions available in version 1.0 (10.0) and higher of Mac OS X
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)
257 struct IOHIDQueueInterface
260 IOHIDQUEUEINTERFACE_FUNCS_100;
264 // IOHIDOutputTransactionInterface Functions available in version 1.2 (10.2) and higher of Mac OS X
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)
288 struct IOHIDOutputTransactionInterface
291 IOHIDOUTPUTTRANSACTIONINTERFACE_FUNCS_120;
296 // BEGIN READABLE STRUCTURE DEFINITIONS
298 // This portion of uncompiled code provides a more reader friendly representation of
299 // the CFPlugin methods defined above.
302 /*! @class IOHIDDeviceInterface
303 @discussion CFPlugin object subclass which provides the primary interface to
306 typedef struct IOHIDDeviceInterface
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.
318 IOReturn (*createAsyncEventSource)(void * self,
319 CFRunLoopSourceRef * source);
321 /*! @function getAsyncEventSource
322 @abstract Gets the created async event source.
323 @result Returns a CFRunLoopSourceRef.
325 CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
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.
333 IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
335 /*! @function getAsyncPort
336 @abstract Gets the current async port.
337 @result Returns a mach_port_t.
339 mach_port_t (*getAsyncPort)(void * self);
342 @abstract Opens the device.
343 @param flags Flags to be passed down to the user client.
344 @result Returns an IOReturn code.
346 IOReturn (*open)(void * self, UInt32 flags);
349 @abstract Closes the device.
350 @result Returns an IOReturn code.
352 IOReturn (*close)(void * self);
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.
361 IOReturn (*setRemovalCallback)(void * self,
362 IOHIDCallbackFunction removalCallback,
363 void * removalTarget,
364 void * removalRefcon);
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
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.
379 IOReturn (*getElementValue)(void * self,
380 IOHIDElementCookie elementCookie,
381 IOHIDEventStruct * valueEvent);
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.
396 IOReturn (*setElementValue)(void * self,
397 IOHIDElementCookie elementCookie,
398 IOHIDEventStruct * valueEvent,
400 IOHIDElementCallbackFunction callback,
401 void * callbackTarget,
402 void * callbackRefcon);
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.
417 IOReturn (*queryElementValue)(void * self,
418 IOHIDElementCookie elementCookie,
419 IOHIDEventStruct * valueEvent,
421 IOHIDElementCallbackFunction callback,
422 void * callbackTarget,
423 void * callbackRefcon);
425 /*! @function startAllQueues
426 @abstract Starts data delivery on all queues for this device.
427 @result Returns an IOReturn code.
429 IOReturn (*startAllQueues)(void * self);
431 /*! @function stopAllQueues
432 @abstract Stops data delivery on all queues for this device.
433 @result Returns an IOReturn code.
435 IOReturn (*stopAllQueues)(void * self);
437 /*! @function allocQueue
438 @abstract Wrapper to return instances of the IOHIDQueueInterface.
439 @result Returns the created IOHIDQueueInterface.
441 IOHIDQueueInterface ** (*allocQueue) (void *self);
443 /*! @function allocOutputTransaction
444 @abstract Wrapper to return instances of the IOHIDOutputTransactionInterface.
445 @result Returns the created IOHIDOutputTransactionInterface.
447 IOHIDOutputTransactionInterface ** (*allocOutputTransaction) (void *self);
449 } IOHIDDeviceInterface;
451 /*! @class IOHIDDeviceInterface121
452 @discussion CFPlugin object subclass which provides the primary interface to
453 HID devices. This class is a subclass of IOHIDDeviceInterface.
455 typedef struct IOHIDDeviceInterface121
459 IOHIDDEVICEINTERFACE_FUNCS_100;
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.
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.
473 IOReturn (*setReport) (void * self,
474 IOHIDReportType reportType,
477 UInt32 reportBufferSize,
479 IOHIDReportCallbackFunction callback,
480 void * callbackTarget,
481 void * callbackRefcon);
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.
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.
496 IOReturn (*getReport) (void * self,
497 IOHIDReportType reportType,
500 UInt32 * reportBufferSize,
502 IOHIDReportCallbackFunction callback,
503 void * callbackTarget,
504 void * callbackRefcon);
506 }IOHIDDeviceInterface121;
508 /*! @class IOHIDDeviceInterface122
509 @discussion CFPlugin object subclass which provides the primary interface to
510 HID devices. This class is a subclass of IOHIDDeviceInterface121.
512 typedef struct IOHIDDeviceInterface122
516 IOHIDDEVICEINTERFACE_FUNCS_100;
517 IOHIDDEVICEINTERFACE_FUNCS_121;
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.
533 IOReturn (*copyMatchingElements)(void * self,
534 CFDictionaryRef matchingDict,
535 CFArrayRef * elements);
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.
550 IOReturn (*setInterruptReportHandlerCallback)(
553 UInt32 reportBufferSize,
554 IOHIDReportCallbackFunction callback,
555 void * callbackTarget,
556 void * callbackRefcon);
558 }IOHIDDeviceInterface122;
560 /*! @class IOHIDQueueInterface
561 @discussion CFPlugin object subclass which provides an interface for input
562 queues from HID devices. Created by an IOHIDDeviceInterface
565 typedef struct IOHIDQueueInterface
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.
576 IOReturn (*createAsyncEventSource)(void * self,
577 CFRunLoopSourceRef * source);
579 /*! @function getAsyncEventSource
580 @abstract Obtains the current event source.
581 @result Returns a CFRunLoopSourceRef.
583 CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
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.
591 IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
593 /*! @function getAsyncPort
594 @abstract Obtains the current async port.
595 @result Returns a mach_port_t.
597 mach_port_t (*getAsyncPort)(void * self);
600 @abstract Creates the current queue.
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.
606 IOReturn (*create)(void * self,
611 @abstract Disposes of the current queue.
612 @result Returns an IOReturn code.
614 IOReturn (*dispose)(void * self);
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.
622 @result Returns an IOReturn code.
624 IOReturn (*addElement)(void * self,
625 IOHIDElementCookie elementCookie,
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.
635 IOReturn (*removeElement)(void * self, IOHIDElementCookie elementCookie);
637 /*! @function hasElement
638 @abstract Checks whether an element has been added to
640 @discussion Will return true if present, otherwise will return false.
641 @param elementCookie The element of interest.
642 @result Returns a Boolean value.
644 Boolean (*hasElement)(void * self, IOHIDElementCookie elementCookie);
647 @abstract Starts event delivery to the queue.
648 @result Returns an IOReturn code.
650 IOReturn (*start)(void * self);
653 @abstract Stops event delivery to the queue.
654 @result Returns an IOReturn code.
656 IOReturn (*stop)(void * self);
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.
670 IOReturn (*getNextEvent)(void * self,
671 IOHIDEventStruct * event,
672 AbsoluteTime maxTime,
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.
686 IOReturn (*setEventCallout)(void * self,
687 IOHIDCallbackFunction callback,
688 void * callbackTarget,
689 void * callbackRefcon);
691 /*! @function getEventCallout
692 @abstract Gets the event callout.
693 @discussion This callback will be called the queue transitions
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.
701 IOReturn (*getEventCallout)(void * self,
702 IOHIDCallbackFunction * outCallback,
703 void ** outCallbackTarget,
704 void ** outCallbackRefcon);
705 } IOHIDQueueInterface;
707 /*! @class IOHIDOutputTransactionInterface
708 @discussion CFPlugin object subclass which privides interface for output
709 transactions to HID devices. Created by a IOHIDDeviceInterface
712 typedef struct IOHIDOutputTransactionInterface
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.
722 IOReturn (*createAsyncEventSource)(void * self,
723 CFRunLoopSourceRef * source);
725 /*! @function getAsyncEventSource
726 @abstract Obtains the current event source.
727 @result Returns a CFRunLoopSourceRef.
729 CFRunLoopSourceRef (*getAsyncEventSource)(void * self);
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.
737 IOReturn (*createAsyncPort)(void * self, mach_port_t * port);
739 /*! @function getAsyncPort
740 @abstract Obtains the current async port.
741 @result Returns a mach_port_t.
743 mach_port_t (*getAsyncPort)(void * self);
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.
751 IOReturn (*create)(void * self);
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.
759 IOReturn (*dispose)(void * self);
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.
768 IOReturn (*addElement) (void * self, IOHIDElementCookie elementCookie);
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.
777 IOReturn (*removeElement) (void * self, IOHIDElementCookie elementCookie);
779 /*! @function hasElement
780 @abstract Checks whether an element has been added to
782 @discussion Will return true if present, otherwise will return false.
783 @param elementCookie The element of interest.
784 @result Returns a Boolean value.
786 Boolean (*hasElement) (void * self, IOHIDElementCookie elementCookie);
788 /*! @function setElementDefault
789 @abstract Sets the default value of an element in a
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.
798 IOReturn (*setElementDefault)(void * self,
799 IOHIDElementCookie elementCookie,
800 IOHIDEventStruct * valueEvent);
802 /*! @function getElementDefault
803 @abstract Obtains the default value of an element in a
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.
812 IOReturn (*getElementDefault)(void * self,
813 IOHIDElementCookie elementCookie,
814 IOHIDEventStruct * outValueEvent);
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.
825 IOReturn (*setElementValue)(void * self,
826 IOHIDElementCookie elementCookie,
827 IOHIDEventStruct * valueEvent);
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.
838 IOReturn (*getElementValue)(void * self,
839 IOHIDElementCookie elementCookie,
840 IOHIDEventStruct * outValueEvent);
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.
855 IOReturn (*commit)(void * self,
857 IOHIDCallbackFunction callback,
858 void * callbackTarget,
859 void * callbackRefcon);
862 @abstract Clears the transaction.
863 @discussion Transaction element values will cleared. Default
864 values will be preserved.
865 @result Returns an IOReturn code.
867 IOReturn (*clear)(void * self);
868 } IOHIDOutputTransactionInterface;
874 #endif /* !_IOKIT_HID_IOHIDLIB_H_ */