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_ */