1/* 2 * Copyright (c) 1999-2008 Apple Computer, Inc. All Rights Reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. Please obtain a copy of the License at 10 * http://www.opensource.apple.com/apsl/ and read it before using this 11 * file. 12 * 13 * The Original Code and all software distributed under the License are 14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 18 * Please see the License for the specific language governing rights and 19 * limitations under the License. 20 * 21 * @APPLE_LICENSE_HEADER_END@ 22 */ 23 24#ifndef _IOKIT_HID_IOHIDMANAGER_H_ 25#define _IOKIT_HID_IOHIDMANAGER_H_ 26 27#include <IOKit/IOTypes.h> 28#include <IOKit/IOReturn.h> 29#include <IOKit/hid/IOHIDLib.h> 30#include <CoreFoundation/CoreFoundation.h> 31 32/*! 33 @header IOHIDManager 34 IOHIDManager defines an Human Interface Device (HID) managment object. 35 It provides global interaction with managed HID devices such as 36 discovery/removal and receiving input events. IOHIDManager is also a CFType 37 object and as such conforms to all the conventions expected such object. 38 <p> 39 This documentation assumes that you have a basic understanding of the 40 material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a> 41 For definitions of I/O Kit terms used in this documentation, such as 42 matching dictionary, family, and driver, see the overview of I/O Kit terms 43 and concepts n the "Device Access and the I/O Kit" chapter of 44 <i>Accessing Hardware From Applications</i>. 45 46 This documentation also assumes you have read <a href="http://developer.apple.com/documentation/DeviceDrivers/HumanInterfaceDeviceForceFeedback-date.html"><i>Human Interface Device & Force Feedback</i></a>. 47 Please review documentation before using this reference. 48 <p> 49 All of the information described in this document is contained in the header 50 file <font face="Courier New,Courier,Monaco">IOHIDManager.h</font> found at 51 <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDManager.h</font>. 52*/ 53 54__BEGIN_DECLS 55 56/*! 57 @enum IOHIDManagerOptions 58 @abstract Various options that can be supplied to IOHIDManager functions. 59 @const kIOHIDManagerOptionNone For those times when supplying 0 just isn't explicit enough. 60 @const kIOHIDManagerOptionUsePersistentProperties This constant can be supplied to @link IOHIDManagerCreate @/link 61 to create and/or use a persistent properties store. 62 @const kIOHIDManagerOptionDoNotLoadProperties This constant can be supplied to @link IOHIDManagerCreate when you wish to overwrite 63 the persistent properties store without loading it first. 64 @const kIOHIDManagerOptionDoNotSaveProperties This constant can be supplied to @link IOHIDManagerCreate @/link when you want to 65 use the persistent property store but do not want to add to it. 66 */ 67typedef enum { 68 kIOHIDManagerOptionNone = 0x0, 69 kIOHIDManagerOptionUsePersistentProperties = 0x1, 70 kIOHIDManagerOptionDoNotLoadProperties = 0x2, 71 kIOHIDManagerOptionDoNotSaveProperties = 0x4, 72} IOHIDManagerOptions; 73 74/*! @typedef IOHIDManagerRef 75 @abstract This is the type of a reference to the IOHIDManager. 76*/ 77typedef struct __IOHIDManager * IOHIDManagerRef; 78 79/*! 80 @function IOHIDManagerGetTypeID 81 @abstract Returns the type identifier of all IOHIDManager instances. 82*/ 83CF_EXPORT 84CFTypeID IOHIDManagerGetTypeID(void) 85AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 86 87/*! 88 @function IOHIDManagerCreate 89 @abstract Creates an IOHIDManager object. 90 @discussion The IOHIDManager object is meant as a global management system 91 for communicating with HID devices. 92 @param allocator Allocator to be used during creation. 93 @param options Supply @link kIOHIDManagerOptionUsePersistentProperties @/link to load 94 properties from the default persistent property store. Otherwise supply 95 @link kIOHIDManagerOptionNone @/link (or 0). 96 @result Returns a new IOHIDManagerRef. 97*/ 98CF_EXPORT 99IOHIDManagerRef IOHIDManagerCreate( 100 CFAllocatorRef allocator, 101 IOOptionBits options) 102AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 103 104/*! 105 @function IOHIDManagerOpen 106 @abstract Opens the IOHIDManager. 107 @discussion This will open both current and future devices that are 108 enumerated. To establish an exclusive link use the 109 kIOHIDOptionsTypeSeizeDevice option. 110 @param manager Reference to an IOHIDManager. 111 @param options Option bits to be sent down to the manager and device. 112 @result Returns kIOReturnSuccess if successful. 113*/ 114CF_EXPORT 115IOReturn IOHIDManagerOpen( 116 IOHIDManagerRef manager, 117 IOOptionBits options) 118AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 119 120/*! 121 @function IOHIDManagerClose 122 @abstract Closes the IOHIDManager. 123 @discussion This will also close all devices that are currently enumerated. 124 @param manager Reference to an IOHIDManager. 125 @param options Option bits to be sent down to the manager and device. 126 @result Returns kIOReturnSuccess if successful. 127*/ 128CF_EXPORT 129IOReturn IOHIDManagerClose( 130 IOHIDManagerRef manager, 131 IOOptionBits options) 132AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 133 134/*! 135 @function IOHIDManagerGetProperty 136 @abstract Obtains a property of an IOHIDManager. 137 @discussion Property keys are prefixed by kIOHIDDevice and declared in 138 <IOKit/hid/IOHIDKeys.h>. 139 @param manager Reference to an IOHIDManager. 140 @param key CFStringRef containing key to be used when querying the 141 manager. 142 @result Returns CFTypeRef containing the property. 143*/ 144CF_EXPORT 145CFTypeRef IOHIDManagerGetProperty( 146 IOHIDManagerRef manager, 147 CFStringRef key) 148AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 149 150/*! 151 @function IOHIDManagerSetProperty 152 @abstract Sets a property for an IOHIDManager. 153 @discussion Property keys are prefixed by kIOHIDDevice and kIOHIDManager and 154 declared in <IOKit/hid/IOHIDKeys.h>. This method will propagate 155 any relevent properties to current and future devices that are 156 enumerated. 157 @param manager Reference to an IOHIDManager. 158 @param key CFStringRef containing key to be used when modifiying the 159 device property. 160 @param value CFTypeRef containing the property value to be set. 161 @result Returns TRUE if successful. 162*/ 163CF_EXPORT 164Boolean IOHIDManagerSetProperty( 165 IOHIDManagerRef manager, 166 CFStringRef key, 167 CFTypeRef value) 168AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 169 170/*! @function IOHIDManagerScheduleWithRunLoop 171 @abstract Schedules HID manager with run loop. 172 @discussion Formally associates manager with client's run loop. Scheduling 173 this device with the run loop is necessary before making use of 174 any asynchronous APIs. This will propagate to current and 175 future devices that are enumerated. 176 @param manager Reference to an IOHIDManager. 177 @param runLoop RunLoop to be used when scheduling any asynchronous 178 activity. 179 @param runLoopMode Run loop mode to be used when scheduling any 180 asynchronous activity. 181*/ 182CF_EXPORT 183void IOHIDManagerScheduleWithRunLoop( 184 IOHIDManagerRef manager, 185 CFRunLoopRef runLoop, 186 CFStringRef runLoopMode) 187AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 188 189/*! @function IOHIDManagerUnscheduleFromRunLoop 190 @abstract Unschedules HID manager with run loop. 191 @discussion Formally disassociates device with client's run loop. This will 192 propagate to current devices that are enumerated. 193 @param manager Reference to an IOHIDManager. 194 @param runLoop RunLoop to be used when unscheduling any asynchronous 195 activity. 196 @param runLoopMode Run loop mode to be used when unscheduling any 197 asynchronous activity. 198*/ 199CF_EXPORT 200void IOHIDManagerUnscheduleFromRunLoop( 201 IOHIDManagerRef manager, 202 CFRunLoopRef runLoop, 203 CFStringRef runLoopMode) 204AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 205 206/*! @function IOHIDManagerSetDeviceMatching 207 @abstract Sets matching criteria for device enumeration. 208 @discussion Matching keys are prefixed by kIOHIDDevice and declared in 209 <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result 210 in all devices being enumerated. Any subsequent calls will cause 211 the hid manager to release previously enumerated devices and 212 restart the enuerate process using the revised criteria. If 213 interested in multiple, specific device classes, please defer to 214 using IOHIDManagerSetDeviceMatchingMultiple. 215 @param manager Reference to an IOHIDManager. 216 @param matching CFDictionaryRef containg device matching criteria. 217*/ 218CF_EXPORT 219void IOHIDManagerSetDeviceMatching( 220 IOHIDManagerRef manager, 221 CFDictionaryRef matching) 222AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 223 224/*! @function IOHIDManagerSetDeviceMatchingMultiple 225 @abstract Sets multiple matching criteria for device enumeration. 226 @discussion Matching keys are prefixed by kIOHIDDevice and declared in 227 <IOKit/hid/IOHIDKeys.h>. This method is useful if interested 228 in multiple, specific device classes. 229 @param manager Reference to an IOHIDManager. 230 @param multiple CFArrayRef containing multiple CFDictionaryRef objects 231 containg device matching criteria. 232*/ 233CF_EXPORT 234void IOHIDManagerSetDeviceMatchingMultiple( 235 IOHIDManagerRef manager, 236 CFArrayRef multiple) 237AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 238 239/*! @function IOHIDManagerCopyDevices 240 @abstract Obtains currently enumerated devices. 241 @param manager Reference to an IOHIDManager. 242 @result CFSetRef containing IOHIDDeviceRefs. 243*/ 244CF_EXPORT 245CFSetRef IOHIDManagerCopyDevices( 246 IOHIDManagerRef manager) 247AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 248 249/*! @function IOHIDManagerRegisterDeviceMatchingCallback 250 @abstract Registers a callback to be used a device is enumerated. 251 @discussion Only device matching the set criteria will be enumerated. 252 @param manager Reference to an IOHIDManagerRef. 253 @param callback Pointer to a callback method of type 254 IOHIDDeviceCallback. 255 @param context Pointer to data to be passed to the callback. 256*/ 257CF_EXPORT 258void IOHIDManagerRegisterDeviceMatchingCallback( 259 IOHIDManagerRef manager, 260 IOHIDDeviceCallback callback, 261 void * context) 262AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 263 264/*! @function IOHIDManagerRegisterDeviceRemovalCallback 265 @abstract Registers a callback to be used when any enumerated device is 266 removed. 267 @discussion In most cases this occurs when a device is unplugged. 268 @param manager Reference to an IOHIDManagerRef. 269 @param callback Pointer to a callback method of type 270 IOHIDDeviceCallback. 271 @param context Pointer to data to be passed to the callback. 272*/ 273CF_EXPORT 274void IOHIDManagerRegisterDeviceRemovalCallback( 275 IOHIDManagerRef manager, 276 IOHIDDeviceCallback callback, 277 void * context) 278AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 279 280/*! @function IOHIDManagerRegisterInputReportCallback 281 @abstract Registers a callback to be used when an input report is issued by 282 any enumerated device. 283 @discussion An input report is an interrupt driver report issued by a device. 284 @param manager Reference to an IOHIDManagerRef. 285 @param callback Pointer to a callback method of type IOHIDReportCallback. 286 @param context Pointer to data to be passed to the callback. 287*/ 288CF_EXPORT 289void IOHIDManagerRegisterInputReportCallback( 290 IOHIDManagerRef manager, 291 IOHIDReportCallback callback, 292 void * context) 293AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 294 295/*! @function IOHIDManagerRegisterInputValueCallback 296 @abstract Registers a callback to be used when an input value is issued by 297 any enumerated device. 298 @discussion An input element refers to any element of type 299 kIOHIDElementTypeInput and is usually issued by interrupt driven 300 reports. 301 @param manager Reference to an IOHIDManagerRef. 302 @param callback Pointer to a callback method of type IOHIDValueCallback. 303 @param context Pointer to data to be passed to the callback. 304*/ 305CF_EXPORT 306void IOHIDManagerRegisterInputValueCallback( 307 IOHIDManagerRef manager, 308 IOHIDValueCallback callback, 309 void * context) 310AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 311 312/*! @function IOHIDManagerSetInputValueMatching 313 @abstract Sets matching criteria for input values received via 314 IOHIDManagerRegisterInputValueCallback. 315 @discussion Matching keys are prefixed by kIOHIDElement and declared in 316 <IOKit/hid/IOHIDKeys.h>. Passing a NULL dictionary will result 317 in all devices being enumerated. Any subsequent calls will cause 318 the hid manager to release previously matched input elements and 319 restart the matching process using the revised criteria. If 320 interested in multiple, specific device elements, please defer to 321 using IOHIDManagerSetInputValueMatchingMultiple. 322 @param manager Reference to an IOHIDManager. 323 @param matching CFDictionaryRef containg device matching criteria. 324*/ 325CF_EXPORT 326void IOHIDManagerSetInputValueMatching( 327 IOHIDManagerRef manager, 328 CFDictionaryRef matching) 329AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 330 331/*! @function IOHIDManagerSetInputValueMatchingMultiple 332 @abstract Sets multiple matching criteria for input values received via 333 IOHIDManagerRegisterInputValueCallback. 334 @discussion Matching keys are prefixed by kIOHIDElement and declared in 335 <IOKit/hid/IOHIDKeys.h>. This method is useful if interested 336 in multiple, specific elements . 337 @param manager Reference to an IOHIDManager. 338 @param multiple CFArrayRef containing multiple CFDictionaryRef objects 339 containing input element matching criteria. 340*/ 341 342CF_EXPORT 343void IOHIDManagerSetInputValueMatchingMultiple( 344 IOHIDManagerRef manager, 345 CFArrayRef multiple) 346AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER; 347 348/*! 349 @abstract Used to write out the current properties to a specific domain. 350 @discussion Using this function will cause the persistent properties to be saved out 351 replacing any properties that already existed in the specified domain. All arguments 352 must be non-NULL except options. 353 @param manager Reference to an IOHIDManager. 354 @param applicationID Reference to a CFPreferences applicationID. 355 @param userName Reference to a CFPreferences userName. 356 @param hostName Reference to a CFPreferences hostName. 357 @param options Reserved for future use. 358 */ 359CF_EXPORT 360void IOHIDManagerSaveToPropertyDomain(IOHIDManagerRef manager, 361 CFStringRef applicationID, 362 CFStringRef userName, 363 CFStringRef hostName, 364 IOOptionBits options) 365AVAILABLE_MAC_OS_X_VERSION_10_6_AND_LATER; 366 367 368 369__END_DECLS 370 371#endif /* _IOKIT_HID_IOHIDMANAGER_H_ */ 372 373