1/* 2 * @APPLE_LICENSE_HEADER_START@ 3 * 4 * Copyright (c) 1999-2012 Apple Computer, Inc. All Rights Reserved. 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#ifndef __IOHIDDescriptorParser__ 24#define __IOHIDDescriptorParser__ 25 26#include <TargetConditionals.h> 27#include <IOKit/IOTypes.h> 28#include <IOKit/hidsystem/IOHIDUsageTables.h> 29 30#ifdef __cplusplus 31extern "C" { 32#endif 33 34#if TARGET_OS_EMBEDDED 35/* Types and enums required by these functions but not in IOTypes.h */ 36 37typedef UInt8 Byte; 38typedef SInt8 SignedByte; 39typedef unsigned long FourCharCode; 40typedef FourCharCode OSType; 41 42enum { 43 noErr = 0 44}; 45#endif 46 47/* End missing types and enums */ 48 49enum 50{ 51 kHIDSuccess = 0, 52 53/* HID assigned error numbers are -13949 .. -13900 */ 54 kHIDBaseError = -13950, 55 56 kHIDNullStateErr, 57 kHIDBufferTooSmallErr, 58 kHIDValueOutOfRangeErr, 59 kHIDUsageNotFoundErr, 60 kHIDNotValueArrayErr, 61 kHIDInvalidPreparsedDataErr, 62 kHIDIncompatibleReportErr, 63 kHIDBadLogPhysValuesErr, 64 kHIDInvalidReportTypeErr, 65 kHIDInvalidReportLengthErr, 66 kHIDNullPointerErr, 67 kHIDBadParameterErr, 68 kHIDNotEnoughMemoryErr, 69 kHIDEndOfDescriptorErr, 70 kHIDUsagePageZeroErr, 71 kHIDBadLogicalMinimumErr, 72 kHIDBadLogicalMaximumErr, 73 kHIDInvertedLogicalRangeErr, 74 kHIDInvertedPhysicalRangeErr, 75 kHIDUnmatchedUsageRangeErr, 76 kHIDInvertedUsageRangeErr, 77 kHIDUnmatchedStringRangeErr, 78 kHIDUnmatchedDesignatorRangeErr, 79 kHIDReportSizeZeroErr, 80 kHIDReportCountZeroErr, 81 kHIDReportIDZeroErr, 82 kHIDInvalidRangePageErr, 83 84 // 85 // HID device driver errors 86 // 87 88 kHIDDeviceNotReady = -13910, // The device is still initializing, try again later 89 kHIDVersionIncompatibleErr, 90}; 91 92// types of HID reports (input, output, feature) 93enum 94{ 95 kHIDInputReport = 1, 96 kHIDOutputReport, 97 kHIDFeatureReport, 98 kHIDUnknownReport = 255 99}; 100 101// flags passed to HIDOpenReportDescriptor 102enum 103{ 104 kHIDFlag_StrictErrorChecking = 0x00000001 105}; 106 107typedef UInt32 HIDReportType; 108typedef UInt32 HIDUsage; 109 110typedef void *HIDPreparsedDataRef; 111 112/*! 113 @typedef HIDUsageAndPage 114 @abstract The HIDUsageAndPage data structure is used by HID clients when obtaining status of buttons to hold the usage page and usage of a button that is down. 115 @discussion Clients use the HIDUSageAndPage structure with the HIDGetButtonsEx function to obtain both the usage page and usage identifiers of each button that is down. 116 @field usage Specifies the usage identifier within the usage page specified by usagePage of a button that is down. 117 @field usagePage Specifies the usage page identifier of a button that is down. 118 */ 119struct HIDUsageAndPage 120{ 121 HIDUsage usage; 122 HIDUsage usagePage; 123}; 124typedef struct HIDUsageAndPage HIDUsageAndPage, *HIDUsageAndPagePtr; 125 126/*! 127 @typedef HIDCaps 128 @abstract The HIDCaps data structure is used by HID clients to hold the capabilities of a HID device. 129 @discussion This structure holds the parsed capabilities and data maximums returned for a device by the HIDGetCaps function. 130 @field usage Specifies the specific class of functionality that this device provides. This value is dependent and specific to the value provided in the usagePage field. For example, a keyboard could have a usagePage of kHIDUsagePage_Generic and a usage of kHIDUsage_Generic_Keyboard. 131 @field usagePage Specifies the usage page identifier for this top level collection. 132 @field inputReportByteLength Specifies the maximum length, in bytes, of an input report for this device, including the report ID which is unilaterally prepended to the device data. 133 @field outputReportByteLength Specifies the maximum length, in bytes, of an output report for this device, including the report ID which is unilaterally prepended to the device data. 134 @field featureReportByteLength Specifies the maximum length, in bytes, of a feature report for this device, including the report ID which is unilaterally prepended to the device data. 135 @field numberCollectionNodes Specifies the number of HIDCollectionNode structures that are returned for this top level collection by the HIDGetConnectionNodes function. 136 @field numberInputButtonCaps Specifies the number of input buttons. 137 @field numberInputValueCaps Specifies the number of input values. 138 @field numberOutputButtonCaps Specifies the number of output buttons. 139 @field numberOutputValueCaps Specifies the number of output values 140 @field numberFeatureButtonCaps Specifies the number of feature buttons. 141 @field numberFeatureValueCaps Specifies the number of feature values. 142 */ 143struct HIDCaps 144{ 145 HIDUsage usage; 146 HIDUsage usagePage; 147 IOByteCount inputReportByteLength; 148 IOByteCount outputReportByteLength; 149 IOByteCount featureReportByteLength; 150 UInt32 numberCollectionNodes; 151 UInt32 numberInputButtonCaps; 152 UInt32 numberInputValueCaps; 153 UInt32 numberOutputButtonCaps; 154 UInt32 numberOutputValueCaps; 155 UInt32 numberFeatureButtonCaps; 156 UInt32 numberFeatureValueCaps; 157}; 158typedef struct HIDCaps HIDCaps, * HIDCapsPtr; 159 160struct HIDCapabilities { 161 HIDUsage usage; 162 HIDUsage usagePage; 163 IOByteCount inputReportByteLength; 164 IOByteCount outputReportByteLength; 165 IOByteCount featureReportByteLength; 166 UInt32 numberCollectionNodes; 167 UInt32 numberInputButtonCaps; 168 UInt32 numberInputValueCaps; 169 UInt32 numberOutputButtonCaps; 170 UInt32 numberOutputValueCaps; 171 UInt32 numberFeatureButtonCaps; 172 UInt32 numberFeatureValueCaps; 173}; 174typedef struct HIDCapabilities HIDCapabilities, * HIDCapabilitiesPtr; 175 176 177struct HIDCollectionNode 178{ 179 HIDUsage collectionUsage; 180 HIDUsage collectionUsagePage; 181 UInt32 parent; 182 UInt32 numberOfChildren; 183 UInt32 nextSibling; 184 UInt32 firstChild; 185}; 186typedef struct HIDCollectionNode HIDCollectionNode, * HIDCollectionNodePtr; 187 188struct HIDButtonCaps 189{ 190 HIDUsage usagePage; 191 UInt32 reportID; 192 UInt32 bitField; 193 UInt32 collection; 194 HIDUsage collectionUsage; 195 HIDUsage collectionUsagePage; 196 Boolean isRange; 197 Boolean isStringRange; 198 Boolean isDesignatorRange; 199 Boolean isAbsolute; 200 SInt32 startBit; // Added esb 9-29-99 201 202 union 203 { 204 struct 205 { 206 HIDUsage usageMin; 207 HIDUsage usageMax; 208 UInt32 stringMin; 209 UInt32 stringMax; 210 UInt32 designatorMin; 211 UInt32 designatorMax; 212 } range; 213 struct 214 { 215 HIDUsage usage; 216 HIDUsage reserved1; 217 UInt32 stringIndex; 218 UInt32 reserved2; 219 UInt32 designatorIndex; 220 UInt32 reserved3; 221 } notRange; 222 } u; 223}; 224typedef struct HIDButtonCaps HIDButtonCaps, * HIDButtonCapsPtr; 225 226struct HIDButtonCapabilities 227{ 228 HIDUsage usagePage; 229 UInt32 reportID; 230 UInt32 bitField; 231 UInt32 collection; 232 HIDUsage collectionUsage; 233 HIDUsage collectionUsagePage; 234 Boolean isRange; 235 Boolean isStringRange; 236 Boolean isDesignatorRange; 237 Boolean isAbsolute; 238 239 SInt32 unitExponent; // Added KH 1/25/01 240 SInt32 units; // Added KH 1/25/01 241// UInt32 reserved; // Not added KH 1/25/01 242 SInt32 startBit; // Added esb 9-29-99 243 UInt32 pbVersion; // Added KH 1/25/01 244 245 union 246 { 247 struct 248 { 249 HIDUsage usageMin; 250 HIDUsage usageMax; 251 UInt32 stringMin; 252 UInt32 stringMax; 253 UInt32 designatorMin; 254 UInt32 designatorMax; 255 } range; 256 struct 257 { 258 HIDUsage usage; 259 HIDUsage reserved1; 260 UInt32 stringIndex; 261 UInt32 reserved2; 262 UInt32 designatorIndex; 263 UInt32 reserved3; 264 } notRange; 265 } u; 266}; 267typedef struct HIDButtonCapabilities HIDButtonCapabilities, * HIDButtonCapabilitiesPtr; 268 269struct HIDValueCaps 270{ 271 HIDUsage usagePage; 272 UInt32 reportID; 273 UInt32 bitField; 274 UInt32 collection; 275 HIDUsage collectionUsage; 276 HIDUsage collectionUsagePage; 277 278 Boolean isRange; 279 Boolean isStringRange; 280 Boolean isDesignatorRange; 281 Boolean isAbsolute; 282 283 UInt32 startBit; // Added by esb 9-28-99 284 UInt32 bitSize; 285 UInt32 reportCount; 286 287 SInt32 logicalMin; 288 SInt32 logicalMax; 289 SInt32 physicalMin; 290 SInt32 physicalMax; 291 292 union 293 { 294 struct 295 { 296 HIDUsage usageMin; 297 HIDUsage usageMax; 298 UInt32 stringMin; 299 UInt32 stringMax; 300 UInt32 designatorMin; 301 UInt32 designatorMax; 302 } range; 303 struct 304 { 305 HIDUsage usage; 306 HIDUsage reserved1; 307 UInt32 stringIndex; 308 UInt32 reserved2; 309 UInt32 designatorIndex; 310 UInt32 reserved3; 311 } notRange; 312 } u; 313}; 314typedef struct HIDValueCaps HIDValueCaps, * HIDValueCapsPtr; 315 316struct HIDValueCapabilities 317{ 318 HIDUsage usagePage; 319 UInt32 reportID; 320 UInt32 bitField; 321 UInt32 collection; 322 HIDUsage collectionUsage; 323 HIDUsage collectionUsagePage; 324 325 Boolean isRange; 326 Boolean isStringRange; 327 Boolean isDesignatorRange; 328 Boolean isAbsolute; 329 330 UInt32 bitSize; 331 UInt32 reportCount; 332 333 SInt32 logicalMin; 334 SInt32 logicalMax; 335 SInt32 physicalMin; 336 SInt32 physicalMax; 337 338 SInt32 unitExponent; // Added KH 1/25/01 339 SInt32 units; // Added KH 1/25/01 340// UInt32 reserved; // Not added KH 1/25/01 341 SInt32 startBit; // Added esb 9-29-99 // Moved here KH 1/25/01 342 UInt32 pbVersion; // Added KH 1/25/01 343 344 union 345 { 346 struct 347 { 348 HIDUsage usageMin; 349 HIDUsage usageMax; 350 UInt32 stringMin; 351 UInt32 stringMax; 352 UInt32 designatorMin; 353 UInt32 designatorMax; 354 } range; 355 struct 356 { 357 HIDUsage usage; 358 HIDUsage reserved1; 359 UInt32 stringIndex; 360 UInt32 reserved2; 361 UInt32 designatorIndex; 362 UInt32 reserved3; 363 } notRange; 364 } u; 365}; 366typedef struct HIDValueCapabilities HIDValueCapabilities, * HIDValueCapabilitiesPtr; 367 368/*! 369 @function HIDOpenReportDescriptor 370 @abstract The HIDOpenReportDescriptor function allocates the memory the parser needs to handle the given report descriptor, and then parses the report descriptor. 371 @discussion When the parsed information is no longer needed, clients should call the HIDCloseReportDescriptor function. 372 @param hidReportDescriptor Contains a pointer to the actual HID report descriptor from the USB device's firmware 373 @param descriptorLength The length of the HID report descriptor 374 @param preparsedDataRef Preparsed data reference to be used for subsequent function calls 375 @param flags Flags for this runction are kHIDFlag_StrictErrorChecking = 0x00000001 376 @result OSStatus Returns an error code if an error was encountered or noErr on success. 377 */ 378 379extern 380OSStatus 381HIDOpenReportDescriptor (void * hidReportDescriptor, 382 IOByteCount descriptorLength, 383 HIDPreparsedDataRef * preparsedDataRef, 384 UInt32 flags); 385 386/*! 387 @function HIDCloseReportDescriptor 388 @abstract Disposes of the memory the parser allocated for the HIDOpenReportDescriptor function. 389 @param hidReportDescriptor Contains a pointer to the actual HID report descriptor from the USB device's firmware 390 @param preparsedDataRef Preparsed data reference for the report that is returned by the HIDOpenReportDescriptor function. After making a call to the HIDCloseReportDescriptor function, the preparsedDataRef is invalid and should not be used. 391 @result OSStatus Returns an error code if an error was encountered or noErr on success. 392 */ 393 394extern 395OSStatus 396HIDCloseReportDescriptor (HIDPreparsedDataRef preparsedDataRef); 397 398/*! 399 @function HIDGetButtonCaps 400 @abstract Returns the button capabilities structures for a HID device based on the given preparsed data. 401 @param reportType Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport 402 @param buttonCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria 403 @param buttonCapsSize Contains the size of the buttonCaps array passed in to the function and is set to the number of elements actually placed in the array after the call completes. 404 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 405 @result OSStatus Returns an error code if an error was encountered or noErr on success. 406 */ 407 408extern 409OSStatus 410HIDGetButtonCaps (HIDReportType reportType, 411 HIDButtonCapsPtr buttonCaps, 412 UInt32 * buttonCapsSize, 413 HIDPreparsedDataRef preparsedDataRef); 414 415/*! 416 @function HIDGetButtonCapabilities 417 @abstract Returns the button capabilities structures for a HID device based on the given preparsed data. 418 @param reportType Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport 419 @param buttonCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCapabilities structures. The structures contain information for all buttons that meet the search criteria 420 @param buttonCapsSize Contains the size of the buttonCaps array passed in to the function and is set to the number of elements actually placed in the array after the call completes. 421 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 422 @result OSStatus Returns an error code if an error was encountered or noErr on success. 423 */ 424 425extern 426OSStatus 427HIDGetButtonCapabilities (HIDReportType reportType, 428 HIDButtonCapabilitiesPtr buttonCaps, 429 UInt32 * buttonCapsSize, 430 HIDPreparsedDataRef preparsedDataRef); 431 432/*! 433 @function HIDGetCaps 434 @abstract Returns the capabilities of a HID device based on the given preparsed data. 435 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 436 @param capabilities Points to a caller allocated buffer, that upon return contains the parsed capability information for this HID device. 437 @result OSStatus Returns an error code if an error was encountered or noErr on success. 438 */ 439 440extern 441OSStatus 442HIDGetCaps (HIDPreparsedDataRef preparsedDataRef, 443 HIDCapsPtr capabilities); 444 445/*! 446 @function HIDGetCapabilities 447 @abstract Returns the capabilities of a HID device based on the given preparsed data. 448 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 449 @param capabilities Points to a caller allocated buffer, that upon return contains the parsed capability information for this HID device. 450 @result OSStatus Returns an error code if an error was encountered or noErr on success. 451 */ 452 453extern 454OSStatus 455HIDGetCapabilities (HIDPreparsedDataRef preparsedDataRef, 456 HIDCapabilitiesPtr capabilities); 457 458/*! 459 @function HIDGetCollectionNodes 460 @abstract Returns an array of HIDCollectionNode structures that describe the relationships and layout of the link collections within this top level collection. 461 @discussion The length of the buffer required, in array elements, for an entire collection node array is found in the HIDCaps structure member numberCollectionNodes. You obtain the HIDCaps information by calling the HIDGetCaps function. For information on the relationships of link collections described by the data returned from this routine, see the descripton of the HIDCollectionNode structure. 462 @param collectionNodes Points to a caller-allocated array of HIDCollectionNode structures in which this routine returns an entry for each collection within the top level collection. A collection is a group of corresponding HID descriptors containing input, output, and feature items that have some common relationship to one another. For example, a pointer collection contains items for x and y position data, and button data. 463 @param collectionNodesSize On input, specifies the length in array elements of the buffer provided at collectionNodes. On output, this parameter is set to the number of entries in the collectionNodes array that were initialized. 464 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 465 @result OSStatus Returns an error code if an error was encountered or noErr on success. 466 */ 467 468extern 469OSStatus 470HIDGetCollectionNodes (HIDCollectionNodePtr collectionNodes, 471 UInt32 * collectionNodesSize, 472 HIDPreparsedDataRef preparsedDataRef); 473 474/*! 475 @function HIDGetScaledUsageValue 476 @abstract The HIDGetScaledUsageValue function returns the capabilities for all buttons for a given top level collection. 477 @discussion Clients who which to obtain all capabilities for a usage that contains multiple data items for a single usage that corresponds to a HID byte array, must call the HIDGetUsageValueArray function. 478 @param reportType Specifies the type of report for which to retrieve the scaled value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 479 @param usagePage Specifies the usage page of the value to be retrieved. 480 @param collection Optionally specifies the link collection identifier of the value to be retrieved. 481 @param usage Specifies the usage of the scaled value to be retrieved. 482 @param usageValue Points to a variable, that on return from this routine holds the scaled value retrieved from the device report. 483 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 484 @param report Points to the caller-allocated buffer that contains the device report data 485 @param reportLength Specifies the length, in bytes, of the report data provided at report 486 @result OSStatus Returns an error code if an error was encountered or noErr on success. 487 */ 488 489extern 490OSStatus 491HIDGetScaledUsageValue (HIDReportType reportType, 492 HIDUsage usagePage, 493 UInt32 collection, 494 HIDUsage usage, 495 SInt32 * usageValue, 496 HIDPreparsedDataRef preparsedDataRef, 497 void * report, 498 IOByteCount reportLength); 499 500/*! 501 @function HIDGetSpecificButtonCaps 502 @abstract Retrieves the capabilities for all buttons in a specific type of report that meet the search criteria. 503 @discussion The HIDGetSpecificButtonCaps function retrieves capability data for buttons that meet a given search criteria, as opposed to the HIDGetButtonCaps function which returns the capability data for all buttons on the device. Calling this routine specifying zero for usagePage, usage and collection is equivalent to calling the HIDGetButtonCaps function. 504 @param reportType Specifies the type of report for which to retrieve the button capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 505 @param usagePage Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only buttons that specify this usage page will be retrieved. 506 @param collection Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only buttons that are part of the specified link collection are retrieved. 507 @param usage Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only buttons that match the value specified are retrieved. 508 @param buttonCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCaps structures. The structures contain information for all buttons that meet the search criteria. 509 @param buttonCapsLength On input, specifies the length, in array elements, of the buffer provided in the buttonCaps parameter. On output, this parameter is set to the actual number of elements that were returned by the function call, in the buffer provided in the buttonCaps parameter, if the routine completed without error. The correct length necessary to retrieve the button capabilities can be found in the capability data returned for the device by the HIDGetCaps function. 510 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 511 @result OSStatus Returns an error code if an error was encountered or noErr on success. 512 */ 513 514extern 515OSStatus 516HIDGetSpecificButtonCaps (HIDReportType reportType, 517 HIDUsage usagePage, 518 UInt32 collection, 519 HIDUsage usage, 520 HIDButtonCapsPtr buttonCaps, 521 UInt32 * buttonCapsSize, 522 HIDPreparsedDataRef preparsedDataRef); 523 524/*! 525 @function HIDGetSpecificButtonCapabilities 526 @abstract Retrieves the capabilities for all buttons in a specific type of report that meet the search criteria. 527 @discussion The HIDGetSpecificButtonCapabilities function retrieves capability data for buttons that meet a given search criteria, as opposed to the HIDGetButtonCapabilities function which returns the capability data for all buttons on the device. Calling this routine specifying zero for usagePage, usage and collection is equivalent to calling the HIDGetButtonCapabilities function. 528 @param reportType Specifies the type of report for which to retrieve the button capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 529 @param usagePage Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only buttons that specify this usage page will be retrieved. 530 @param collection Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only buttons that are part of the specified link collection are retrieved. 531 @param usage Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only buttons that match the value specified are retrieved. 532 @param buttonCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDButtonCapabilities structures. The structures contain information for all buttons that meet the search criteria. 533 @param buttonCapsLength On input, specifies the length, in array elements, of the buffer provided in the buttonCaps parameter. On output, this parameter is set to the actual number of elements that were returned by the function call, in the buffer provided in the buttonCaps parameter, if the routine completed without error. The correct length necessary to retrieve the button capabilities can be found in the capability data returned for the device by the HIDGetCaps function. 534 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 535 @result OSStatus Returns an error code if an error was encountered or noErr on success. 536 */ 537 538extern 539OSStatus 540HIDGetSpecificButtonCapabilities (HIDReportType reportType, 541 HIDUsage usagePage, 542 UInt32 collection, 543 HIDUsage usage, 544 HIDButtonCapabilitiesPtr buttonCaps, 545 UInt32 * buttonCapsSize, 546 HIDPreparsedDataRef preparsedDataRef); 547 548/*! 549 @function HIDGetSpecificValueCaps 550 @abstract Retrieves the capabilities for all values in a specific type of report that meet the search criteria. 551 @discussion The HIDGetSpecificValueCaps function retrieves capability data for values that meet given search criteria, as opposed to the HIDGetValueCaps function, which returns the capability data for all values on the device. Calling this routine with a value of zero for usagePage, usage and collection parameters is equivalent to calling the HIDGetValueCaps function. 552 @param reportType Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport. 553 @param usagePage Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage page will be retrieved. 554 @param collection Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only values that are part of this link collection will be retrieved. 555 @param usage Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage will be retrieved. 556 @param valueCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDValueCaps structures that contain information for all values that meet the search criteria. 557 @param valueCapsSize Specifies the length on input, in array elements, of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned by this function call, in the buffer provided in the valueCaps parameter, if the routine completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device from the HIDGetCaps function. 558 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 559 @result OSStatus Returns an error code if an error was encountered or noErr on success. 560 */ 561 562extern 563OSStatus 564HIDGetSpecificValueCaps (HIDReportType reportType, 565 HIDUsage usagePage, 566 UInt32 collection, 567 HIDUsage usage, 568 HIDValueCapsPtr valueCaps, 569 UInt32 * valueCapsSize, 570 HIDPreparsedDataRef preparsedDataRef); 571 572/*! 573 @function HIDGetSpecificValueCapabilities 574 @abstract Retrieves the capabilities for all values in a specific type of report that meet the search criteria. 575 @discussion The HIDGetSpecificValueCapabilities function retrieves capability data for values that meet given search criteria, as opposed to the HIDGetValueCapabilities function, which returns the capability data for all values on the device. Calling this routine with a value of zero for usagePage, usage and collection parameters is equivalent to calling the HIDGetValueCapabilities function. 576 @param reportType Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport. 577 @param usagePage Specifies a usage page identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage page will be retrieved. 578 @param collection Specifies a link collection identifier to use as a search criteria. If this parameter is non-zero, then only values that are part of this link collection will be retrieved. 579 @param usage Specifies a usage identifier to use as a search criteria. If this parameter is non-zero, then only values that specify this usage will be retrieved. 580 @param valueCaps Points to a caller-allocated buffer that will contain, on return, an array of HIDValueCapabilities structures that contain information for all values that meet the search criteria. 581 @param valueCapsSize Specifies the length on input, in array elements, of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned by this function call, in the buffer provided in the valueCaps parameter, if the routine completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device from the HIDGetCaps function. 582 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 583 @result OSStatus Returns an error code if an error was encountered or noErr on success. 584 */ 585 586extern 587OSStatus 588HIDGetSpecificValueCapabilities (HIDReportType reportType, 589 HIDUsage usagePage, 590 UInt32 collection, 591 HIDUsage usage, 592 HIDValueCapabilitiesPtr valueCaps, 593 UInt32 * valueCapsSize, 594 HIDPreparsedDataRef preparsedDataRef); 595 596/*! 597 @function HIDGetButtonsOnPage 598 @abstract Retrieves the button stat information for buttons on a specified usage page. 599 @param reportType Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport. 600 @param usagePage Specifies the usage page of the buttons for which to retrieve the current state. 601 @param collection Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned. 602 @param usageList On return, points to a caller-allocated buffer that contains the usages of all the buttons that are perssed and belong to the usage page specified in the usagePage parameter. 603 @param usageListSize Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferTooSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function. 604 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 605 @param report Points to the caller-allocated buffer that contains the device report data 606 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter 607 @result OSStatus Returns an error code if an error was encountered or noErr on success. 608 */ 609 610extern 611OSStatus 612HIDGetButtonsOnPage (HIDReportType reportType, 613 HIDUsage usagePage, 614 UInt32 collection, 615 HIDUsage * usageList, 616 UInt32 * usageListSize, 617 HIDPreparsedDataRef preparsedDataRef, 618 void * report, 619 IOByteCount reportLength); 620 621/*! 622 @function HIDGetButtons 623 @abstract The HIDGetButtons function takes a report from a HID device and gets the current state of the buttons in that report. 624 @param reportType Specifies the type of report, provided in the report parameter, from which to retrieve the buttons. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport or kHIDFeatureReport 625 @param collection Optionally specifies the link collection identifier used to retrieve only specific button states. If this value is non-zero, only the buttons that are part of the given collection are returned. 626 @param usageList On return, points to a caller-allocated buffer that contains the usages of all the buttons that are pressed. 627 @param usageListSize Is the size, in array elements, of the buffer provided in the usageList parameter. On return, this parameter contains the number of button states that were set by this routine. If the error kHIDBufferToSmallErr was returned, this parameter contains the number of array elements required to hold all button data requested. The maximum number of buttons that can ever be returned for a given type of report can be obtained by calling the HIDMaxUsageListLength function. 628 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 629 @param report Points to the caller-allocated buffer that contains the device report data. 630 @param reportLength Specifies the length, in bytes, of the report data provided in the report parameter. 631 @result OSStatus Returns an error code if an error was encountered or noErr on success. 632 */ 633 634extern 635OSStatus 636HIDGetButtons (HIDReportType reportType, 637 UInt32 collection, 638 HIDUsageAndPagePtr usageList, 639 UInt32 * usageListSize, 640 HIDPreparsedDataRef preparsedDataRef, 641 void * report, 642 IOByteCount reportLength); 643 644extern 645OSStatus 646HIDGetNextButtonInfo (HIDReportType reportType, 647 HIDUsage usagePage, 648 HIDUsage usage, 649 UInt32 * collection, 650 UInt8 * reportID, 651 HIDPreparsedDataRef preparsedDataRef); 652 653extern 654OSStatus 655HIDGetNextUsageValueInfo (HIDReportType reportType, 656 HIDUsage usagePage, 657 HIDUsage usage, 658 UInt32 * collection, 659 UInt8 * reportID, 660 HIDPreparsedDataRef preparsedDataRef); 661 662extern 663OSStatus 664HIDGetReportLength (HIDReportType reportType, 665 UInt8 reportID, 666 IOByteCount *reportLength, 667 HIDPreparsedDataRef preparsedDataRef); 668 669/*! 670 @function HIDGetUsageValue 671 @abstract The HIDGetUsageValue function returns a value from a device data report given a selected search criteria. 672 @discussion The HIDGetUsageValue function does not sign the value. To have the sign bit automatically applied, use the HIDGetScaledUsageValue function instead. For manually assigning the sign bit, the position of the sign bit can be found in the HIDValueCaps structure for this value. Clients who wish to obtain all data for a usage that contains multiple data items for a single usage, corresponding to a HID byte array, must call the HIDGetUsageValueArray function instead. 673 @param reportType Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 674 @param usagePage Specifies the usage page of the value to retrieve. 675 @param collection Optionally specifies the link collection identifier of the value to be retrieved. 676 @param usage Specifies the usage of the value to be retrieved. 677 @param usageValue Points to a variable, that on return from this routine holds the value retrieved from the device report. 678 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 679 @param report Points to the caller-allocated buffer that contains the device report data. 680 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter. 681 @result OSStatus Returns an error code if an error was encountered or noErr on success. 682 */ 683 684extern 685OSStatus 686HIDGetUsageValue (HIDReportType reportType, 687 HIDUsage usagePage, 688 UInt32 collection, 689 HIDUsage usage, 690 SInt32 * usageValue, 691 HIDPreparsedDataRef preparsedDataRef, 692 void * report, 693 IOByteCount reportLength); 694 695/*! 696 @function HIDGetUsageValueArray 697 @abstract The HIDGetUsageValueArray function returns a value from a device data report given a selected search criteria. 698 @discussion When the HIDGetUsageValueArray function retrieves the data, it fills in the buffer in little-endian order beginning with the least significant bit of the data for this usage. The data is filled in without regard to byte alignment and is shifted such that the least significant bit is placed as the 1st bit of the given buffer. 699 @param reportType Specifies the type of report, provided in report, from which to retrieve the value. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 700 @param usagePage Specifies the usage page of the data to be retrieved. 701 @param collection Optionally specifies the link collection identifier of the data to be retrieved. 702 @param usage Specifies the usage identifier of the value to be retrieved. 703 @param usageValueBuffer Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for the value and rounding the resulting value up to the nearest byte. 704 @param usageValueBufferSize Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter. 705 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 706 @param report Points to the caller-allocated buffer that contains the device report data. 707 @param reportLength Specifies the size, in bytes, of the report data provided in report. 708 @result OSStatus Returns an error code if an error was encountered or noErr on success. 709 */ 710 711extern 712OSStatus 713HIDGetUsageValueArray (HIDReportType reportType, 714 HIDUsage usagePage, 715 UInt32 collection, 716 HIDUsage usage, 717 UInt8 * usageValueBuffer, 718 IOByteCount usageValueBufferSize, 719 HIDPreparsedDataRef preparsedDataRef, 720 void * report, 721 IOByteCount reportLength); 722 723/*! 724 @function HIDGetValueCaps 725 @abstract The HIDGetValueCaps function retrieves the capabilities for all values for a specified top level collection. 726 @discussion The HIDGetValueCaps function retrieves the capability data for all values in a top level collection without regard for the usage, usage page or collection of the value. To retrieve value capabilities for a specific usage, usage page or collection, use the HIDGetSpecificValueCaps function. 727 @param reportType Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 728 @param valueCaps On return, points to a caller-allocated buffer that contains an array of HIDValueCaps structures containing information for all values in the top level collection. 729 @param valueCapsSize On input, specifies the size in array elements of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned in the buffer provided in the valueCaps parameter, if the function completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device by the HIDGetCaps function. 730 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 731 @result OSStatus Returns an error code if an error was encountered or noErr on success. 732 */ 733 734extern 735OSStatus 736HIDGetValueCaps (HIDReportType reportType, 737 HIDValueCapsPtr valueCaps, 738 UInt32 * valueCapsSize, 739 HIDPreparsedDataRef preparsedDataRef); 740 741/*! 742 @function HIDGetValueCapabilities 743 @abstract The HIDGetValueCapabilities function retrieves the capabilities for all values for a specified top level collection. 744 @discussion The HIDGetValueCapabilities function retrieves the capability data for all values in a top level collection without regard for the usage, usage page or collection of the value. To retrieve value capabilities for a specific usage, usage page or collection, use the HIDGetSpecificValueCapabilities function. 745 @param reportType Specifies the type of report for which to retrieve the value capabilities. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 746 @param valueCaps On return, points to a caller-allocated buffer that contains an array of HIDValueCapabilities structures containing information for all values in the top level collection. 747 @param valueCapsSize On input, specifies the size in array elements of the buffer provided in the valueCaps parameter. On output, this parameter is set to the actual number of elements that were returned in the buffer provided in the valueCaps parameter, if the function completed without error. The correct length necessary to retrieve the value capabilities can be found in the capability data returned for the device by the HIDGetCapabilities function. 748 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 749 @result OSStatus Returns an error code if an error was encountered or noErr on success. 750 */ 751 752extern 753OSStatus 754HIDGetValueCapabilities (HIDReportType reportType, 755 HIDValueCapabilitiesPtr valueCaps, 756 UInt32 * valueCapsSize, 757 HIDPreparsedDataRef preparsedDataRef); 758 759extern 760OSStatus 761HIDInitReport (HIDReportType reportType, 762 UInt8 reportID, 763 HIDPreparsedDataRef preparsedDataRef, 764 void * report, 765 IOByteCount reportLength); 766 767/*! 768 @function HIDMaxUsageListLength 769 @abstract The HIDMaxUsageListLength function returns the maximum number of buttons that can be returned from a given report type for the top level collection. 770 @param reportType Specifies the type of report for which to get a maximum usage count. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 771 @param usagePage Optionally specifies the usage page identifier to use as a search criteria. If this parameter is zero, the function returns the number of buttons for the entire top-level collection regardless of the actual value of the usage page. 772 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 773 @result OSStatus Returns an error code if an error was encountered or noErr on success. 774 */ 775 776extern 777UInt32 778HIDMaxUsageListLength (HIDReportType reportType, 779 HIDUsage usagePage, 780 HIDPreparsedDataRef preparsedDataRef); 781 782/*! 783 @function HIDSetScaledUsageValue 784 @abstract The HIDSetScaledUsageValue function takes a signed physical (scaled) number and converts it to the logical, or device representation and inserts it in a given report. 785 @discussion The HIDSetScaledUsageValue function automatically handles the setting of the signed bit in the data to be sent to the device. 786 @param reportType Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 787 @param usagePage Specifies the usage page identifier of the value to be set in the report. 788 @param collection Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it will be ignored. 789 @param usage Specifies the usage identifier of the value to be set in the report. 790 @param usageValue Specifies the physical, or scaled, value to be set in the value for the given report. 791 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 792 @param report Points to the caller-allocated buffer that contains the device report data. 793 @param Specifies the length, in bytes of the report data specified in the report parameter. 794 @result OSStatus Returns an error code if an error was encountered or noErr on success. 795 */ 796 797extern 798OSStatus 799HIDSetScaledUsageValue (HIDReportType reportType, 800 HIDUsage usagePage, 801 UInt32 collection, 802 HIDUsage usage, 803 SInt32 usageValue, 804 HIDPreparsedDataRef preparsedDataRef, 805 void * report, 806 IOByteCount reportLength); 807 808/*! 809 @function HIDSetButtons 810 @abstract The HIDSetButtons function takes a report from a HID device and returns the current state of the buttons in that report. 811 @param reportType Specifies the type of repor. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 812 @param usagePage Specifies the usage page identifier of the value to be set in the report. 813 @param collection Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored. 814 @param usageList Points to a caller-allocated buffer that contains an array of button data to be set in the report in the report parameter. 815 @param usageListSize Specifies the size, in array elements, of the buffer provided in the usageList parameter. If an error is returned by a call to this function, the usageListLength parameter contains the location in the array provided in the usageList parameter where the error was encountered. All array entries encountered prior to the error location were successfully set in the report provided in the report parameter. 816 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 817 @param report Points to the caller-allocated buffer that contains the device report data. 818 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter. 819 @result OSStatus Returns an error code if an error was encountered or noErr on success. 820 */ 821 822extern 823OSStatus 824HIDSetButtons (HIDReportType reportType, 825 HIDUsage usagePage, 826 UInt32 collection, 827 HIDUsage * usageList, 828 UInt32 * usageListSize, 829 HIDPreparsedDataRef preparsedDataRef, 830 void * report, 831 IOByteCount reportLength); 832 833/*! 834 @function HIDSetUsageValue 835 @abstract The HIDSetUsageValue function sets a value in a give report. 836 @discussion The HIDSetUsageVlaue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function. 837 @param reportType Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 838 @param usagePage Specifies the usage page identifier of the value to be set in the report. 839 @param collection Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored. 840 @param usage Specifies the usage identifier of the value to be set in the report. 841 @param usageValue Specifies the data that is to be set in the value for the given report. 842 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 843 @param report Points to the caller-allocated buffer that contains the device report data. 844 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter. 845 @result OSStatus Returns an error code if an error was encountered or noErr on success. 846 */ 847 848extern 849OSStatus 850HIDSetUsageValue (HIDReportType reportType, 851 HIDUsage usagePage, 852 UInt32 collection, 853 HIDUsage usage, 854 SInt32 usageValue, 855 HIDPreparsedDataRef preparsedDataRef, 856 void * report, 857 IOByteCount reportLength); 858 859/*! 860 @function HIDSetUsageValueArray 861 @abstract The HIDSetUsageValueArray function sets an array of values in a given report. 862 @discussion The HIDSetUsageValue function does not automatically handle the sign bit. Clients must either manually set the sign bit, at the position provided in the HIDValueCaps structure for this value, or call the HIDSetScaledUsageValue function. 863 @param reportType Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 864 @param usagePage Specifies the usage page identifier of the value to be set in the report. 865 @param collection Optionally specifies the link collection identifier to distinguish between values that have the same usage page and usage identifiers. If this parameter is zero, it is ignored. 866 @param usage Specifies the usage identifier of the value to be set in the report. 867 @param usageValueBuffer Points to a caller-allocated buffer that contains, on output, the data from the device. The correct length for this buffer can be found by multiplying the reportCount and bitSize fields of the HIDValueCaps structure for this value and rounding the resulting value up to the nearest byte. 868 @param usageValueBufferLength Specifies the size, in bytes, of the buffer in the usageValueBuffer parameter. 869 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 870 @param report Points to the caller-allocated buffer that contains the device report data. 871 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter. 872 @result OSStatus Returns an error code if an error was encountered or noErr on success. 873 */ 874 875extern 876OSStatus 877HIDSetUsageValueArray (HIDReportType reportType, 878 HIDUsage usagePage, 879 UInt32 collection, 880 HIDUsage usage, 881 UInt8 * usageValueBuffer, 882 IOByteCount usageValueBufferLength, 883 HIDPreparsedDataRef preparsedDataRef, 884 void * report, 885 IOByteCount reportLength); 886 887/*! 888 @function HIDUsageListDifference 889 @abstract The HIDUsageListDifference function compares and provides the differences between two lists of buttons. 890 @param previousUsageList Points to the older button list to be used for comparison. 891 @param currentUsageList Points to the newer button list to be used for comparison. 892 @param breakUsageList On return, points to a caller-allocated buffer that contains the buttons set in the older list, specified in the previousUsageList parameter, but not set in the new list, specified in the currentUsageList parameter. 893 @param makeUsageList On return, points to a caller-allocated buffer that contains the buttons set in the new list, specified in the currentUsageList parameter, but not set in the old list, specified in the previousUsageList parameter. 894 @param usageListsLength Specifies the length, in array elements, of the buffers provided in the currentUsageList and previousUssageList parameters. 895 @result OSStatus Returns an error code if an error was encountered or noErr on success. 896 */ 897 898extern 899OSStatus 900HIDUsageListDifference (HIDUsage * previousUsageList, 901 HIDUsage * currentUsageList, 902 HIDUsage * breakUsageList, 903 HIDUsage * makeUsageList, 904 UInt32 usageListsSize); 905 906/*! 907 @function HIDSetButton 908 @abstract The HIDSetButton function takes a report from a HID device and sets the current state of the specified button in that report. 909 @param reportType Specifies the type of report. This parameter must be one of the following: kHIDInputReport, kHIDOutputReport, or kHIDFeatureReport. 910 @param usagePage Specifies the usage page identifier of the value to be set in the report. 911 @param collection Optionally specifies the link collection identifier to distinguish between buttons. If this parameter is zero, it is ignored. 912 @param usage Points to a caller-allocated buffer that contains the button data to be set in the report in the report parameter. 913 @param preparsedDataRef Preparsed data reference for the report that is retuned by the HIDOpenReportDescriptor function 914 @param report Points to the caller-allocated buffer that contains the device report data. 915 @param reportLength Specifies the size, in bytes, of the report data provided in the report parameter. 916 @result OSStatus Returns an error code if an error was encountered or noErr on success. 917 */ 918 919extern 920OSStatus 921HIDSetButton (HIDReportType reportType, 922 HIDUsage usagePage, 923 UInt32 collection, 924 HIDUsage usage, 925 HIDPreparsedDataRef preparsedDataRef, 926 void * report, 927 IOByteCount reportLength); 928 929 930#ifdef __cplusplus 931} 932#endif 933 934 935#endif 936