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