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_IOHIDELEMENT_USER_H
25#define _IOKIT_HID_IOHIDELEMENT_USER_H
26
27#include <CoreFoundation/CoreFoundation.h>
28#include <IOKit/hid/IOHIDKeys.h>
29#include <IOKit/hid/IOHIDBase.h>
30
31/*!
32	@header IOHIDElement
33    IOHIDElement defines a parsed item contained within a Human Interface Device
34    (HID) object.  It is used to obtain properties of the parsed.  It can also
35    be used to set properties such as calibration settings.  IOHIDElement is a
36    CFType object and as such conforms to all the conventions expected such
37    object.
38    <p>
39    This documentation assumes that you have a basic understanding of the material contained in <a href="http://developer.apple.com/documentation/DeviceDrivers/Conceptual/AccessingHardware/index.html"><i>Accessing Hardware From Applications</i></a>
40    For definitions of I/O Kit terms used in this documentation, such as matching dictionary, family, and driver, see the overview of I/O Kit terms and concepts
41    in the "Device Access and the I/O Kit" chapter of <i>Accessing Hardware From Applications</i>.
42    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>.
43    Please review documentation before using this reference.
44    <p>
45    All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDElement.h</font> found at
46    <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDElement.h</font>.
47*/
48
49__BEGIN_DECLS
50
51/*!
52	@function   IOHIDElementGetTypeID
53	@abstract   Returns the type identifier of all IOHIDElement instances.
54*/
55CF_EXPORT
56CFTypeID IOHIDElementGetTypeID(void)
57AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
58
59/*!
60	@function   IOHIDElementCreateWithDictionary
61	@abstract   Creates an element from a dictionary.
62    @discussion The dictionary should contain keys defined in IOHIDKeys.h and start with kIOHIDElement.  This call is meant be used by a IOHIDDeviceDeviceInterface object.
63    @param      allocator Allocator to be used during creation.
64    @param      dictionary dictionary containing values in which to create element.
65    @result     Returns a new IOHIDElementRef.
66*/
67CF_EXPORT
68IOHIDElementRef IOHIDElementCreateWithDictionary(CFAllocatorRef allocator, CFDictionaryRef dictionary)
69AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
70
71/*!
72	@function   IOHIDElementGetDevice
73	@abstract   Obtain the device associated with the element.
74    @param      element IOHIDElement to be queried.
75    @result     Returns the a reference to the device.
76*/
77CF_EXPORT
78IOHIDDeviceRef IOHIDElementGetDevice(IOHIDElementRef element)
79AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
80
81/*!
82	@function   IOHIDElementGetParent
83	@abstract   Returns the parent for the element.
84    @discussion The parent element can be an element of type kIOHIDElementTypeCollection.
85    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
86    @result     Returns an IOHIDElementRef referencing the parent element.
87*/
88CF_EXPORT
89IOHIDElementRef IOHIDElementGetParent(IOHIDElementRef element)
90AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
91
92/*!
93	@function   IOHIDElementGetChildren
94	@abstract   Returns the children for the element.
95    @discussion An element of type kIOHIDElementTypeCollection usually contains children.
96    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
97    @result     Returns an CFArrayRef containing element objects of type IOHIDElementRef.
98*/
99CF_EXPORT
100CFArrayRef IOHIDElementGetChildren(IOHIDElementRef element)
101AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
102
103/*!
104	@function   IOHIDElementAttach
105	@abstract   Establish a relationship between one or more elements.
106    @discussion This is useful for grouping HID elements with related functionality.
107    @param      element The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
108    @param      toAttach The element to be attached. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
109*/
110CF_EXPORT
111void IOHIDElementAttach(IOHIDElementRef element, IOHIDElementRef toAttach)
112AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
113
114/*!
115	@function   IOHIDElementDetach
116	@abstract   Remove a relationship between one or more elements.
117    @discussion This is useful for grouping HID elements with related functionality.
118    @param      element The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
119    @param      toDetach The element to be detached. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
120*/
121CF_EXPORT
122void IOHIDElementDetach(IOHIDElementRef element, IOHIDElementRef toDetach)
123AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
124
125/*!
126	@function   IOHIDElementCopyAttached
127	@abstract   Obtain attached elements.
128    @discussion Attached elements are those that have been grouped via IOHIDElementAttach.
129    @param      element The element to be modified. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
130    @result     Returns a copy of the current attached elements.
131*/
132CF_EXPORT
133CFArrayRef IOHIDElementCopyAttached(IOHIDElementRef element)
134AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
135
136/*!
137	@function   IOHIDElementGetCookie
138	@abstract   Retrieves the cookie for the element.
139    @discussion The IOHIDElementCookie represent a unique identifier for an element within a device.
140    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
141    @result     Returns the IOHIDElementCookie for the element.
142*/
143CF_EXPORT
144IOHIDElementCookie IOHIDElementGetCookie(IOHIDElementRef element)
145AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
146
147/*!
148	@function   IOHIDElementGetType
149	@abstract   Retrieves the type for the element.
150    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
151    @result     Returns the IOHIDElementType for the element.
152*/
153CF_EXPORT
154IOHIDElementType IOHIDElementGetType(IOHIDElementRef element)
155AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
156
157/*!
158	@function   IOHIDElementGetCollectionType
159	@abstract   Retrieves the collection type for the element.
160    @discussion The value returned by this method only makes sense if the element type is kIOHIDElementTypeCollection.
161    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
162    @result     Returns the IOHIDElementCollectionType for the element.
163*/
164CF_EXPORT
165IOHIDElementCollectionType IOHIDElementGetCollectionType(IOHIDElementRef element)
166AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
167
168/*!
169	@function   IOHIDElementGetUsagePage
170	@abstract   Retrieves the usage page for an element.
171    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
172    @result     Returns the usage page for the element.
173*/
174CF_EXPORT
175uint32_t IOHIDElementGetUsagePage(IOHIDElementRef element)
176AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
177
178/*!
179	@function   IOHIDElementGetUsage
180	@abstract   Retrieves the usage for an element.
181    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
182    @result     Returns the usage for the element.
183*/
184CF_EXPORT
185uint32_t IOHIDElementGetUsage(IOHIDElementRef element)
186AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
187
188/*!
189	@function   IOHIDElementIsVirtual
190	@abstract   Returns the virtual property for the element.
191    @discussion Indicates whether the element is a virtual element.
192    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
193    @result     Returns the TRUE if virtual or FALSE if not.
194*/
195CF_EXPORT
196Boolean IOHIDElementIsVirtual(IOHIDElementRef element)
197AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
198
199/*!
200	@function   IOHIDElementIsRelative
201	@abstract   Returns the relative property for the element.
202    @discussion Indicates whether the data is relative (indicating the change in value from the last report) or absolute
203                (based on a fixed origin).
204    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
205    @result     Returns TRUE if relative or FALSE if absolute.
206*/
207CF_EXPORT
208Boolean IOHIDElementIsRelative(IOHIDElementRef element)
209AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
210
211/*!
212	@function   IOHIDElementIsWrapping
213	@abstract   Returns the wrap property for the element.
214    @discussion Wrap indicates whether the data "rolls over" when reaching either the extreme high or low value.
215    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
216    @result     Returns TRUE if wrapping or FALSE if non-wrapping.
217*/
218CF_EXPORT
219Boolean IOHIDElementIsWrapping(IOHIDElementRef element)
220AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
221
222/*!
223	@function   IOHIDElementIsArray
224	@abstract   Returns the array property for the element.
225    @discussion Indicates whether the element represents variable or array data values. Variable values represent data from a
226                physical control.  An array returns an index in each field that corresponds to the pressed button
227                (like keyboard scan codes).
228                <br>
229                <b>Note:</b> The HID Manager will represent most elements as "variable" including the possible usages of an array.
230                Array indices will remain as "array" elements with a usage of 0xffffffff.
231    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
232    @result     Returns TRUE if array or FALSE if variable.
233*/
234CF_EXPORT
235Boolean IOHIDElementIsArray(IOHIDElementRef element)
236AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
237
238/*!
239	@function   IOHIDElementIsNonLinear
240	@abstract   Returns the linear property for the element.
241    @discussion Indicates whether the value for the element has been processed in some way, and no longer represents a linear
242                relationship between what is measured and the value that is reported.
243    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
244    @result     Returns TRUE if non linear or FALSE if linear.
245*/
246CF_EXPORT
247Boolean IOHIDElementIsNonLinear(IOHIDElementRef element)
248AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
249
250/*!
251	@function   IOHIDElementHasPreferredState
252	@abstract   Returns the preferred state property for the element.
253    @discussion Indicates whether the element has a preferred state to which it will return when the user is not physically
254                interacting with the control.
255    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
256    @result     Returns TRUE if preferred state or FALSE if no preferred state.
257*/
258CF_EXPORT
259Boolean IOHIDElementHasPreferredState(IOHIDElementRef element)
260AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
261
262/*!
263	@function   IOHIDElementHasNullState
264	@abstract   Returns the null state property for the element.
265    @discussion Indicates whether the element has a state in which it is not sending meaningful data.
266    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
267    @result     Returns TRUE if null state or FALSE if no null state.
268*/
269CF_EXPORT
270Boolean IOHIDElementHasNullState(IOHIDElementRef element)
271AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
272
273/*!
274	@function   IOHIDElementGetName
275	@abstract   Returns the name for the element.
276    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
277    @result     Returns CFStringRef containing the element name.
278*/
279CF_EXPORT
280CFStringRef IOHIDElementGetName(IOHIDElementRef element)
281AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
282
283/*!
284	@function   IOHIDElementGetReportID
285	@abstract   Returns the report ID for the element.
286    @discussion The report ID represents what report this particular element belongs to.
287    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
288    @result     Returns the report ID.
289*/
290CF_EXPORT
291uint32_t IOHIDElementGetReportID(IOHIDElementRef element)
292AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
293
294/*!
295	@function   IOHIDElementGetReportSize
296	@abstract   Returns the report size in bits for the element.
297    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
298    @result     Returns the report size.
299*/
300CF_EXPORT
301uint32_t IOHIDElementGetReportSize(IOHIDElementRef element)
302AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
303
304/*!
305	@function   IOHIDElementGetReportCount
306	@abstract   Returns the report count for the element.
307    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
308    @result     Returns the report count.
309*/
310CF_EXPORT
311uint32_t IOHIDElementGetReportCount(IOHIDElementRef element)
312AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
313
314/*!
315	@function   IOHIDElementGetUnit
316	@abstract   Returns the unit property for the element.
317    @discussion The unit property is described in more detail in Section 6.2.2.7 of the
318                "Device Class Definition for Human Interface Devices(HID)" Specification, Version 1.11.
319    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
320    @result     Returns the unit.
321*/
322CF_EXPORT
323uint32_t IOHIDElementGetUnit(IOHIDElementRef element)
324AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
325
326/*!
327	@function   IOHIDElementGetUnitExponent
328	@abstract   Returns the unit exponenet in base 10 for the element.
329    @discussion The unit exponent property is described in more detail in Section 6.2.2.7 of the
330                "Device Class Definition for Human Interface Devices(HID)" Specification, Version 1.11.
331    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
332    @result     Returns the unit exponent.
333*/
334CF_EXPORT
335uint32_t IOHIDElementGetUnitExponent(IOHIDElementRef element)
336AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
337
338/*!
339	@function   IOHIDElementGetLogicalMin
340	@abstract   Returns the minimum value possible for the element.
341    @discussion This corresponds to the logical minimun, which indicates the lower bounds of a variable element.
342    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
343    @result     Returns the logical minimum.
344*/
345CF_EXPORT
346CFIndex IOHIDElementGetLogicalMin(IOHIDElementRef element)
347AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
348
349/*!
350	@function   IOHIDElementGetLogicalMax
351	@abstract   Returns the maximum value possible for the element.
352    @discussion This corresponds to the logical maximum, which indicates the upper bounds of a variable element.
353    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
354    @result     Returns the logical maximum.
355*/
356CF_EXPORT
357CFIndex IOHIDElementGetLogicalMax(IOHIDElementRef element)
358AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
359
360/*!
361	@function   IOHIDElementGetPhysicalMin
362	@abstract   Returns the scaled minimum value possible for the element.
363    @discussion Minimum value for the physical extent of a variable element. This represents the value for the logical minimum with units applied to it.
364    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
365    @result     Returns the physical minimum.
366*/
367CF_EXPORT
368CFIndex IOHIDElementGetPhysicalMin(IOHIDElementRef element)
369AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
370
371/*!
372	@function   IOHIDElementGetPhysicalMax
373	@abstract   Returns the scaled maximum value possible for the element.
374    @discussion Maximum value for the physical extent of a variable element.  This represents the value for the logical maximum with units applied to it.
375    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
376    @result     Returns the physical maximum.
377*/
378CF_EXPORT
379CFIndex IOHIDElementGetPhysicalMax(IOHIDElementRef element)
380AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
381
382/*!
383	@function   IOHIDElementGetProperty
384	@abstract   Returns the an element property.
385    @discussion Property keys are prefixed by kIOHIDElement and declared in IOHIDKeys.h.
386    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
387    @param      key The key to be used when querying the element.
388    @result     Returns the property.
389*/
390CF_EXPORT
391CFTypeRef IOHIDElementGetProperty(IOHIDElementRef element, CFStringRef key)
392AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
393
394/*!
395	@function   IOHIDElementSetProperty
396	@abstract   Sets an element property.
397    @discussion This method can be used to set arbitrary element properties, such as application specific references.
398    @param      element The element to be queried. If this parameter is not a valid IOHIDElementRef, the behavior is undefined.
399    @param      key The key to be used when querying the element.
400    @result     Returns TRUE if successful.
401*/
402CF_EXPORT
403Boolean IOHIDElementSetProperty(IOHIDElementRef element, CFStringRef key, CFTypeRef property)
404AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
405
406
407__END_DECLS
408
409#endif /* _IOKIT_HID_IOHIDELEMENT_USER_H */
410