Mercurial > sdl-ios-xcode

comparison src/joystick/darwin/10.3.9-FIX/IOHIDLib.h @ 2110:21942f552734

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