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