iokit/IOKit/hidsystem/IOHIDDescriptorParser.h

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