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