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_IOHIDELEMENTEVENT_H
25#define _IOKIT_HID_IOHIDELEMENTEVENT_H
26
27#include <CoreFoundation/CoreFoundation.h>
28#include <IOKit/hid/IOHIDBase.h>
29#include <IOKit/hid/IOHIDKeys.h>
30
31/*!
32	@header IOHIDValue
33    IOHIDValue defines a value at a given time from an parsed item
34    (IOHIDElement) contained within a Human Interface Device (HID) object.  It
35    is used to obtain either integer or data element values along with scaled
36    values based on physical or calibrated settings. IOHIDValue is 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 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
43    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>.
44    Please review documentation before using this reference.
45    <p>
46    All of the information described in this document is contained in the header file <font face="Courier New,Courier,Monaco">IOHIDValue.h</font> found at
47    <font face="Courier New,Courier,Monaco">/System/Library/Frameworks/IOKit.framework/Headers/hid/IOHIDValue.h</font>.
48*/
49
50__BEGIN_DECLS
51
52/*!
53	@function   IOHIDValueGetTypeID
54	@abstract   Returns the type identifier of all IOHIDValue instances.
55*/
56CF_EXPORT
57CFTypeID IOHIDValueGetTypeID(void)
58AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
59
60/*!
61	@function   IOHIDValueCreateWithIntegerValue
62	@abstract   Creates a new element value using an integer value.
63    @discussion IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime.
64                To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h>
65    @param      allocator The CFAllocator which should be used to allocate memory for the value.  This
66                parameter may be NULL in which case the current default CFAllocator is used. If this
67                reference is not a valid CFAllocator, the behavior is undefined.
68    @param      element IOHIDElementRef associated with this value.
69    @param      timeStamp OS absolute time timestamp for this value.
70    @param      value Integer value to be copied to this object.
71    @result     Returns a reference to a new IOHIDValueRef.
72*/
73CF_EXPORT
74IOHIDValueRef IOHIDValueCreateWithIntegerValue(CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, CFIndex value)
75AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
76
77/*!
78	@function   IOHIDValueCreateWithBytes
79	@abstract   Creates a new element value using byte data.
80    @discussion IOHIDValueGetTimeStamp should represent OS AbsoluteTime, not CFAbsoluteTime.
81                To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h>
82    @param      allocator The CFAllocator which should be used to allocate memory for the value.  This
83                parameter may be NULL in which case the current default CFAllocator is used. If this
84                reference is not a valid CFAllocator, the behavior is undefined.
85    @param      element IOHIDElementRef associated with this value.
86    @param      timeStamp OS absolute time timestamp for this value.
87    @param      bytes Pointer to a buffer of uint8_t to be copied to this object.
88    @param      length Number of bytes in the passed buffer.
89    @result     Returns a reference to a new IOHIDValueRef.
90*/
91CF_EXPORT
92IOHIDValueRef IOHIDValueCreateWithBytes(CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, const uint8_t * bytes, CFIndex length)
93AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
94
95/*!
96	@function   IOHIDValueCreateWithBytesNoCopy
97	@abstract   Creates a new element value using byte data without performing a copy.
98    @discussion The timestamp value passed should represent OS AbsoluteTime, not CFAbsoluteTime.
99                To obtain the OS AbsoluteTime, please reference the APIs declared in <mach/mach_time.h>
100    @param      allocator The CFAllocator which should be used to allocate memory for the value.  This
101                parameter may be NULL in which case the current default CFAllocator is used. If this
102                reference is not a valid CFAllocator, the behavior is undefined.
103    @param      element IOHIDElementRef associated with this value.
104    @param      timeStamp OS absolute time timestamp for this value.
105    @param      bytes Pointer to a buffer of uint8_t to be referenced by this object.
106    @param      length Number of bytes in the passed buffer.
107    @result     Returns a reference to a new IOHIDValueRef.
108*/
109CF_EXPORT
110IOHIDValueRef IOHIDValueCreateWithBytesNoCopy(CFAllocatorRef allocator, IOHIDElementRef element, uint64_t timeStamp, const uint8_t * bytes, CFIndex length)
111AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
112
113/*!
114	@function   IOHIDValueGetElement
115	@abstract   Returns the element value associated with this IOHIDValueRef.
116    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
117    @result     Returns a IOHIDElementRef referenced by this value.
118*/
119CF_EXPORT
120IOHIDElementRef IOHIDValueGetElement(IOHIDValueRef value)
121AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
122
123/*!
124	@function   IOHIDValueGetTimeStamp
125	@abstract   Returns the timestamp value contained in this IOHIDValueRef.
126    @discussion The timestamp value returned represents OS AbsoluteTime, not CFAbsoluteTime.
127    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
128    @result     Returns a uint64_t representing the timestamp of this value.
129*/
130CF_EXPORT
131uint64_t IOHIDValueGetTimeStamp(IOHIDValueRef value)
132AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
133
134/*!
135	@function   IOHIDValueGetLength
136	@abstract   Returns the size, in bytes, of the value contained in this IOHIDValueRef.
137    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
138    @result     Returns length of the value.
139*/
140CF_EXPORT
141CFIndex IOHIDValueGetLength(IOHIDValueRef value)
142AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
143
144/*!
145	@function   IOHIDValueGetBytePtr
146	@abstract   Returns a byte pointer to the value contained in this IOHIDValueRef.
147    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
148    @result     Returns a pointer to the value.
149*/
150CF_EXPORT
151const uint8_t * IOHIDValueGetBytePtr(IOHIDValueRef value)
152AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
153
154/*!
155	@function   IOHIDValueGetIntegerValue
156	@abstract   Returns an integer representaion of the value contained in this IOHIDValueRef.
157    @discussion The value is based on the logical element value contained in the report returned by the device.
158    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
159    @result     Returns an integer representation of the value.
160*/
161CF_EXPORT
162CFIndex IOHIDValueGetIntegerValue(IOHIDValueRef value)
163AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
164
165/*!
166	@function   IOHIDValueGetScaledValue
167	@abstract   Returns an scaled representaion of the value contained in this IOHIDValueRef based on the scale type.
168    @discussion The scaled value is based on the range described by the scale type's min and max, such that:
169        <br>
170        scaledValue = ((value - min) * (scaledMax - scaledMin) / (max - min)) + scaledMin
171        <br>
172        <b>Note:</b>
173        <br>
174        There are currently two types of scaling that can be applied:
175        <ul>
176        <li><b>kIOHIDValueScaleTypePhysical</b>: Scales element value using the physical bounds of the device such that <b>scaledMin = physicalMin</b> and <b>scaledMax = physicalMax</b>.
177        <li><b>kIOHIDValueScaleTypeCalibrated</b>: Scales element value such that <b>scaledMin = -1</b> and <b>scaledMax = 1</b>.  This value will also take into account the calibration properties associated with this element.
178        </ul>
179    @param      value The value to be queried. If this parameter is not a valid IOHIDValueRef, the behavior is undefined.
180    @param      type The type of scaling to be performed.
181    @result     Returns an scaled floating point representation of the value.
182*/
183CF_EXPORT
184double_t IOHIDValueGetScaledValue(IOHIDValueRef value, IOHIDValueScaleType type)
185AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER;
186
187__END_DECLS
188
189#endif /* _IOKIT_HID_IOHIDELEMENTEVENT_H */
190