1/*
2 *
3 * @APPLE_LICENSE_HEADER_START@
4 *
5 * Copyright (c) 1999-2012 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_IOHIDUSERDEVICE_USER_H
26#define _IOKIT_HID_IOHIDUSERDEVICE_USER_H
27
28#include <CoreFoundation/CoreFoundation.h>
29#include <IOKit/IOKitLib.h>
30#include <IOKit/hid/IOHIDKeys.h>
31
32__BEGIN_DECLS
33
34typedef struct __IOHIDUserDevice * IOHIDUserDeviceRef;
35
36
37typedef IOReturn (*IOHIDUserDeviceReportCallback)(void * refcon, IOHIDReportType type, uint32_t reportID, uint8_t * report, CFIndex reportLength);
38typedef IOReturn (*IOHIDUserDeviceReportWithReturnLengthCallback)(void * refcon, IOHIDReportType type, uint32_t reportID, uint8_t * report, CFIndex * pReportLength);
39typedef IOReturn (*IOHIDUserDeviceHandleReportAsyncCallback)(void * refcon, IOReturn result);
40
41enum {
42  kIOHIDUserDeviceCreateOptionStartWhenScheduled = (1<<0)
43};
44
45/*!
46    @function   IOHIDUserDeviceGetTypeID
47    @abstract   Returns the type identifier of all IOHIDUserDevice instances.
48*/
49CF_EXPORT
50CFTypeID IOHIDUserDeviceGetTypeID(void);
51
52/*!
53    @function   IOHIDUserDeviceCreate
54    @abstract   Creates an virtual IOHIDDevice in the kernel.
55    @discussion The io_service_t passed in this method must reference an object
56                in the kernel of type IOHIDUserDevice.
57    @param      allocator Allocator to be used during creation.
58    @param      properties CFDictionaryRef containing device properties index by keys defined in IOHIDKeys.h.
59    @result     Returns a new IOHIDUserDeviceRef.
60*/
61CF_EXPORT
62IOHIDUserDeviceRef IOHIDUserDeviceCreate(CFAllocatorRef allocator, CFDictionaryRef properties);
63
64/*!
65 @function   IOHIDUserDeviceCreateWithOptions
66 @abstract   Creates an virtual IOHIDDevice in the kernel.
67 @discussion The io_service_t passed in this method must reference an object
68 in the kernel of type IOHIDUserDevice.  Please use the kIOHIDUserDeviceCreateOptionStartWhenScheduled option
69 if you would like to ensure that callbacks are in place and scheduled prior to starting the device.  This will
70 that you will be able to handle getReport and setReport operations if performed during creation.
71 @param      allocator Allocator to be used during creation.
72 @param      properties CFDictionaryRef containing device properties index by keys defined in IOHIDKeys.h.
73 @param      options options to be used when allocating the device
74 @result     Returns a new IOHIDUserDeviceRef.
75 */
76CF_EXPORT
77IOHIDUserDeviceRef IOHIDUserDeviceCreateWithOptions(CFAllocatorRef allocator, CFDictionaryRef properties, IOOptionBits options);
78
79
80/*!
81    @function   IOHIDUserDeviceScheduleWithRunLoop
82    @abstract   Schedules the IOHIDUserDevice with a run loop
83    @discussion This is necessary to receive asynchronous events from the kernel
84    @param      device Reference to IOHIDUserDevice
85    @param      runLoop Run loop to be scheduled with
86    @param      runLoopMode Run loop mode to be scheduled with
87*/
88CF_EXPORT
89void IOHIDUserDeviceScheduleWithRunLoop(IOHIDUserDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode);
90
91/*!
92    @function   IOHIDUserDeviceUnscheduleFromRunLoop
93    @abstract   Unschedules the IOHIDUserDevice from a run loop
94    @param      device Reference to IOHIDUserDevice
95    @param      runLoop Run loop to be scheduled with
96    @param      runLoopMode Run loop mode to be scheduled with
97*/
98CF_EXPORT
99void IOHIDUserDeviceUnscheduleFromRunLoop(IOHIDUserDeviceRef device, CFRunLoopRef runLoop, CFStringRef runLoopMode);
100
101/*!
102 @function   IOHIDUserDeviceScheduleWithDispatchQueue
103 @abstract   Schedules the IOHIDUserDevice with a dispatch queue
104 @discussion This is necessary to receive asynchronous events from the kernel
105 @param      device Reference to IOHIDUserDevice
106 @param      queue Dispatch queue to be registered with
107 */
108CF_EXPORT
109void IOHIDUserDeviceScheduleWithDispatchQueue(IOHIDUserDeviceRef device, dispatch_queue_t queue);
110
111/*!
112 @function   IOHIDUserDeviceUnscheduleFromDispatchQueue
113 @abstract   Unschedules the IOHIDUserDevice from a dispatch queue
114 @param      device Reference to IOHIDUserDevice
115 @param      queue Dispatch queue to be unregistered from
116 */
117CF_EXPORT
118void IOHIDUserDeviceUnscheduleFromDispatchQueue(IOHIDUserDeviceRef device, dispatch_queue_t queue);
119
120/*!
121    @function   IOHIDUserDeviceRegisterGetReportCallback
122    @abstract   Register a callback to receive get report requests
123    @param      device Reference to IOHIDUserDevice
124    @param      callback Callback of type IOHIDUserDeviceReportCallback to be used
125    @param      refcon pointer to a reference object of your choosing
126*/
127CF_EXPORT
128void IOHIDUserDeviceRegisterGetReportCallback(IOHIDUserDeviceRef device, IOHIDUserDeviceReportCallback callback, void * refcon);
129
130/*!
131 @function   IOHIDUserDeviceRegisterGetReportWithLegthCallback
132 @abstract   Register a callback to receive get report requests
133 @discussion Unlike the callback specified in IOHIDUserDeviceRegisterGetReportCallback, the callback passed here allows the callee to return the actual bytes read.
134 @param      device Reference to IOHIDUserDevice
135 @param      callback Callback of type IOHIDUserDeviceReportWithReturnLengthCallback to be used
136 @param      refcon pointer to a reference object of your choosing
137 */
138CF_EXPORT
139void IOHIDUserDeviceRegisterGetReportWithReturnLengthCallback(IOHIDUserDeviceRef device, IOHIDUserDeviceReportWithReturnLengthCallback callback, void * refcon);
140
141/*!
142    @function   IOHIDUserDeviceRegisterSetReportCallback
143    @abstract   Register a callback to receive set report requests
144    @param      device Reference to IOHIDUserDevice
145    @param      callback Callback to be used
146    @param      refcon pointer to a reference object of your choosing
147*/
148CF_EXPORT
149void IOHIDUserDeviceRegisterSetReportCallback(IOHIDUserDeviceRef device, IOHIDUserDeviceReportCallback callback, void * refcon);
150
151/*!
152    @function   IOHIDUserDeviceHandleReport
153    @abstract   Dispatch a report to the IOHIDUserDevice.
154    @param      device Reference to IOHIDUserDevice
155    @param      report Buffer containing formated report being issued to HID stack
156    @param      reportLength Report buffer length
157    @result     Returns kIOReturnSuccess when report is handled successfully.
158*/
159CF_EXPORT
160IOReturn IOHIDUserDeviceHandleReport(IOHIDUserDeviceRef device, uint8_t * report, CFIndex reportLength);
161
162/*!
163    @function   IOHIDUserDeviceHandleReportAsync
164    @abstract   Dispatch a report to the IOHIDUserDevice.
165    @param      device Reference to IOHIDUserDevice
166    @param      report Buffer containing formated report being issued to HID stack
167    @param      reportLength Report buffer length
168    @param      callback Callback to be used (optional)
169    @param      refcon pointer to a reference object of your choosing (optional)
170    @result     Returns kIOReturnSuccess when report is handled successfully.
171 */
172CF_EXPORT
173IOReturn IOHIDUserDeviceHandleReportAsync(IOHIDUserDeviceRef device, uint8_t *report, CFIndex reportLength, IOHIDUserDeviceHandleReportAsyncCallback callback, void * refcon);
174
175/*!
176    @function   IOHIDUserDeviceHandleReportWithTimeStamp
177    @abstract   Dispatch a report to the IOHIDUserDevice.
178    @param      device Reference to IOHIDUserDevice
179    @param      timestamp mach_absolute_time() based timestamp
180    @param      report Buffer containing formated report being issued to HID stack
181    @param      reportLength Report buffer length
182    @result     Returns kIOReturnSuccess when report is handled successfully.
183 */
184CF_EXPORT
185IOReturn IOHIDUserDeviceHandleReportWithTimeStamp(IOHIDUserDeviceRef device, uint64_t timestamp, uint8_t * report, CFIndex reportLength);
186
187/*!
188    @function   IOHIDUserDeviceHandleReportAsync
189    @abstract   Dispatch a report to the IOHIDUserDevice.
190    @param      device Reference to IOHIDUserDevice
191    @param      timestamp mach_absolute_time() based timestamp
192    @param      report Buffer containing formated report being issued to HID stack
193    @param      reportLength Report buffer length
194    @param      callback Callback to be used (optional)
195    @param      refcon pointer to a reference object of your choosing (optional)
196    @result     Returns kIOReturnSuccess when report is handled successfully.
197 */
198CF_EXPORT
199IOReturn IOHIDUserDeviceHandleReportAsyncWithTimeStamp(IOHIDUserDeviceRef device, uint64_t timestamp, uint8_t *report, CFIndex reportLength, IOHIDUserDeviceHandleReportAsyncCallback callback, void * refcon);
200
201__END_DECLS
202
203#endif /* _IOKIT_HID_IOHIDUSERDEVICE_USER_H */
204