git.zerfleddert.de Git - proxmark3-svn/blob - client/include/hidpi.h

   1 /*++
   2
   3 Copyright (c) 1996-1998      Microsoft Corporation
   4
   5 Module Name:
   6
   7         HIDPI.H
   8
   9 Abstract:
  10
  11    Public Interface to the HID parsing library.
  12
  13 Environment:
  14
  15     Kernel & user mode
  16
  17 --*/
  18
  19 #ifndef   __HIDPI_H__
  20 #define   __HIDPI_H__
  21
  22 #include <pshpack4.h>
  23 typedef LONG NTSTATUS;
  24 // Please include "hidsdi.h" to use the user space (dll / parser)
  25 // Please include "hidpddi.h" to use the kernel space parser
  26
  27 //
  28 // Special Link collection values for using the query functions
  29 //
  30 // Root collection references the collection at the base of the link
  31 // collection tree.
  32 // Unspecifies, references all collections in the link collection tree.
  33 //
  34 #define HIDP_LINK_COLLECTION_ROOT ((USHORT) -1)
  35 #define HIDP_LINK_COLLECTION_UNSPECIFIED ((USHORT) 0)
  36
  37
  38 typedef enum _HIDP_REPORT_TYPE
  39 {
  40     HidP_Input,
  41     HidP_Output,
  42     HidP_Feature
  43 } HIDP_REPORT_TYPE;
  44
  45 typedef struct _USAGE_AND_PAGE
  46 {
  47     USAGE Usage;
  48     USAGE UsagePage;
  49 } USAGE_AND_PAGE, *PUSAGE_AND_PAGE;
  50
  51 #define HidP_IsSameUsageAndPage(u1, u2) ((* (PULONG) &u1) == (* (PULONG) &u2))
  52
  53 typedef struct _HIDP_BUTTON_CAPS
  54 {
  55     USAGE    UsagePage;
  56     UCHAR    ReportID;
  57     BOOLEAN  IsAlias;
  58
  59     USHORT   BitField;
  60     USHORT   LinkCollection;   // A unique internal index pointer
  61
  62     USAGE    LinkUsage;
  63     USAGE    LinkUsagePage;
  64
  65     BOOLEAN  IsRange;
  66     BOOLEAN  IsStringRange;
  67     BOOLEAN  IsDesignatorRange;
  68     BOOLEAN  IsAbsolute;
  69
  70     ULONG    Reserved[10];
  71     union {
  72         struct {
  73             USAGE    UsageMin,         UsageMax;
  74             USHORT   StringMin,        StringMax;
  75             USHORT   DesignatorMin,    DesignatorMax;
  76             USHORT   DataIndexMin,     DataIndexMax;
  77         } Range;
  78         struct  {
  79             USAGE    Usage,            Reserved1;
  80             USHORT   StringIndex,      Reserved2;
  81             USHORT   DesignatorIndex,  Reserved3;
  82             USHORT   DataIndex,        Reserved4;
  83         } NotRange;
  84     };
  85
  86 } HIDP_BUTTON_CAPS, *PHIDP_BUTTON_CAPS;
  87
  88
  89 typedef struct _HIDP_VALUE_CAPS
  90 {
  91     USAGE    UsagePage;
  92     UCHAR    ReportID;
  93     BOOLEAN  IsAlias;
  94
  95     USHORT   BitField;
  96     USHORT   LinkCollection;   // A unique internal index pointer
  97
  98     USAGE    LinkUsage;
  99     USAGE    LinkUsagePage;
 100
 101     BOOLEAN  IsRange;
 102     BOOLEAN  IsStringRange;
 103     BOOLEAN  IsDesignatorRange;
 104     BOOLEAN  IsAbsolute;
 105
 106     BOOLEAN  HasNull;        // Does this channel have a null report   union
 107     UCHAR    Reserved;
 108     USHORT   BitSize;        // How many bits are devoted to this value?
 109
 110     USHORT   ReportCount;    // See Note below.  Usually set to 1.
 111     USHORT   Reserved2[5];
 112
 113     ULONG    UnitsExp;
 114     ULONG    Units;
 115
 116     LONG     LogicalMin,       LogicalMax;
 117     LONG     PhysicalMin,      PhysicalMax;
 118
 119     union {
 120         struct {
 121             USAGE    UsageMin,         UsageMax;
 122             USHORT   StringMin,        StringMax;
 123             USHORT   DesignatorMin,    DesignatorMax;
 124             USHORT   DataIndexMin,     DataIndexMax;
 125         } Range;
 126
 127         struct {
 128             USAGE    Usage,            Reserved1;
 129             USHORT   StringIndex,      Reserved2;
 130             USHORT   DesignatorIndex,  Reserved3;
 131             USHORT   DataIndex,        Reserved4;
 132         } NotRange;
 133     };
 134 } HIDP_VALUE_CAPS, *PHIDP_VALUE_CAPS;
 135
 136 //
 137 // Notes:
 138 //
 139 // ReportCount:  When a report descriptor declares an Input, Output, or
 140 // Feature main item with fewer usage declarations than the report count, then
 141 // the last usage applies to all remaining unspecified count in that main item.
 142 // (As an example you might have data that required many fields to describe,
 143 // possibly buffered bytes.)  In this case, only one value cap structure is
 144 // allocated for these associtated fields, all with the same usage, and Report
 145 // Count reflects the number of fields involved.  Normally ReportCount is 1.
 146 // To access all of the fields in such a value structure would require using
 147 // HidP_GetUsageValueArray and HidP_SetUsageValueArray.   HidP_GetUsageValue/
 148 // HidP_SetScaledUsageValue will also work, however, these functions will only
 149 // work with the first field of the structure.
 150 //
 151
 152 //
 153 // The link collection tree consists of an array of LINK_COLLECTION_NODES
 154 // where the index into this array is the same as the collection number.
 155 //
 156 // Given a collection A which contains a subcollection B, A is defined to be
 157 // the parent B, and B is defined to be the child.
 158 //
 159 // Given collections A, B, and C where B and C are children of A, and B was
 160 // encountered before C in the report descriptor, B is defined as a sibling of
 161 // C.  (This implies, of course, that if B is a sibling of C, then C is NOT a
 162 // sibling of B).
 163 //
 164 // B is defined as the NextSibling of C if and only if there exists NO
 165 // child collection of A, call it D, such that B is a sibling of D and D
 166 // is a sibling of C.
 167 //
 168 // E is defined to be the FirstChild of A if and only if for all children of A,
 169 // F, that are not equivalent to E, F is a sibling of E.
 170 // (This implies, of course, that the does not exist a child of A, call it G,
 171 // where E is a sibling of G).  In other words the first sibling is the last
 172 // link collection found in the list.
 173 //
 174 // In other words, if a collection B is defined within the definition of another
 175 // collection A, B becomes a child of A.  All collections with the same parent
 176 // are considered siblings.  The FirstChild of the parent collection, A, will be
 177 // last collection defined that has A as a parent.  The order of sibling pointers
 178 // is similarly determined.  When a collection B is defined, it becomes the
 179 // FirstChild of it's parent collection.  The previously defined FirstChild of the
 180 // parent collection becomes the NextSibling of the new collection.  As new
 181 // collections with the same parent are discovered, the chain of sibling is built.
 182 //
 183 // With that in mind, the following describes conclusively a data structure
 184 // that provides direct traversal up, down, and accross the link collection
 185 // tree.
 186 //
 187 //
 188 typedef struct _HIDP_LINK_COLLECTION_NODE
 189 {
 190     USAGE    LinkUsage;
 191     USAGE    LinkUsagePage;
 192     USHORT   Parent;
 193     USHORT   NumberOfChildren;
 194     USHORT   NextSibling;
 195     USHORT   FirstChild;
 196     ULONG    CollectionType: 8;  // As defined in 6.2.2.6 of HID spec
 197     ULONG    IsAlias : 1; // This link node is an allias of the next link node.
 198     ULONG    Reserved: 23;
 199     PVOID    UserContext; // The user can hang his coat here.
 200 } HIDP_LINK_COLLECTION_NODE, *PHIDP_LINK_COLLECTION_NODE;
 201
 202 //
 203 // When a link collection is described by a delimiter, alias link collection
 204 // nodes are created.  (One for each usage within the delimiter).
 205 // The parser assigns each capability description listed above only one
 206 // link collection.
 207 //
 208 // If a control is defined within a collection defined by
 209 // delimited usages, then that control is said to be within multiple link
 210 // collections, one for each usage within the open and close delimiter tokens.
 211 // Such multiple link collecions are said to be aliases.  The first N-1 such
 212 // collections, listed in the link collection node array, have their IsAlias
 213 // bit set.  The last such link collection is the link collection index used
 214 // in the capabilities described above.
 215 // Clients wishing to set a control in an aliased collection, should walk the
 216 // collection array once for each time they see the IsAlias flag set, and use
 217 // the last link collection as the index for the below accessor functions.
 218 //
 219 // NB: if IsAlias is set, then NextSibling should be one more than the current
 220 // link collection node index.
 221 //
 222
 223 typedef PUCHAR  PHIDP_REPORT_DESCRIPTOR;
 224 typedef struct _HIDP_PREPARSED_DATA * PHIDP_PREPARSED_DATA;
 225
 226 typedef struct _HIDP_CAPS
 227 {
 228     USAGE    Usage;
 229     USAGE    UsagePage;
 230     USHORT   InputReportByteLength;
 231     USHORT   OutputReportByteLength;
 232     USHORT   FeatureReportByteLength;
 233     USHORT   Reserved[17];
 234
 235     USHORT   NumberLinkCollectionNodes;
 236
 237     USHORT   NumberInputButtonCaps;
 238     USHORT   NumberInputValueCaps;
 239     USHORT   NumberInputDataIndices;
 240
 241     USHORT   NumberOutputButtonCaps;
 242     USHORT   NumberOutputValueCaps;
 243     USHORT   NumberOutputDataIndices;
 244
 245     USHORT   NumberFeatureButtonCaps;
 246     USHORT   NumberFeatureValueCaps;
 247     USHORT   NumberFeatureDataIndices;
 248 } HIDP_CAPS, *PHIDP_CAPS;
 249
 250 typedef struct _HIDP_DATA
 251 {
 252     USHORT  DataIndex;
 253     USHORT  Reserved;
 254     union {
 255         ULONG   RawValue; // for values
 256         BOOLEAN On; // for buttons MUST BE TRUE for buttons.
 257     };
 258 } HIDP_DATA, *PHIDP_DATA;
 259 //
 260 // The HIDP_DATA structure is used with HidP_GetData and HidP_SetData
 261 // functions.
 262 //
 263 // The parser contiguously assigns every control (button or value) in a hid
 264 // device a unique data index from zero to NumberXXXDataIndices -1 , inclusive.
 265 // This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures.
 266 //
 267 // Most clients will find the Get/Set Buttons / Value accessor functions
 268 // sufficient to their needs, as they will allow the clients to access the
 269 // data known to them while ignoring the other controls.
 270 //
 271 // More complex clients, which actually read the Button / Value Caps, and which
 272 // do a value add service to these routines (EG Direct Input), will need to
 273 // access all the data in the device without interest in the individual usage
 274 // or link collection location.  These are the clients that will find
 275 // HidP_Data useful.
 276 //
 277
 278 typedef struct _HIDP_UNKNOWN_TOKEN
 279 {
 280     UCHAR  Token;
 281     UCHAR  Reserved[3];
 282     ULONG  BitField;
 283 } HIDP_UNKNOWN_TOKEN, *PHIDP_UNKNOWN_TOKEN;
 284
 285 typedef struct _HIDP_EXTENDED_ATTRIBUTES
 286 {
 287     UCHAR   NumGlobalUnknowns;
 288     UCHAR   Reserved [3];
 289     PHIDP_UNKNOWN_TOKEN  GlobalUnknowns;
 290     // ... Additional attributes
 291     ULONG   Data [1]; // variableLength  DO NOT ACCESS THIS FIELD
 292 } HIDP_EXTENDED_ATTRIBUTES, *PHIDP_EXTENDED_ATTRIBUTES;
 293
 294 NTSTATUS __stdcall
 295 HidP_GetCaps (
 296    IN      PHIDP_PREPARSED_DATA      PreparsedData,
 297    OUT     PHIDP_CAPS                Capabilities
 298    );
 299 /*++
 300 Routine Description:
 301    Returns a list of capabilities of a given hid device as described by its
 302    preparsed data.
 303
 304 Arguments:
 305    PreparsedData    The preparsed data returned from HIDCLASS.
 306    Capabilities     a HIDP_CAPS structure
 307
 308 Return Value:
 309 ·  HIDP_STATUS_SUCCESS
 310 ·  HIDP_STATUS_INVALID_PREPARSED_DATA
 311 --*/
 312
 313 NTSTATUS __stdcall
 314 HidP_GetLinkCollectionNodes (
 315    OUT      PHIDP_LINK_COLLECTION_NODE LinkCollectionNodes,
 316    IN OUT   PULONG                     LinkCollectionNodesLength,
 317    IN       PHIDP_PREPARSED_DATA       PreparsedData
 318    );
 319 /*++
 320 Routine Description:
 321    Return a list of PHIDP_LINK_COLLECTION_NODEs used to describe the link
 322    collection tree of this hid device.  See the above description of
 323    struct _HIDP_LINK_COLLECTION_NODE.
 324
 325 Arguments:
 326    LinkCollectionNodes - a caller allocated array into which
 327                  HidP_GetLinkCollectionNodes will store the information
 328
 329    LinKCollectionNodesLength - the caller sets this value to the length of the
 330                  the array in terms of number of elements.
 331                  HidP_GetLinkCollectionNodes sets this value to the actual
 332                  number of elements set. The total number of nodes required to
 333                  describe this HID device can be found in the
 334                  NumberLinkCollectionNodes field in the HIDP_CAPS structure.
 335
 336 --*/
 337
 338 NTSTATUS __stdcall
 339 HidP_GetButtonCaps (
 340    IN       HIDP_REPORT_TYPE     ReportType,
 341    OUT      PHIDP_BUTTON_CAPS    ButtonCaps,
 342    IN OUT   PUSHORT              ButtonCapsLength,
 343    IN       PHIDP_PREPARSED_DATA PreparsedData
 344 );
 345 #define HidP_GetButtonCaps(_Type_, _Caps_, _Len_, _Data_) \
 346         HidP_GetSpecificButtonCaps (_Type_, 0, 0, 0, _Caps_, _Len_, _Data_)
 347 NTSTATUS __stdcall
 348 HidP_GetSpecificButtonCaps (
 349    IN       HIDP_REPORT_TYPE     ReportType,
 350    IN       USAGE                UsagePage,      // Optional (0 => ignore)
 351    IN       USHORT               LinkCollection, // Optional (0 => ignore)
 352    IN       USAGE                Usage,          // Optional (0 => ignore)
 353    OUT      PHIDP_BUTTON_CAPS    ButtonCaps,
 354    IN OUT   PUSHORT              ButtonCapsLength,
 355    IN       PHIDP_PREPARSED_DATA PreparsedData
 356    );
 357 /*++
 358 Description:
 359    HidP_GetButtonCaps returns all the buttons (binary values) that are a part
 360    of the given report type for the Hid device represented by the given
 361    preparsed data.
 362
 363 Parameters:
 364    ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 365
 366    UsagePage   A usage page value used to limit the button caps returned to
 367                 those on a given usage page.  If set to 0, this parameter is
 368                 ignored.  Can be used with LinkCollection and Usage parameters
 369                 to further limit the number of button caps structures returned.
 370
 371    LinkCollection HIDP_LINK_COLLECTION node array index used to limit the
 372                   button caps returned to those buttons in a given link
 373                   collection.  If set to 0, this parameter is
 374                   ignored.  Can be used with UsagePage and Usage parameters
 375                   to further limit the number of button caps structures
 376                   returned.
 377
 378    Usage      A usage value used to limit the button caps returned to those
 379                with the specified usage value.  If set to 0, this parameter
 380                is ignored.  Can be used with LinkCollection and UsagePage
 381                parameters to further limit the number of button caps
 382                structures returned.
 383
 384    ButtonCaps A _HIDP_BUTTON_CAPS array containing information about all the
 385                binary values in the given report.  This buffer is provided by
 386                the caller.
 387
 388    ButtonLength   As input, this parameter specifies the length of the
 389                   ButtonCaps parameter (array) in number of array elements.
 390                   As output, this value is set to indicate how many of those
 391                   array elements were filled in by the function.  The maximum number of
 392                   button caps that can be returned is found in the HIDP_CAPS
 393                   structure.  If HIDP_STATUS_BUFFER_TOO_SMALL is returned,
 394                   this value contains the number of array elements needed to
 395                   successfully complete the request.
 396
 397    PreparsedData  The preparsed data returned from HIDCLASS.
 398
 399
 400 Return Value
 401 HidP_GetSpecificButtonCaps returns the following error codes:
 402 · HIDP_STATUS_SUCCESS.
 403 · HIDP_STATUS_INVALID_REPORT_TYPE
 404 · HIDP_STATUS_INVALID_PREPARSED_DATA
 405 · HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in)
 406 · HIDP_STATUS_USAGE_NOT_FOUND
 407 --*/
 408
 409 NTSTATUS __stdcall
 410 HidP_GetValueCaps (
 411    IN       HIDP_REPORT_TYPE     ReportType,
 412    OUT      PHIDP_VALUE_CAPS     ValueCaps,
 413    IN OUT   PUSHORT              ValueCapsLength,
 414    IN       PHIDP_PREPARSED_DATA PreparsedData
 415 );
 416 #define HidP_GetValueCaps(_Type_, _Caps_, _Len_, _Data_) \
 417         HidP_GetSpecificValueCaps (_Type_, 0, 0, 0, _Caps_, _Len_, _Data_)
 418 NTSTATUS __stdcall
 419 HidP_GetSpecificValueCaps (
 420    IN       HIDP_REPORT_TYPE     ReportType,
 421    IN       USAGE                UsagePage,      // Optional (0 => ignore)
 422    IN       USHORT               LinkCollection, // Optional (0 => ignore)
 423    IN       USAGE                Usage,          // Optional (0 => ignore)
 424    OUT      PHIDP_VALUE_CAPS     ValueCaps,
 425    IN OUT   PUSHORT              ValueCapsLength,
 426    IN       PHIDP_PREPARSED_DATA PreparsedData
 427    );
 428 /*++
 429 Description:
 430    HidP_GetValueCaps returns all the values (non-binary) that are a part
 431    of the given report type for the Hid device represented by the given
 432    preparsed data.
 433
 434 Parameters:
 435    ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 436
 437    UsagePage   A usage page value used to limit the value caps returned to
 438                 those on a given usage page.  If set to 0, this parameter is
 439                 ignored.  Can be used with LinkCollection and Usage parameters
 440                 to further limit the number of value caps structures returned.
 441
 442    LinkCollection HIDP_LINK_COLLECTION node array index used to limit the
 443                   value caps returned to those buttons in a given link
 444                   collection.  If set to 0, this parameter is
 445                   ignored.  Can be used with UsagePage and Usage parameters
 446                   to further limit the number of value caps structures
 447                   returned.
 448
 449    Usage      A usage value used to limit the value caps returned to those
 450                with the specified usage value.  If set to 0, this parameter
 451                is ignored.  Can be used with LinkCollection and UsagePage
 452                parameters to further limit the number of value caps
 453                structures returned.
 454
 455    ValueCaps  A _HIDP_VALUE_CAPS array containing information about all the
 456                non-binary values in the given report.  This buffer is provided
 457                by the caller.
 458
 459    ValueLength   As input, this parameter specifies the length of the ValueCaps
 460                   parameter (array) in number of array elements.  As output,
 461                   this value is set to indicate how many of those array elements
 462                   were filled in by the function.  The maximum number of
 463                   value caps that can be returned is found in the HIDP_CAPS
 464                   structure.  If HIDP_STATUS_BUFFER_TOO_SMALL is returned,
 465                   this value contains the number of array elements needed to
 466                   successfully complete the request.
 467
 468    PreparsedData  The preparsed data returned from HIDCLASS.
 469
 470
 471 Return Value
 472 HidP_GetValueCaps returns the following error codes:
 473 · HIDP_STATUS_SUCCESS.
 474 · HIDP_STATUS_INVALID_REPORT_TYPE
 475 · HIDP_STATUS_INVALID_PREPARSED_DATA
 476 · HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in)
 477 · HIDP_STATUS_USAGE_NOT_FOUND
 478
 479 --*/
 480
 481 NTSTATUS __stdcall
 482 HidP_GetExtendedAttributes (
 483     IN      HIDP_REPORT_TYPE            ReportType,
 484     IN      USHORT                      DataIndex,
 485     IN      PHIDP_PREPARSED_DATA        PreparsedData,
 486     OUT     PHIDP_EXTENDED_ATTRIBUTES   Attributes,
 487     IN OUT  PULONG                      LengthAttributes
 488     );
 489 /*++
 490 Description:
 491     Given a data index from the value or button capabilities of a given control
 492     return any extended attributes for the control if any exist.
 493
 494 Parameters:
 495     ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 496
 497     DataIndex   The data index for the given control, found in the capabilities
 498                 structure for that control
 499
 500     PreparsedData   The preparsed data returned from HIDCLASS.
 501
 502     Attributes  Pointer to a buffer into which the extended attribute data will
 503                 be copied.
 504
 505     LengthAttributes    Length of the given buffer in bytes.
 506
 507 Return Value
 508     HIDP_STATUS_SUCCESS
 509     HIDP_STATUS_DATA_INDEX_NOT_FOUND
 510 --*/
 511
 512 NTSTATUS __stdcall
 513 HidP_InitializeReportForID (
 514    IN       HIDP_REPORT_TYPE      ReportType,
 515    IN       UCHAR                 ReportID,
 516    IN       PHIDP_PREPARSED_DATA  PreparsedData,
 517    IN OUT   PCHAR                 Report,
 518    IN       ULONG                 ReportLength
 519    );
 520 /*++
 521
 522 Routine Description:
 523
 524     Initialize a report based on the given report ID.
 525
 526 Parameters:
 527
 528     ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 529
 530     PreparasedData  Preparsed data structure returned by HIDCLASS
 531
 532     Report      Buffer which to set the data into.
 533
 534     ReportLength Length of Report...Report should be at least as long as the
 535                 value indicated in the HIDP_CAPS structure for the device and
 536                 the corresponding ReportType
 537
 538 Return Value
 539
 540 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 541 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 542 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not equal
 543                                         to the length specified in HIDP_CAPS
 544                                         structure for the given ReportType
 545 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 546                                         for the given ReportType
 547
 548 --*/
 549
 550 NTSTATUS __stdcall
 551 HidP_SetData (
 552    IN       HIDP_REPORT_TYPE      ReportType,
 553    IN       PHIDP_DATA            DataList,
 554    IN OUT   PULONG                DataLength,
 555    IN       PHIDP_PREPARSED_DATA  PreparsedData,
 556    IN OUT   PCHAR                 Report,
 557    IN       ULONG                 ReportLength
 558    );
 559 /*++
 560
 561 Routine Description:
 562
 563     Please Note: Since usage value arrays deal with multiple fields for
 564                  for one usage value, they cannot be used with HidP_SetData
 565                  and HidP_GetData.  In this case,
 566                  HIDP_STATUS_IS_USAGE_VALUE_ARRAY will be returned.
 567
 568 Parameters:
 569
 570     ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 571
 572     DataList    Array of HIDP_DATA structures that contains the data values
 573                 that are to be set into the given report
 574
 575     DataLength  As input, length in array elements of DataList.  As output,
 576                 contains the number of data elements set on successful
 577                 completion or an index into the DataList array to identify
 578                 the faulting HIDP_DATA value if an error code is returned.
 579
 580     PreparasedData  Preparsed data structure returned by HIDCLASS
 581
 582     Report      Buffer which to set the data into.
 583
 584     ReportLength Length of Report...Report should be at least as long as the
 585                 value indicated in the HIDP_CAPS structure for the device and
 586                 the corresponding ReportType
 587
 588 Return Value
 589     HidP_SetData returns the following error codes.  The report packet will
 590         have all the data set up until the HIDP_DATA structure that caused the
 591         error.  DataLength, in the error case, will return this problem index.
 592
 593 · HIDP_STATUS_SUCCESS                -- upon successful insertion of all data
 594                                         into the report packet.
 595 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 596 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 597 · HIDP_STATUS_DATA_INDEX_NOT_FOUND   -- if a HIDP_DATA structure referenced a
 598                                         data index that does not exist for this
 599                                         device's ReportType
 600 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not equal
 601                                         to the length specified in HIDP_CAPS
 602                                         structure for the given ReportType
 603 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 604                                         for the given ReportType
 605 · HIDP_STATUS_IS_USAGE_VALUE_ARRAY   -- if one of the HIDP_DATA structures
 606                                         references a usage value array.
 607                                         DataLength will contain the index into
 608                                         the array that was invalid
 609 · HIDP_STATUS_BUTTON_NOT_PRESSED     -- if a HIDP_DATA structure attempted
 610                                         to unset a button that was not already
 611                                         set in the Report
 612 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- a HIDP_DATA structure was found with
 613                                         a valid index value but is contained
 614                                         in a different report than the one
 615                                         currently being processed
 616 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if there are not enough entries in
 617                                         a given Main Array Item to report all
 618                                         buttons that have been requested to be
 619                                         set
 620 --*/
 621
 622 NTSTATUS __stdcall
 623 HidP_GetData (
 624    IN       HIDP_REPORT_TYPE      ReportType,
 625    OUT      PHIDP_DATA            DataList,
 626    IN OUT   PULONG                DataLength,
 627    IN       PHIDP_PREPARSED_DATA  PreparsedData,
 628    IN       PCHAR                 Report,
 629    IN       ULONG                 ReportLength
 630    );
 631 /*++
 632
 633 Routine Description:
 634
 635     Please Note: For obvious reasons HidP_SetData and HidP_GetData will not
 636     access UsageValueArrays.
 637
 638 Parameters:
 639     ReportType  One of HidP_Input, HidP_Output, or HidP_Feature.
 640
 641     DataList    Array of HIDP_DATA structures that will receive the data
 642                 values that are set in the given report
 643
 644     DataLength  As input, length in array elements of DataList.  As output,
 645                 contains the number of data elements that were successfully
 646                 set by HidP_GetData.  The maximum size necessary for DataList
 647                 can be determined by calling HidP_MaxDataListLength
 648
 649     PreparasedData  Preparsed data structure returned by HIDCLASS
 650
 651     Report      Buffer which to set the data into.
 652
 653     ReportLength Length of Report...Report should be at least as long as the
 654                 value indicated in the HIDP_CAPS structure for the device and
 655                 the corresponding ReportType
 656
 657 Return Value
 658     HidP_GetData returns the following error codes.
 659
 660 · HIDP_STATUS_SUCCESS                -- upon successful retrieval of all data
 661                                         from the report packet.
 662 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 663 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 664 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not equal
 665                                         to the length specified in HIDP_CAPS
 666                                         structure for the given ReportType
 667 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 668                                         for the given ReportType
 669 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if there are not enough array entries in
 670                                         DataList to store all the indice values
 671                                         in the given report.  DataLength will
 672                                         contain the number of array entries
 673                                         required to hold all data
 674 --*/
 675
 676 ULONG __stdcall
 677 HidP_MaxDataListLength (
 678    IN HIDP_REPORT_TYPE      ReportType,
 679    IN PHIDP_PREPARSED_DATA  PreparsedData
 680    );
 681 /*++
 682 Routine Description:
 683
 684     This function returns the maximum length of HIDP_DATA elements that
 685     HidP_GetData could return for the given report type.
 686
 687 Parameters:
 688
 689     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
 690
 691     PreparsedData    Preparsed data structure returned by HIDCLASS
 692
 693 Return Value:
 694
 695     The length of the data list array required for the HidP_GetData function
 696     call.  If an error occurs (either HIDP_STATUS_INVALID_REPORT_TYPE or
 697     HIDP_STATUS_INVALID_PREPARSED_DATA), this function returns 0.
 698
 699 --*/
 700
 701 #define HidP_SetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \
 702         HidP_SetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle)
 703
 704 NTSTATUS __stdcall
 705 HidP_SetUsages (
 706    IN       HIDP_REPORT_TYPE      ReportType,
 707    IN       USAGE                 UsagePage,
 708    IN       USHORT                LinkCollection, // Optional
 709    IN       PUSAGE                UsageList,
 710    IN OUT   PULONG                UsageLength,
 711    IN       PHIDP_PREPARSED_DATA  PreparsedData,
 712    IN OUT   PCHAR                 Report,
 713    IN       ULONG                 ReportLength
 714    );
 715 /*++
 716
 717 Routine Description:
 718     This function sets binary values (buttons) in a report.  Given an
 719     initialized packet of correct length, it modifies the report packet so that
 720     each element in the given list of usages has been set in the report packet.
 721     For example, in an output report with 5 LED\92s, each with a given usage,
 722     an application could turn on any subset of these lights by placing their
 723     usages in any order into the usage array (UsageList).  HidP_SetUsages would,
 724     in turn, set the appropriate bit or add the corresponding byte into the
 725     HID Main Array Item.
 726
 727     A properly initialized Report packet is one of the correct byte length,
 728     and all zeros.
 729
 730     NOTE: A packet that has already been set with a call to a HidP_Set routine
 731           can also be passed in.  This routine then sets processes the UsageList
 732           in the same fashion but verifies that the ReportID already set in
 733           Report matches the report ID for the given usages.
 734
 735 Parameters:
 736     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
 737
 738     UsagePage   All of the usages in the usage array, which HidP_SetUsages will
 739                 set in the report, refer to this same usage page.
 740                 If a client wishes to set usages in a report for multiple
 741                 usage pages then that client needs to make multiple calls to
 742                 HidP_SetUsages for each of the usage pages.
 743
 744     UsageList   A usage array containing the usages that HidP_SetUsages will set in
 745                 the report packet.
 746
 747     UsageLength The length of the given usage array in array elements.
 748                 The parser will set this value to the position in the usage
 749                 array where it stopped processing.  If successful, UsageLength
 750                 will be unchanged.  In any error condition, this parameter
 751                 reflects how many of the usages in the usage list have
 752                 actually been set by the parser.  This is useful for finding
 753                 the usage in the list which caused the error.
 754
 755     PreparsedData The preparsed data recevied from HIDCLASS
 756
 757     Report      The report packet.
 758
 759     ReportLength   Length of the given report packet...Must be equal to the
 760                    value reported in the HIDP_CAPS structure for the device
 761                    and corresponding report type.
 762
 763 Return Value
 764     HidP_SetUsages returns the following error codes.  On error, the report packet
 765     will be correct up until the usage element that caused the error.
 766
 767 · HIDP_STATUS_SUCCESS                -- upon successful insertion of all usages
 768                                         into the report packet.
 769 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 770 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 771 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
 772                                         equal to the length specified in
 773                                         the HIDP_CAPS structure for the given
 774                                         ReportType
 775 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 776                                         for the given ReportType
 777 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a
 778                                         different report.  If the report is
 779                                         zero-initialized on entry the first
 780                                         usage in the list will determine which
 781                                         report ID is used.  Otherwise, the
 782                                         parser will verify that usage matches
 783                                         the passed in report's ID
 784 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage does not exist for any
 785                                         report (no matter what the report ID)
 786                                         for the given report type.
 787 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if there are not enough entries in a
 788                                         given Main Array Item to list all of
 789                                         the given usages.  The caller needs
 790                                         to split his request into more than
 791                                         one call
 792 --*/
 793
 794 #define HidP_UnsetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \
 795         HidP_UnsetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle)
 796
 797 NTSTATUS __stdcall
 798 HidP_UnsetUsages (
 799    IN       HIDP_REPORT_TYPE      ReportType,
 800    IN       USAGE                 UsagePage,
 801    IN       USHORT                LinkCollection, // Optional
 802    IN       PUSAGE                UsageList,
 803    IN OUT   PULONG                UsageLength,
 804    IN       PHIDP_PREPARSED_DATA  PreparsedData,
 805    IN OUT   PCHAR                 Report,
 806    IN       ULONG                 ReportLength
 807    );
 808 /*++
 809
 810 Routine Description:
 811     This function unsets (turns off) binary values (buttons) in the report.  Given
 812     an initialized packet of correct length, it modifies the report packet so
 813     that each element in the given list of usages has been unset in the
 814     report packet.
 815
 816     This function is the "undo" operation for SetUsages.  If the given usage
 817     is not already set in the Report, it will return an error code of
 818     HIDP_STATUS_BUTTON_NOT_PRESSED.  If the button is pressed, HidP_UnsetUsages
 819     will unset the appropriate bit or remove the corresponding index value from
 820     the HID Main Array Item.
 821
 822     A properly initialized Report packet is one of the correct byte length,
 823     and all zeros..
 824
 825     NOTE: A packet that has already been set with a call to a HidP_Set routine
 826           can also be passed in.  This routine then processes the UsageList
 827           in the same fashion but verifies that the ReportID already set in
 828           Report matches the report ID for the given usages.
 829
 830 Parameters:
 831     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
 832
 833     UsagePage   All of the usages in the usage array, which HidP_UnsetUsages will
 834                 unset in the report, refer to this same usage page.
 835                 If a client wishes to unset usages in a report for multiple
 836                 usage pages then that client needs to make multiple calls to
 837                 HidP_UnsetUsages for each of the usage pages.
 838
 839     UsageList   A usage array containing the usages that HidP_UnsetUsages will
 840                 unset in the report packet.
 841
 842     UsageLength The length of the given usage array in array elements.
 843                 The parser will set this value to the position in the usage
 844                 array where it stopped processing.  If successful, UsageLength
 845                 will be unchanged.  In any error condition, this parameter
 846                 reflects how many of the usages in the usage list have
 847                 actually been unset by the parser.  This is useful for finding
 848                 the usage in the list which caused the error.
 849
 850     PreparsedData The preparsed data recevied from HIDCLASS
 851
 852     Report      The report packet.
 853
 854     ReportLength   Length of the given report packet...Must be equal to the
 855                    value reported in the HIDP_CAPS structure for the device
 856                    and corresponding report type.
 857
 858 Return Value
 859     HidP_UnsetUsages returns the following error codes.  On error, the report
 860     packet will be correct up until the usage element that caused the error.
 861
 862 · HIDP_STATUS_SUCCESS                -- upon successful "unsetting" of all usages
 863                                         in the report packet.
 864 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 865 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 866 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
 867                                         equal to the length specified in
 868                                         the HIDP_CAPS structure for the given
 869                                         ReportType
 870 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 871                                         for the given ReportType
 872 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a
 873                                         different report.  If the report is
 874                                         zero-initialized on entry the first
 875                                         usage in the list will determine which
 876                                         report ID is used.  Otherwise, the
 877                                         parser will verify that usage matches
 878                                         the passed in report's ID
 879 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage does not exist for any
 880                                         report (no matter what the report ID)
 881                                         for the given report type.
 882 · HIDP_STATUS_BUTTON_NOT_PRESSED     -- if a usage corresponds to a button that
 883                                         is not already set in the given report
 884 --*/
 885
 886 #define HidP_GetButtons(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) \
 887         HidP_GetUsages(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe)
 888
 889 NTSTATUS __stdcall
 890 HidP_GetUsages (
 891    IN       HIDP_REPORT_TYPE     ReportType,
 892    IN       USAGE                UsagePage,
 893    IN       USHORT               LinkCollection, // Optional
 894    OUT      USAGE *              UsageList,
 895    IN OUT   ULONG *              UsageLength,
 896    IN       PHIDP_PREPARSED_DATA PreparsedData,
 897    IN       PCHAR                Report,
 898    IN       ULONG                ReportLength
 899    );
 900 /*++
 901
 902 Routine Description:
 903     This function returns the binary values (buttons) that are set in a HID
 904     report.  Given a report packet of correct length, it searches the report
 905     packet for each usage for the given usage page and returns them in the
 906     usage list.
 907
 908 Parameters:
 909     ReportType One of HidP_Input, HidP_Output or HidP_Feature.
 910
 911     UsagePage  All of the usages in the usage list, which HidP_GetUsages will
 912                retrieve in the report, refer to this same usage page.
 913                If the client wishes to get usages in a packet for multiple
 914                usage pages then that client needs to make multiple calls
 915                to HidP_GetUsages.
 916
 917     LinkCollection  An optional value which can limit which usages are returned
 918                     in the UsageList to those usages that exist in a specific
 919                     LinkCollection.  A non-zero value indicates the index into
 920                     the HIDP_LINK_COLLECITON_NODE list returned by
 921                     HidP_GetLinkCollectionNodes of the link collection the
 922                     usage should belong to.  A value of 0 indicates this
 923                     should value be ignored.
 924
 925     UsageList  The usage array that will contain all the usages found in
 926                the report packet.
 927
 928     UsageLength The length of the given usage array in array elements.
 929                 On input, this value describes the length of the usage list.
 930                 On output, HidP_GetUsages sets this value to the number of
 931                 usages that was found.  Use HidP_MaxUsageListLength to
 932                 determine the maximum length needed to return all the usages
 933                 that a given report packet may contain.
 934
 935     PreparsedData Preparsed data structure returned by HIDCLASS
 936
 937     Report       The report packet.
 938
 939     ReportLength  Length (in bytes) of the given report packet
 940
 941
 942 Return Value
 943     HidP_GetUsages returns the following error codes:
 944
 945 · HIDP_STATUS_SUCCESS                -- upon successfully retrieving all the
 946                                         usages from the report packet
 947 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
 948 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
 949 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
 950                                         equal to the length specified in
 951                                         the HIDP_CAPS structure for the given
 952                                         ReportType
 953 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
 954                                         for the given ReportType
 955 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if the UsageList is not big enough to
 956                                         hold all the usages found in the report
 957                                         packet.  If this is returned, the buffer
 958                                         will contain UsageLength number of
 959                                         usages.  Use HidP_MaxUsageListLength to
 960                                         find the maximum length needed
 961 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages
 962                                         that match the UsagePage and
 963                                         LinkCollection specified could be found
 964                                         in a report with a different report ID
 965 · HIDP_STATUS_USAGE_NOT_FOUND        -- if there are no usages in a reports for
 966                                         the device and ReportType that match the
 967                                         UsagePage and LinkCollection that were
 968                                         specified
 969 --*/
 970
 971 #define HidP_GetButtonsEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe)  \
 972         HidP_GetUsagesEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe)
 973
 974 NTSTATUS __stdcall
 975 HidP_GetUsagesEx (
 976    IN       HIDP_REPORT_TYPE     ReportType,
 977    IN       USHORT               LinkCollection, // Optional
 978    OUT      PUSAGE_AND_PAGE      ButtonList,
 979    IN OUT   ULONG *              UsageLength,
 980    IN       PHIDP_PREPARSED_DATA PreparsedData,
 981    IN       PCHAR                Report,
 982    IN       ULONG                ReportLength
 983    );
 984
 985 /*++
 986
 987 Routine Description:
 988     This function returns the binary values (buttons) in a HID report.
 989     Given a report packet of correct length, it searches the report packet
 990     for all buttons and returns the UsagePage and Usage for each of the buttons
 991     it finds.
 992
 993 Parameters:
 994     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
 995
 996     LinkCollection  An optional value which can limit which usages are returned
 997                     in the ButtonList to those usages that exist in a specific
 998                     LinkCollection.  A non-zero value indicates the index into
 999                     the HIDP_LINK_COLLECITON_NODE list returned by
1000                     HidP_GetLinkCollectionNodes of the link collection the
1001                     usage should belong to.  A value of 0 indicates this
1002                     should value be ignored.
1003
1004     ButtonList  An array of USAGE_AND_PAGE structures describing all the
1005                 buttons currently ``down'' in the device.
1006
1007     UsageLength The length of the given array in terms of elements.
1008                 On input, this value describes the length of the list.  On
1009                 output, HidP_GetUsagesEx sets this value to the number of
1010                 usages that were found.  Use HidP_MaxUsageListLength to
1011                 determine the maximum length needed to return all the usages
1012                 that a given report packet may contain.
1013
1014     PreparsedData Preparsed data returned by HIDCLASS
1015
1016     Report       The report packet.
1017
1018     ReportLength Length (in bytes) of the given report packet.
1019
1020
1021 Return Value
1022     HidP_GetUsagesEx returns the following error codes:
1023
1024 · HIDP_STATUS_SUCCESS                -- upon successfully retrieving all the
1025                                         usages from the report packet
1026 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1027 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1028 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1029                                         equal to the length specified in
1030                                         the HIDP_CAPS structure for the given
1031                                         ReportType
1032 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
1033                                         for the given ReportType
1034 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if ButtonList is not big enough to
1035                                         hold all the usages found in the report
1036                                         packet.  If this is returned, the buffer
1037                                         will contain UsageLength number of
1038                                         usages.  Use HidP_MaxUsageListLength to
1039                                         find the maximum length needed
1040 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages
1041                                         that match the specified LinkCollection
1042                                         exist in report with a different report
1043                                         ID.
1044 · HIDP_STATUS_USAGE_NOT_FOUND        -- if there are no usages in any reports that
1045                                         match the LinkCollection parameter
1046 --*/
1047
1048 #define HidP_GetButtonListLength(RTy, UPa, Ppd) \
1049         HidP_GetUsageListLength(Rty, UPa, Ppd)
1050
1051 ULONG __stdcall
1052 HidP_MaxUsageListLength (
1053    IN HIDP_REPORT_TYPE      ReportType,
1054    IN USAGE                 UsagePage, // Optional
1055    IN PHIDP_PREPARSED_DATA  PreparsedData
1056    );
1057 /*++
1058 Routine Description:
1059     This function returns the maximum number of usages that a call to
1060     HidP_GetUsages or HidP_GetUsagesEx could return for a given HID report.
1061     If calling for number of usages returned by HidP_GetUsagesEx, use 0 as
1062     the UsagePage value.
1063
1064 Parameters:
1065     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
1066
1067     UsagePage   Specifies the optional UsagePage to query for.  If 0, will
1068                 return all the maximum number of usage values that could be
1069                 returned for a given ReportType.   If non-zero, will return
1070                 the maximum number of usages that would be returned for the
1071                 ReportType with the given UsagePage.
1072
1073     PreparsedData Preparsed data returned from HIDCLASS
1074
1075 Return Value:
1076     The length of the usage list array required for the HidP_GetUsages or
1077     HidP_GetUsagesEx function call.  If an error occurs (such as
1078     HIDP_STATUS_INVALID_REPORT_TYPE or HIDP_INVALID_PREPARSED_DATA, this
1079     returns 0.
1080 --*/
1081
1082 NTSTATUS __stdcall
1083 HidP_SetUsageValue (
1084    IN       HIDP_REPORT_TYPE     ReportType,
1085    IN       USAGE                UsagePage,
1086    IN       USHORT               LinkCollection, // Optional
1087    IN       USAGE                Usage,
1088    IN       ULONG                UsageValue,
1089    IN       PHIDP_PREPARSED_DATA PreparsedData,
1090    IN OUT   PCHAR                Report,
1091    IN       ULONG                ReportLength
1092    );
1093 /*++
1094 Description:
1095     HidP_SetUsageValue inserts a value into the HID Report Packet in the field
1096     corresponding to the given usage page and usage.  HidP_SetUsageValue
1097     casts this value to the appropriate bit length.  If a report packet
1098     contains two different fields with the same Usage and UsagePage,
1099     they can be distinguished with the optional LinkCollection field value.
1100     Using this function sets the raw value into the report packet with
1101     no checking done as to whether it actually falls within the logical
1102     minimum/logical maximum range.  Use HidP_SetScaledUsageValue for this...
1103
1104     NOTE: Although the UsageValue parameter is a ULONG, any casting that is
1105           done will preserve or sign-extend the value.  The value being set
1106           should be considered a LONG value and will be treated as such by
1107           this function.
1108
1109 Parameters:
1110
1111     ReportType  One of HidP_Output or HidP_Feature.
1112
1113     UsagePage   The usage page to which the given usage refers.
1114
1115     LinkCollection  (Optional)  This value can be used to differentiate
1116                                 between two fields that may have the same
1117                                 UsagePage and Usage but exist in different
1118                                 collections.  If the link collection value
1119                                 is zero, this function will set the first field
1120                                 it finds that matches the usage page and
1121                                 usage.
1122
1123     Usage       The usage whose value HidP_SetUsageValue will set.
1124
1125     UsageValue  The raw value to set in the report buffer.  This value must be within
1126                 the logical range or if a NULL value this value should be the
1127                 most negative value that can be represented by the number of bits
1128                 for this field.
1129
1130     PreparsedData The preparsed data returned for HIDCLASS
1131
1132     Report      The report packet.
1133
1134     ReportLength Length (in bytes) of the given report packet.
1135
1136
1137 Return Value:
1138     HidP_SetUsageValue returns the following error codes:
1139
1140 · HIDP_STATUS_SUCCESS                -- upon successfully setting the value
1141                                         in the report packet
1142 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1143 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1144 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1145                                         equal to the length specified in
1146                                         the HIDP_CAPS structure for the given
1147                                         ReportType
1148 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
1149                                         for the given ReportType
1150 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1151                                         link collection exist but exists in
1152                                         a report with a different report ID
1153                                         than the report being passed in.  To
1154                                         set this value, call HidP_SetUsageValue
1155                                         again with a zero-initizialed report
1156                                         packet
1157 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1158                                         collection combination does not exist
1159                                         in any reports for this ReportType
1160 --*/
1161
1162 NTSTATUS __stdcall
1163 HidP_SetScaledUsageValue (
1164    IN       HIDP_REPORT_TYPE     ReportType,
1165    IN       USAGE                UsagePage,
1166    IN       USHORT               LinkCollection, // Optional
1167    IN       USAGE                Usage,
1168    IN       LONG                 UsageValue,
1169    IN       PHIDP_PREPARSED_DATA PreparsedData,
1170    IN OUT   PCHAR                Report,
1171    IN       ULONG                ReportLength
1172    );
1173
1174 /*++
1175 Description:
1176     HidP_SetScaledUsageValue inserts the UsageValue into the HID report packet
1177     in the field corresponding to the given usage page and usage.  If a report
1178     packet contains two different fields with the same Usage and UsagePage,
1179     they can be distinguished with the optional LinkCollection field value.
1180
1181     If the specified field has a defined physical range, this function converts
1182     the physical value specified to the corresponding logical value for the
1183     report.  If a physical value does not exist, the function will verify that
1184     the value specified falls within the logical range and set according.
1185
1186     If the range checking fails but the field has NULL values, the function will
1187     set the field to the defined NULL value (most negative number possible) and
1188     return HIDP_STATUS_NULL.  In other words, use this function to set NULL
1189     values for a given field by passing in a value that falls outside the
1190     physical range if it is defined or the logical range otherwise.
1191
1192     If the field does not support NULL values, an out of range error will be
1193     returned instead.
1194
1195 Parameters:
1196
1197     ReportType  One of HidP_Output or HidP_Feature.
1198
1199     UsagePage   The usage page to which the given usage refers.
1200
1201     LinkCollection  (Optional)  This value can be used to differentiate
1202                                 between two fields that may have the same
1203                                 UsagePage and Usage but exist in different
1204                                 collections.  If the link collection value
1205                                 is zero, this function will set the first field
1206                                 it finds that matches the usage page and
1207                                 usage.
1208
1209     Usage       The usage whose value HidP_SetScaledUsageValue will set.
1210
1211     UsageValue  The value to set in the report buffer.  See the routine
1212                 description above for the different interpretations of this
1213                 value
1214
1215     PreparsedData The preparsed data returned from HIDCLASS
1216
1217     Report      The report packet.
1218
1219     ReportLength Length (in bytes) of the given report packet.
1220
1221
1222 Return Value:
1223    HidP_SetScaledUsageValue returns the following error codes:
1224
1225 · HIDP_STATUS_SUCCESS                -- upon successfully setting the value
1226                                         in the report packet
1227 · HIDP_STATUS_NULL                   -- upon successfully setting the value
1228                                         in the report packet as a NULL value
1229 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1230 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1231 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1232                                         equal to the length specified in
1233                                         the HIDP_CAPS structure for the given
1234                                         ReportType
1235 · HIDP_STATUS_VALUE_OUT_OF_RANGE     -- if the value specified failed to fall
1236                                         within the physical range if it exists
1237                                         or within the logical range otherwise
1238                                         and the field specified by the usage
1239                                         does not allow NULL values
1240 · HIDP_STATUS_BAD_LOG_PHY_VALUES     -- if the field has a physical range but
1241                                         either the logical range is invalid
1242                                         (max <= min) or the physical range is
1243                                         invalid
1244 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1245                                         link collection exist but exists in
1246                                         a report with a different report ID
1247                                         than the report being passed in.  To
1248                                         set this value, call
1249                                         HidP_SetScaledUsageValue again with
1250                                         a zero-initialized report packet
1251 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1252                                         collection combination does not exist
1253                                         in any reports for this ReportType
1254 --*/
1255
1256 NTSTATUS __stdcall
1257 HidP_SetUsageValueArray (
1258     IN    HIDP_REPORT_TYPE     ReportType,
1259     IN    USAGE                UsagePage,
1260     IN    USHORT               LinkCollection, // Optional
1261     IN    USAGE                Usage,
1262     IN    PCHAR                UsageValue,
1263     IN    USHORT               UsageValueByteLength,
1264     IN    PHIDP_PREPARSED_DATA PreparsedData,
1265     OUT   PCHAR                Report,
1266     IN    ULONG                ReportLength
1267     );
1268
1269 /*++
1270 Routine Descripton:
1271     A usage value array occurs when the last usage in the list of usages
1272     describing a main item must be repeated because there are less usages defined
1273     than there are report counts declared for the given main item.  In this case
1274     a single value cap is allocated for that usage and the report count of that
1275     value cap is set to reflect the number of fields to which that usage refers.
1276
1277     HidP_SetUsageValueArray sets the raw bits for that usage which spans
1278     more than one field in a report.
1279
1280     NOTE: This function currently does not support value arrays where the
1281           ReportSize for each of the fields in the array is not a multiple
1282           of 8 bits.
1283
1284           The UsageValue buffer should have the values set as they would appear
1285           in the report buffer.  If this function supported non 8-bit multiples
1286           for the ReportSize then caller should format the input buffer so that
1287           each new value begins at the bit immediately following the last bit
1288           of the previous value
1289
1290 Parameters:
1291
1292     ReportType  One of HidP_Output or HidP_Feature.
1293
1294     UsagePage   The usage page to which the given usage refers.
1295
1296     LinkCollection  (Optional)  This value can be used to differentiate
1297                                 between two fields that may have the same
1298                                 UsagePage and Usage but exist in different
1299                                 collections.  If the link collection value
1300                                 is zero, this function will set the first field
1301                                 it finds that matches the usage page and
1302                                 usage.
1303
1304     Usage       The usage whose value array HidP_SetUsageValueArray will set.
1305
1306     UsageValue  The buffer with the values to set into the value array.
1307                 The number of BITS required is found by multiplying the
1308                 BitSize and ReportCount fields of the Value Cap for this
1309                 control.  The least significant bit of this control found in the
1310                 given report will be placed in the least significan bit location
1311                 of the array given (little-endian format), regardless of whether
1312                 or not the field is byte alligned or if the BitSize is a multiple
1313                 of sizeof (CHAR).
1314
1315                 See the above note for current implementation limitations.
1316
1317     UsageValueByteLength  Length of the UsageValue buffer (in bytes)
1318
1319     PreparsedData The preparsed data returned from HIDCLASS
1320
1321     Report      The report packet.
1322
1323     ReportLength Length (in bytes) of the given report packet.
1324
1325
1326 Return Value:
1327 · HIDP_STATUS_SUCCESS                -- upon successfully setting the value
1328                                         array in the report packet
1329 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1330 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1331 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1332                                         equal to the length specified in
1333                                         the HIDP_CAPS structure for the given
1334                                         ReportType
1335 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
1336                                         for the given ReportType
1337 · HIDP_STATUS_NOT_VALUE_ARRAY        -- if the control specified is not a
1338                                         value array -- a value array will have
1339                                         a ReportCount field in the
1340                                         HIDP_VALUE_CAPS structure that is > 1
1341                                         Use HidP_SetUsageValue instead
1342 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if the size of the passed in buffer with
1343                                         the values to set is too small (ie. has
1344                                         fewer values than the number of fields in
1345                                         the array
1346 · HIDP_STATUS_NOT_IMPLEMENTED        -- if the usage value array has field sizes
1347                                         that are not multiples of 8 bits, this
1348                                         error code is returned since the function
1349                                         currently does not handle setting into
1350                                         such arrays.
1351 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1352                                         link collection exist but exists in
1353                                         a report with a different report ID
1354                                         than the report being passed in.  To
1355                                         set this value, call
1356                                         HidP_SetUsageValueArray again with
1357                                         a zero-initialized report packet
1358 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1359                                         collection combination does not exist
1360                                         in any reports for this ReportType
1361 --*/
1362
1363
1364 NTSTATUS __stdcall
1365 HidP_GetUsageValue (
1366    IN    HIDP_REPORT_TYPE     ReportType,
1367    IN    USAGE                UsagePage,
1368    IN    USHORT               LinkCollection, // Optional
1369    IN    USAGE                Usage,
1370    OUT   PULONG               UsageValue,
1371    IN    PHIDP_PREPARSED_DATA PreparsedData,
1372    IN    PCHAR                Report,
1373    IN    ULONG                ReportLength
1374    );
1375
1376 /*
1377 Description
1378     HidP_GetUsageValue retrieves the value from the HID Report for the usage
1379     specified by the combination of usage page, usage and link collection.
1380     If a report packet contains two different fields with the same
1381     Usage and UsagePage, they can be distinguished with the optional
1382     LinkCollection field value.
1383
1384 Parameters:
1385
1386     ReportType  One of HidP_Input or HidP_Feature.
1387
1388     UsagePage   The usage page to which the given usage refers.
1389
1390     LinkCollection  (Optional)  This value can be used to differentiate
1391                                 between two fields that may have the same
1392                                 UsagePage and Usage but exist in different
1393                                 collections.  If the link collection value
1394                                 is zero, this function will set the first field
1395                                 it finds that matches the usage page and
1396                                 usage.
1397
1398     Usage       The usage whose value HidP_GetUsageValue will retrieve
1399
1400     UsageValue  The raw value that is set for the specified field in the report
1401                 buffer. This value will either fall within the logical range
1402                 or if NULL values are allowed, a number outside the range to
1403                 indicate a NULL
1404
1405     PreparsedData The preparsed data returned for HIDCLASS
1406
1407     Report      The report packet.
1408
1409     ReportLength Length (in bytes) of the given report packet.
1410
1411
1412 Return Value:
1413     HidP_GetUsageValue returns the following error codes:
1414
1415 · HIDP_STATUS_SUCCESS                -- upon successfully retrieving the value
1416                                         from the report packet
1417 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1418 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1419 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1420                                         equal to the length specified in
1421                                         the HIDP_CAPS structure for the given
1422                                         ReportType
1423 · HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
1424                                         for the given ReportType
1425 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1426                                         link collection exist but exists in
1427                                         a report with a different report ID
1428                                         than the report being passed in.  To
1429                                         set this value, call HidP_GetUsageValue
1430                                         again with a different report packet
1431 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1432                                         collection combination does not exist
1433                                         in any reports for this ReportType
1434 --*/
1435
1436
1437 NTSTATUS __stdcall
1438 HidP_GetScaledUsageValue (
1439    IN    HIDP_REPORT_TYPE     ReportType,
1440    IN    USAGE                UsagePage,
1441    IN    USHORT               LinkCollection, // Optional
1442    IN    USAGE                Usage,
1443    OUT   PLONG                UsageValue,
1444    IN    PHIDP_PREPARSED_DATA PreparsedData,
1445    IN    PCHAR                Report,
1446    IN    ULONG                ReportLength
1447    );
1448
1449 /*++
1450 Description
1451     HidP_GetScaledUsageValue retrieves a UsageValue from the HID report packet
1452     in the field corresponding to the given usage page and usage.  If a report
1453     packet contains two different fields with the same Usage and UsagePage,
1454     they can be distinguished with the optional LinkCollection field value.
1455
1456     If the specified field has a defined physical range, this function converts
1457     the logical value that exists in the report packet to the corresponding
1458     physical value.  If a physical range does not exist, the function will
1459     return the logical value.  This function will check to verify that the
1460     logical value in the report falls within the declared logical range.
1461
1462     When doing the conversion between logical and physical values, this
1463     function assumes a linear extrapolation between the physical max/min and
1464     the logical max/min. (Where logical is the values reported by the device
1465     and physical is the value returned by this function).  If the data field
1466     size is less than 32 bits, then HidP_GetScaledUsageValue will sign extend
1467     the value to 32 bits.
1468
1469     If the range checking fails but the field has NULL values, the function
1470     will set UsageValue to 0 and return HIDP_STATUS_NULL.  Otherwise, it
1471     returns a HIDP_STATUS_OUT_OF_RANGE error.
1472
1473 Parameters:
1474
1475     ReportType  One of HidP_Output or HidP_Feature.
1476
1477     UsagePage   The usage page to which the given usage refers.
1478
1479     LinkCollection  (Optional)  This value can be used to differentiate
1480                                 between two fields that may have the same
1481                                 UsagePage and Usage but exist in different
1482                                 collections.  If the link collection value
1483                                 is zero, this function will retrieve the first
1484                                 field it finds that matches the usage page
1485                                 and usage.
1486
1487     Usage       The usage whose value HidP_GetScaledUsageValue will retrieve
1488
1489     UsageValue  The value retrieved from the report buffer.  See the routine
1490                 description above for the different interpretations of this
1491                 value
1492
1493     PreparsedData The preparsed data returned from HIDCLASS
1494
1495     Report      The report packet.
1496
1497     ReportLength Length (in bytes) of the given report packet.
1498
1499
1500 Return Value:
1501    HidP_GetScaledUsageValue returns the following error codes:
1502
1503 · HIDP_STATUS_SUCCESS                -- upon successfully retrieving the value
1504                                         from the report packet
1505 · HIDP_STATUS_NULL                   -- if the report packet had a NULL value
1506                                         set
1507 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1508 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1509 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1510                                         equal to the length specified in
1511                                         the HIDP_CAPS structure for the given
1512                                         ReportType
1513 · HIDP_STATUS_VALUE_OUT_OF_RANGE     -- if the value retrieved from the packet
1514                                         falls outside the logical range and
1515                                         the field does not support NULL values
1516 · HIDP_STATUS_BAD_LOG_PHY_VALUES     -- if the field has a physical range but
1517                                         either the logical range is invalid
1518                                         (max <= min) or the physical range is
1519                                         invalid
1520 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1521                                         link collection exist but exists in
1522                                         a report with a different report ID
1523                                         than the report being passed in.  To
1524                                         set this value, call
1525                                         HidP_GetScaledUsageValue with a
1526                                         different report packet
1527 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1528                                         collection combination does not exist
1529                                         in any reports for this ReportType
1530 --*/
1531
1532 NTSTATUS __stdcall
1533 HidP_GetUsageValueArray (
1534     IN    HIDP_REPORT_TYPE     ReportType,
1535     IN    USAGE                UsagePage,
1536     IN    USHORT               LinkCollection, // Optional
1537     IN    USAGE                Usage,
1538     OUT   PCHAR                UsageValue,
1539     IN    USHORT               UsageValueByteLength,
1540     IN    PHIDP_PREPARSED_DATA PreparsedData,
1541     IN    PCHAR                Report,
1542     IN    ULONG                ReportLength
1543     );
1544
1545 /*++
1546 Routine Descripton:
1547     A usage value array occurs when the last usage in the list of usages
1548     describing a main item must be repeated because there are less usages defined
1549     than there are report counts declared for the given main item.  In this case
1550     a single value cap is allocated for that usage and the report count of that
1551     value cap is set to reflect the number of fields to which that usage refers.
1552
1553     HidP_GetUsageValueArray returns the raw bits for that usage which spans
1554     more than one field in a report.
1555
1556     NOTE: This function currently does not support value arrays where the
1557           ReportSize for each of the fields in the array is not a multiple
1558           of 8 bits.
1559
1560           The UsageValue buffer will have the raw values as they are set
1561           in the report packet.
1562
1563 Parameters:
1564
1565     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
1566
1567     UsagePage   The usage page to which the given usage refers.
1568
1569     LinkCollection  (Optional)  This value can be used to differentiate
1570                                 between two fields that may have the same
1571                                 UsagePage and Usage but exist in different
1572                                 collections.  If the link collection value
1573                                 is zero, this function will set the first field
1574                                 it finds that matches the usage page and
1575                                 usage.
1576
1577    Usage       The usage whose value HidP_GetUsageValueArray will retreive.
1578
1579    UsageValue  A pointer to an array of characters where the value will be
1580                placed.  The number of BITS required is found by multiplying the
1581                BitSize and ReportCount fields of the Value Cap for this
1582                control.  The least significant bit of this control found in the
1583                given report will be placed in the least significant bit location
1584                of the buffer (little-endian format), regardless of whether
1585                or not the field is byte aligned or if the BitSize is a multiple
1586                of sizeof (CHAR).
1587
1588                See note above about current implementation limitations
1589
1590    UsageValueByteLength
1591                the length of the given UsageValue buffer.
1592
1593    PreparsedData The preparsed data returned by the HIDCLASS
1594
1595    Report      The report packet.
1596
1597    ReportLength   Length of the given report packet.
1598
1599 Return Value:
1600
1601 · HIDP_STATUS_SUCCESS                -- upon successfully retrieving the value
1602                                         from the report packet
1603 · HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
1604 · HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1605 · HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
1606                                         equal to the length specified in
1607                                         the HIDP_CAPS structure for the given
1608                                         ReportType
1609 · HIDP_STATUS_NOT_VALUE_ARRAY        -- if the control specified is not a
1610                                         value array -- a value array will have
1611                                         a ReportCount field in the
1612                                         HIDP_VALUE_CAPS structure that is > 1
1613                                         Use HidP_GetUsageValue instead
1614 · HIDP_STATUS_BUFFER_TOO_SMALL       -- if the size of the passed in buffer in
1615                                         which to return the array is too small
1616                                         (ie. has fewer values than the number of
1617                                         fields in the array
1618 · HIDP_STATUS_NOT_IMPLEMENTED        -- if the usage value array has field sizes
1619                                         that are not multiples of 8 bits, this
1620                                         error code is returned since the function
1621                                         currently does not handle getting values
1622                                         from such arrays.
1623 · HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1624                                         link collection exist but exists in
1625                                         a report with a different report ID
1626                                         than the report being passed in.  To
1627                                         set this value, call
1628                                         HidP_GetUsageValueArray with a
1629                                         different report packet
1630 · HIDP_STATUS_USAGE_NOT_FOUND        -- if the usage page, usage, and link
1631                                         collection combination does not exist
1632                                         in any reports for this ReportType
1633 --*/
1634
1635 NTSTATUS __stdcall
1636 HidP_UsageListDifference (
1637     IN    PUSAGE   PreviousUsageList,
1638     IN    PUSAGE   CurrentUsageList,
1639     OUT   PUSAGE   BreakUsageList,
1640     OUT   PUSAGE   MakeUsageList,
1641     IN    ULONG    UsageListLength
1642     );
1643 /*++
1644 Routine Description:
1645     This function will return the difference between a two lists of usages
1646     (as might be returned from HidP_GetUsages),  In other words, it will return
1647     return a list of usages that are in the current list but not the previous
1648     list as well as a list of usages that are in the previous list but not
1649     the current list.
1650
1651 Parameters:
1652
1653     PreviousUsageList   The list of usages before.
1654     CurrentUsageList    The list of usages now.
1655     BreakUsageList      Previous - Current.
1656     MakeUsageList       Current - Previous.
1657     UsageListLength     Represents the length of the usage lists in array
1658                         elements.  If comparing two lists with a differing
1659                         number of array elements, this value should be
1660                         the size of the larger of the two lists.  Any
1661                         zero found with a list indicates an early termination
1662                         of the list and any usages found after the first zero
1663                         will be ignored.
1664 --*/
1665
1666 NTSTATUS __stdcall
1667 HidP_UsageAndPageListDifference (
1668    IN    PUSAGE_AND_PAGE PreviousUsageList,
1669    IN    PUSAGE_AND_PAGE CurrentUsageList,
1670    OUT   PUSAGE_AND_PAGE BreakUsageList,
1671    OUT   PUSAGE_AND_PAGE MakeUsageList,
1672    IN    ULONG           UsageListLength
1673    );
1674
1675 //
1676 // Produce Make or Break Codes
1677 //
1678 typedef enum _HIDP_KEYBOARD_DIRECTION {
1679     HidP_Keyboard_Break,
1680     HidP_Keyboard_Make
1681 } HIDP_KEYBOARD_DIRECTION;
1682
1683 //
1684 // A bitmap of the current shift state of the keyboard when using the
1685 // below keyboard usages to i8042 translation function.
1686 //
1687 typedef struct _HIDP_KEYBOARD_MODIFIER_STATE {
1688    union {
1689       struct {
1690          ULONG LeftControl: 1;
1691          ULONG LeftShift: 1;
1692          ULONG LeftAlt: 1;
1693          ULONG LeftGUI: 1;
1694          ULONG RightControl: 1;
1695          ULONG RightShift: 1;
1696          ULONG RightAlt: 1;
1697          ULONG RigthGUI: 1;
1698          ULONG CapsLock: 1;
1699          ULONG ScollLock: 1;
1700          ULONG NumLock: 1;
1701          ULONG Reserved: 21;
1702       };
1703       ULONG ul;
1704    };
1705
1706 } HIDP_KEYBOARD_MODIFIER_STATE, * PHIDP_KEYBOARD_MODIFIER_STATE;
1707
1708 //
1709 // A call back function to give the i8042 scan codes to the caller of
1710 // the below translation function.
1711 //
1712 typedef BOOLEAN (* PHIDP_INSERT_SCANCODES) (
1713                   IN PVOID Context,  // Some caller supplied context.
1714                   IN PCHAR NewScanCodes, // A list of i8042 scan codes.
1715                   IN ULONG Length // the length of the scan codes.
1716                   );
1717
1718 NTSTATUS __stdcall
1719 HidP_TranslateUsageAndPagesToI8042ScanCodes (
1720     IN     PUSAGE_AND_PAGE               ChangedUsageList,
1721     IN     ULONG                         UsageListLength,
1722     IN     HIDP_KEYBOARD_DIRECTION       KeyAction,
1723     IN OUT PHIDP_KEYBOARD_MODIFIER_STATE ModifierState,
1724     IN     PHIDP_INSERT_SCANCODES        InsertCodesProcedure,
1725     IN     PVOID                         InsertCodesContext
1726     );
1727 /*++
1728 Routine Description:
1729 Parameters:
1730 --*/
1731
1732 NTSTATUS __stdcall
1733 HidP_TranslateUsagesToI8042ScanCodes (
1734     IN     PUSAGE                        ChangedUsageList,
1735     IN     ULONG                         UsageListLength,
1736     IN     HIDP_KEYBOARD_DIRECTION       KeyAction,
1737     IN OUT PHIDP_KEYBOARD_MODIFIER_STATE ModifierState,
1738     IN     PHIDP_INSERT_SCANCODES        InsertCodesProcedure,
1739     IN     PVOID                         InsertCodesContext
1740     );
1741 /*++
1742 Routine Description:
1743 Parameters:
1744 --*/
1745
1746
1747
1748 //
1749 // Define NT Status codes with Facility Code of FACILITY_HID_ERROR_CODE
1750 //
1751
1752 // FACILITY_HID_ERROR_CODE defined in ntstatus.h
1753 #ifndef FACILITY_HID_ERROR_CODE
1754 #define FACILITY_HID_ERROR_CODE 0x11
1755 #endif
1756
1757 #define HIDP_ERROR_CODES(SEV, CODE) \
1758         ((NTSTATUS) (((SEV) << 28) | (FACILITY_HID_ERROR_CODE << 16) | (CODE)))
1759
1760 #define HIDP_STATUS_SUCCESS                  (HIDP_ERROR_CODES(0x0,0))
1761 #define HIDP_STATUS_NULL                     (HIDP_ERROR_CODES(0x8,1))
1762 #define HIDP_STATUS_INVALID_PREPARSED_DATA   (HIDP_ERROR_CODES(0xC,1))
1763 #define HIDP_STATUS_INVALID_REPORT_TYPE      (HIDP_ERROR_CODES(0xC,2))
1764 #define HIDP_STATUS_INVALID_REPORT_LENGTH    (HIDP_ERROR_CODES(0xC,3))
1765 #define HIDP_STATUS_USAGE_NOT_FOUND          (HIDP_ERROR_CODES(0xC,4))
1766 #define HIDP_STATUS_VALUE_OUT_OF_RANGE       (HIDP_ERROR_CODES(0xC,5))
1767 #define HIDP_STATUS_BAD_LOG_PHY_VALUES       (HIDP_ERROR_CODES(0xC,6))
1768 #define HIDP_STATUS_BUFFER_TOO_SMALL         (HIDP_ERROR_CODES(0xC,7))
1769 #define HIDP_STATUS_INTERNAL_ERROR           (HIDP_ERROR_CODES(0xC,8))
1770 #define HIDP_STATUS_I8042_TRANS_UNKNOWN      (HIDP_ERROR_CODES(0xC,9))
1771 #define HIDP_STATUS_INCOMPATIBLE_REPORT_ID   (HIDP_ERROR_CODES(0xC,0xA))
1772 #define HIDP_STATUS_NOT_VALUE_ARRAY          (HIDP_ERROR_CODES(0xC,0xB))
1773 #define HIDP_STATUS_IS_VALUE_ARRAY           (HIDP_ERROR_CODES(0xC,0xC))
1774 #define HIDP_STATUS_DATA_INDEX_NOT_FOUND     (HIDP_ERROR_CODES(0xC,0xD))
1775 #define HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE  (HIDP_ERROR_CODES(0xC,0xE))
1776 #define HIDP_STATUS_BUTTON_NOT_PRESSED       (HIDP_ERROR_CODES(0xC,0xF))
1777 #define HIDP_STATUS_REPORT_DOES_NOT_EXIST    (HIDP_ERROR_CODES(0xC,0x10))
1778 #define HIDP_STATUS_NOT_IMPLEMENTED          (HIDP_ERROR_CODES(0xC,0x20))
1779
1780 //
1781 // We blundered this status code.
1782 //
1783 #define HIDP_STATUS_I8242_TRANS_UNKNOWN HIDP_STATUS_I8042_TRANS_UNKNOWN
1784
1785 #include <poppack.h>
1786
1787 #endif