2 // SL: We use this file to generate P/Invoke using P/Invoke Interop Assistant.
6 typedef USHORT USAGE, *PUSAGE;
9 #define HIDP_LINK_COLLECTION_ROOT ((USHORT) -1)
10 #define HIDP_LINK_COLLECTION_UNSPECIFIED ((USHORT) 0)
13 typedef enum _HIDP_REPORT_TYPE
20 typedef struct _USAGE_AND_PAGE
24 } USAGE_AND_PAGE, *PUSAGE_AND_PAGE;
26 #define HidP_IsSameUsageAndPage(u1, u2) ((* (PULONG) &u1) == (* (PULONG) &u2))
28 typedef struct _HIDP_BUTTON_CAPS
35 USHORT LinkCollection; // A unique internal index pointer
41 BOOLEAN IsStringRange;
42 BOOLEAN IsDesignatorRange;
48 USAGE UsageMin, UsageMax;
49 USHORT StringMin, StringMax;
50 USHORT DesignatorMin, DesignatorMax;
51 USHORT DataIndexMin, DataIndexMax;
54 USAGE Usage, Reserved1;
55 USHORT StringIndex, Reserved2;
56 USHORT DesignatorIndex, Reserved3;
57 USHORT DataIndex, Reserved4;
61 } HIDP_BUTTON_CAPS, *PHIDP_BUTTON_CAPS;
64 typedef struct _HIDP_VALUE_CAPS
71 USHORT LinkCollection; // A unique internal index pointer
77 BOOLEAN IsStringRange;
78 BOOLEAN IsDesignatorRange;
81 BOOLEAN HasNull; // Does this channel have a null report union
83 USHORT BitSize; // How many bits are devoted to this value?
85 USHORT ReportCount; // See Note below. Usually set to 1.
91 LONG LogicalMin, LogicalMax;
92 LONG PhysicalMin, PhysicalMax;
96 USAGE UsageMin, UsageMax;
97 USHORT StringMin, StringMax;
98 USHORT DesignatorMin, DesignatorMax;
99 USHORT DataIndexMin, DataIndexMax;
103 USAGE Usage, Reserved1;
104 USHORT StringIndex, Reserved2;
105 USHORT DesignatorIndex, Reserved3;
106 USHORT DataIndex, Reserved4;
109 } HIDP_VALUE_CAPS, *PHIDP_VALUE_CAPS;
114 // ReportCount: When a report descriptor declares an Input, Output, or
115 // Feature main item with fewer usage declarations than the report count, then
116 // the last usage applies to all remaining unspecified count in that main item.
117 // (As an example you might have data that required many fields to describe,
118 // possibly buffered bytes.) In this case, only one value cap structure is
119 // allocated for these associtated fields, all with the same usage, and Report
120 // Count reflects the number of fields involved. Normally ReportCount is 1.
121 // To access all of the fields in such a value structure would require using
122 // HidP_GetUsageValueArray and HidP_SetUsageValueArray. HidP_GetUsageValue/
123 // HidP_SetScaledUsageValue will also work, however, these functions will only
124 // work with the first field of the structure.
128 // The link collection tree consists of an array of LINK_COLLECTION_NODES
129 // where the index into this array is the same as the collection number.
131 // Given a collection A which contains a subcollection B, A is defined to be
132 // the parent B, and B is defined to be the child.
134 // Given collections A, B, and C where B and C are children of A, and B was
135 // encountered before C in the report descriptor, B is defined as a sibling of
136 // C. (This implies, of course, that if B is a sibling of C, then C is NOT a
139 // B is defined as the NextSibling of C if and only if there exists NO
140 // child collection of A, call it D, such that B is a sibling of D and D
141 // is a sibling of C.
143 // E is defined to be the FirstChild of A if and only if for all children of A,
144 // F, that are not equivalent to E, F is a sibling of E.
145 // (This implies, of course, that the does not exist a child of A, call it G,
146 // where E is a sibling of G). In other words the first sibling is the last
147 // link collection found in the list.
149 // In other words, if a collection B is defined within the definition of another
150 // collection A, B becomes a child of A. All collections with the same parent
151 // are considered siblings. The FirstChild of the parent collection, A, will be
152 // last collection defined that has A as a parent. The order of sibling pointers
153 // is similarly determined. When a collection B is defined, it becomes the
154 // FirstChild of it's parent collection. The previously defined FirstChild of the
155 // parent collection becomes the NextSibling of the new collection. As new
156 // collections with the same parent are discovered, the chain of sibling is built.
158 // With that in mind, the following describes conclusively a data structure
159 // that provides direct traversal up, down, and accross the link collection
163 typedef struct _HIDP_LINK_COLLECTION_NODE
168 USHORT NumberOfChildren;
171 ULONG CollectionType: 8; // As defined in 6.2.2.6 of HID spec
172 ULONG IsAlias : 1; // This link node is an allias of the next link node.
174 PVOID UserContext; // The user can hang his coat here.
175 } HIDP_LINK_COLLECTION_NODE, *PHIDP_LINK_COLLECTION_NODE;
178 // When a link collection is described by a delimiter, alias link collection
179 // nodes are created. (One for each usage within the delimiter).
180 // The parser assigns each capability description listed above only one
183 // If a control is defined within a collection defined by
184 // delimited usages, then that control is said to be within multiple link
185 // collections, one for each usage within the open and close delimiter tokens.
186 // Such multiple link collecions are said to be aliases. The first N-1 such
187 // collections, listed in the link collection node array, have their IsAlias
188 // bit set. The last such link collection is the link collection index used
189 // in the capabilities described above.
190 // Clients wishing to set a control in an aliased collection, should walk the
191 // collection array once for each time they see the IsAlias flag set, and use
192 // the last link collection as the index for the below accessor functions.
194 // NB: if IsAlias is set, then NextSibling should be one more than the current
195 // link collection node index.
198 typedef PUCHAR PHIDP_REPORT_DESCRIPTOR;
199 typedef struct _HIDP_PREPARSED_DATA * PHIDP_PREPARSED_DATA;
201 typedef struct _HIDP_CAPS
205 USHORT InputReportByteLength;
206 USHORT OutputReportByteLength;
207 USHORT FeatureReportByteLength;
210 USHORT NumberLinkCollectionNodes;
212 USHORT NumberInputButtonCaps;
213 USHORT NumberInputValueCaps;
214 USHORT NumberInputDataIndices;
216 USHORT NumberOutputButtonCaps;
217 USHORT NumberOutputValueCaps;
218 USHORT NumberOutputDataIndices;
220 USHORT NumberFeatureButtonCaps;
221 USHORT NumberFeatureValueCaps;
222 USHORT NumberFeatureDataIndices;
223 } HIDP_CAPS, *PHIDP_CAPS;
225 typedef struct _HIDP_DATA
230 ULONG RawValue; // for values
231 BOOLEAN On; // for buttons MUST BE TRUE for buttons.
233 } HIDP_DATA, *PHIDP_DATA;
235 // The HIDP_DATA structure is used with HidP_GetData and HidP_SetData
238 // The parser contiguously assigns every control (button or value) in a hid
239 // device a unique data index from zero to NumberXXXDataIndices -1 , inclusive.
240 // This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures.
242 // Most clients will find the Get/Set Buttons / Value accessor functions
243 // sufficient to their needs, as they will allow the clients to access the
244 // data known to them while ignoring the other controls.
246 // More complex clients, which actually read the Button / Value Caps, and which
247 // do a value add service to these routines (EG Direct Input), will need to
248 // access all the data in the device without interest in the individual usage
249 // or link collection location. These are the clients that will find
253 typedef struct _HIDP_UNKNOWN_TOKEN
258 } HIDP_UNKNOWN_TOKEN, *PHIDP_UNKNOWN_TOKEN;
260 typedef struct _HIDP_EXTENDED_ATTRIBUTES
262 UCHAR NumGlobalUnknowns;
264 PHIDP_UNKNOWN_TOKEN GlobalUnknowns;
265 // ... Additional attributes
266 ULONG Data [1]; // variableLength DO NOT ACCESS THIS FIELD
267 } HIDP_EXTENDED_ATTRIBUTES, *PHIDP_EXTENDED_ATTRIBUTES;
271 PHIDP_PREPARSED_DATA PreparsedData,
272 PHIDP_CAPS Capabilities
276 Returns a list of capabilities of a given hid device as described by its
280 PreparsedData The preparsed data returned from HIDCLASS.
281 Capabilities a HIDP_CAPS structure
285 HIDP_STATUS_INVALID_PREPARSED_DATA
289 HidP_GetLinkCollectionNodes (
290 PHIDP_LINK_COLLECTION_NODE LinkCollectionNodes,
291 PULONG LinkCollectionNodesLength,
292 PHIDP_PREPARSED_DATA PreparsedData
296 Return a list of PHIDP_LINK_COLLECTION_NODEs used to describe the link
297 collection tree of this hid device. See the above description of
298 struct _HIDP_LINK_COLLECTION_NODE.
301 LinkCollectionNodes - a caller allocated array into which
302 HidP_GetLinkCollectionNodes will store the information
304 LinKCollectionNodesLength - the caller sets this value to the length of the
305 the array in terms of number of elements.
306 HidP_GetLinkCollectionNodes sets this value to the actual
307 number of elements set. The total number of nodes required to
308 describe this HID device can be found in the
309 NumberLinkCollectionNodes field in the HIDP_CAPS structure.
314 HidP_GetSpecificButtonCaps (
315 HIDP_REPORT_TYPE ReportType,
316 USAGE UsagePage, // Optional (0 => ignore)
317 USHORT LinkCollection, // Optional (0 => ignore)
318 USAGE Usage, // Optional (0 => ignore)
319 PHIDP_BUTTON_CAPS ButtonCaps,
320 PUSHORT ButtonCapsLength,
321 PHIDP_PREPARSED_DATA PreparsedData
325 HidP_GetButtonCaps returns all the buttons (binary values) that are a part
326 of the given report type for the Hid device represented by the given
330 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
332 UsagePage A usage page value used to limit the button caps returned to
333 those on a given usage page. If set to 0, this parameter is
334 ignored. Can be used with LinkCollection and Usage parameters
335 to further limit the number of button caps structures returned.
337 LinkCollection HIDP_LINK_COLLECTION node array index used to limit the
338 button caps returned to those buttons in a given link
339 collection. If set to 0, this parameter is
340 ignored. Can be used with UsagePage and Usage parameters
341 to further limit the number of button caps structures
344 Usage A usage value used to limit the button caps returned to those
345 with the specified usage value. If set to 0, this parameter
346 is ignored. Can be used with LinkCollection and UsagePage
347 parameters to further limit the number of button caps
350 ButtonCaps A _HIDP_BUTTON_CAPS array containing information about all the
351 binary values in the given report. This buffer is provided by
354 ButtonLength As input, this parameter specifies the length of the
355 ButtonCaps parameter (array) in number of array elements.
356 As output, this value is set to indicate how many of those
357 array elements were filled in by the function. The maximum number of
358 button caps that can be returned is found in the HIDP_CAPS
359 structure. If HIDP_STATUS_BUFFER_TOO_SMALL is returned,
360 this value contains the number of array elements needed to
361 successfully complete the request.
363 PreparsedData The preparsed data returned from HIDCLASS.
367 HidP_GetSpecificButtonCaps returns the following error codes:
369 HIDP_STATUS_INVALID_REPORT_TYPE
370 HIDP_STATUS_INVALID_PREPARSED_DATA
371 HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in)
372 HIDP_STATUS_USAGE_NOT_FOUND
376 HIDP_REPORT_TYPE ReportType,
377 PHIDP_BUTTON_CAPS ButtonCaps,
378 PUSHORT ButtonCapsLength,
379 PHIDP_PREPARSED_DATA PreparsedData
383 HidP_GetSpecificValueCaps (
384 HIDP_REPORT_TYPE ReportType,
385 USAGE UsagePage, // Optional (0 => ignore)
386 USHORT LinkCollection, // Optional (0 => ignore)
387 USAGE Usage, // Optional (0 => ignore)
388 PHIDP_VALUE_CAPS ValueCaps,
389 PUSHORT ValueCapsLength,
390 PHIDP_PREPARSED_DATA PreparsedData
394 HidP_GetValueCaps returns all the values (non-binary) that are a part
395 of the given report type for the Hid device represented by the given
399 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
401 UsagePage A usage page value used to limit the value caps returned to
402 those on a given usage page. If set to 0, this parameter is
403 ignored. Can be used with LinkCollection and Usage parameters
404 to further limit the number of value caps structures returned.
406 LinkCollection HIDP_LINK_COLLECTION node array index used to limit the
407 value caps returned to those buttons in a given link
408 collection. If set to 0, this parameter is
409 ignored. Can be used with UsagePage and Usage parameters
410 to further limit the number of value caps structures
413 Usage A usage value used to limit the value caps returned to those
414 with the specified usage value. If set to 0, this parameter
415 is ignored. Can be used with LinkCollection and UsagePage
416 parameters to further limit the number of value caps
419 ValueCaps A _HIDP_VALUE_CAPS array containing information about all the
420 non-binary values in the given report. This buffer is provided
423 ValueLength As input, this parameter specifies the length of the ValueCaps
424 parameter (array) in number of array elements. As output,
425 this value is set to indicate how many of those array elements
426 were filled in by the function. The maximum number of
427 value caps that can be returned is found in the HIDP_CAPS
428 structure. If HIDP_STATUS_BUFFER_TOO_SMALL is returned,
429 this value contains the number of array elements needed to
430 successfully complete the request.
432 PreparsedData The preparsed data returned from HIDCLASS.
436 HidP_GetValueCaps returns the following error codes:
438 HIDP_STATUS_INVALID_REPORT_TYPE
439 HIDP_STATUS_INVALID_PREPARSED_DATA
440 HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in)
441 HIDP_STATUS_USAGE_NOT_FOUND
447 HIDP_REPORT_TYPE ReportType,
448 PHIDP_VALUE_CAPS ValueCaps,
449 PUSHORT ValueCapsLength,
450 PHIDP_PREPARSED_DATA PreparsedData
454 HidP_GetExtendedAttributes (
455 HIDP_REPORT_TYPE ReportType,
457 PHIDP_PREPARSED_DATA PreparsedData,
458 PHIDP_EXTENDED_ATTRIBUTES Attributes,
459 PULONG LengthAttributes
463 Given a data index from the value or button capabilities of a given control
464 return any extended attributes for the control if any exist.
467 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
469 DataIndex The data index for the given control, found in the capabilities
470 structure for that control
472 PreparsedData The preparsed data returned from HIDCLASS.
474 Attributes Pointer to a buffer into which the extended attribute data will
477 LengthAttributes Length of the given buffer in bytes.
481 HIDP_STATUS_DATA_INDEX_NOT_FOUND
485 HidP_InitializeReportForID (
486 HIDP_REPORT_TYPE ReportType,
488 PHIDP_PREPARSED_DATA PreparsedData,
496 Initialize a report based on the given report ID.
500 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
502 PreparasedData Preparsed data structure returned by HIDCLASS
504 Report Buffer which to set the data into.
506 ReportLength Length of Report...Report should be at least as long as the
507 value indicated in the HIDP_CAPS structure for the device and
508 the corresponding ReportType
512 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
513 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
514 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal
515 to the length specified in HIDP_CAPS
516 structure for the given ReportType
517 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
518 for the given ReportType
524 HIDP_REPORT_TYPE ReportType,
527 PHIDP_PREPARSED_DATA PreparsedData,
535 Please Note: Since usage value arrays deal with multiple fields for
536 for one usage value, they cannot be used with HidP_SetData
537 and HidP_GetData. In this case,
538 HIDP_STATUS_IS_USAGE_VALUE_ARRAY will be returned.
542 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
544 DataList Array of HIDP_DATA structures that contains the data values
545 that are to be set into the given report
547 DataLength As input, length in array elements of DataList. As output,
548 contains the number of data elements set on successful
549 completion or an index into the DataList array to identify
550 the faulting HIDP_DATA value if an error code is returned.
552 PreparasedData Preparsed data structure returned by HIDCLASS
554 Report Buffer which to set the data into.
556 ReportLength Length of Report...Report should be at least as long as the
557 value indicated in the HIDP_CAPS structure for the device and
558 the corresponding ReportType
561 HidP_SetData returns the following error codes. The report packet will
562 have all the data set up until the HIDP_DATA structure that caused the
563 error. DataLength, in the error case, will return this problem index.
565 HIDP_STATUS_SUCCESS -- upon successful insertion of all data
566 into the report packet.
567 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
568 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
569 HIDP_STATUS_DATA_INDEX_NOT_FOUND -- if a HIDP_DATA structure referenced a
570 data index that does not exist for this
572 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal
573 to the length specified in HIDP_CAPS
574 structure for the given ReportType
575 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
576 for the given ReportType
577 HIDP_STATUS_IS_USAGE_VALUE_ARRAY -- if one of the HIDP_DATA structures
578 references a usage value array.
579 DataLength will contain the index into
580 the array that was invalid
581 HIDP_STATUS_BUTTON_NOT_PRESSED -- if a HIDP_DATA structure attempted
582 to unset a button that was not already
584 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- a HIDP_DATA structure was found with
585 a valid index value but is contained
586 in a different report than the one
587 currently being processed
588 HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough entries in
589 a given Main Array Item to report all
590 buttons that have been requested to be
596 HIDP_REPORT_TYPE ReportType,
599 PHIDP_PREPARSED_DATA PreparsedData,
607 Please Note: For obvious reasons HidP_SetData and HidP_GetData will not
608 access UsageValueArrays.
611 ReportType One of HidP_Input, HidP_Output, or HidP_Feature.
613 DataList Array of HIDP_DATA structures that will receive the data
614 values that are set in the given report
616 DataLength As input, length in array elements of DataList. As output,
617 contains the number of data elements that were successfully
618 set by HidP_GetData. The maximum size necessary for DataList
619 can be determined by calling HidP_MaxDataListLength
621 PreparasedData Preparsed data structure returned by HIDCLASS
623 Report Buffer which to set the data into.
625 ReportLength Length of Report...Report should be at least as long as the
626 value indicated in the HIDP_CAPS structure for the device and
627 the corresponding ReportType
630 HidP_GetData returns the following error codes.
632 HIDP_STATUS_SUCCESS -- upon successful retrieval of all data
633 from the report packet.
634 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
635 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
636 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal
637 to the length specified in HIDP_CAPS
638 structure for the given ReportType
639 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
640 for the given ReportType
641 HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough array entries in
642 DataList to store all the indice values
643 in the given report. DataLength will
644 contain the number of array entries
645 required to hold all data
650 HidP_MaxDataListLength (
651 HIDP_REPORT_TYPE ReportType,
652 PHIDP_PREPARSED_DATA PreparsedData
657 This function returns the maximum length of HIDP_DATA elements that
658 HidP_GetData could return for the given report type.
662 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
664 PreparsedData Preparsed data structure returned by HIDCLASS
668 The length of the data list array required for the HidP_GetData function
669 call. If an error occurs (either HIDP_STATUS_INVALID_REPORT_TYPE or
670 HIDP_STATUS_INVALID_PREPARSED_DATA), this function returns 0.
674 #define HidP_SetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \
675 HidP_SetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle)
680 HIDP_REPORT_TYPE ReportType,
682 USHORT LinkCollection,
685 PHIDP_PREPARSED_DATA PreparsedData,
692 This function sets binary values (buttons) in a report. Given an
693 initialized packet of correct length, it modifies the report packet so that
694 each element in the given list of usages has been set in the report packet.
695 For example, in an output report with 5 LED's, each with a given usage,
696 an application could turn on any subset of these lights by placing their
697 usages in any order into the usage array (UsageList). HidP_SetUsages would,
698 in turn, set the appropriate bit or add the corresponding byte into the
701 A properly initialized Report packet is one of the correct byte length,
704 NOTE: A packet that has already been set with a call to a HidP_Set routine
705 can also be passed in. This routine then sets processes the UsageList
706 in the same fashion but verifies that the ReportID already set in
707 Report matches the report ID for the given usages.
710 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
712 UsagePage All of the usages in the usage array, which HidP_SetUsages will
713 set in the report, refer to this same usage page.
714 If a client wishes to set usages in a report for multiple
715 usage pages then that client needs to make multiple calls to
716 HidP_SetUsages for each of the usage pages.
718 UsageList A usage array containing the usages that HidP_SetUsages will set in
721 UsageLength The length of the given usage array in array elements.
722 The parser will set this value to the position in the usage
723 array where it stopped processing. If successful, UsageLength
724 will be unchanged. In any error condition, this parameter
725 reflects how many of the usages in the usage list have
726 actually been set by the parser. This is useful for finding
727 the usage in the list which caused the error.
729 PreparsedData The preparsed data recevied from HIDCLASS
731 Report The report packet.
733 ReportLength Length of the given report packet...Must be equal to the
734 value reported in the HIDP_CAPS structure for the device
735 and corresponding report type.
738 HidP_SetUsages returns the following error codes. On error, the report packet
739 will be correct up until the usage element that caused the error.
741 HIDP_STATUS_SUCCESS -- upon successful insertion of all usages
742 into the report packet.
743 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
744 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
745 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
746 equal to the length specified in
747 the HIDP_CAPS structure for the given
749 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
750 for the given ReportType
751 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a
752 different report. If the report is
753 zero-initialized on entry the first
754 usage in the list will determine which
755 report ID is used. Otherwise, the
756 parser will verify that usage matches
757 the passed in report's ID
758 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage does not exist for any
759 report (no matter what the report ID)
760 for the given report type.
761 HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough entries in a
762 given Main Array Item to list all of
763 the given usages. The caller needs
764 to split his request into more than
768 #define HidP_UnsetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \
769 HidP_UnsetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle)
774 HIDP_REPORT_TYPE ReportType,
776 USHORT LinkCollection,
779 PHIDP_PREPARSED_DATA PreparsedData,
786 This function unsets (turns off) binary values (buttons) in the report. Given
787 an initialized packet of correct length, it modifies the report packet so
788 that each element in the given list of usages has been unset in the
791 This function is the "undo" operation for SetUsages. If the given usage
792 is not already set in the Report, it will return an error code of
793 HIDP_STATUS_BUTTON_NOT_PRESSED. If the button is pressed, HidP_UnsetUsages
794 will unset the appropriate bit or remove the corresponding index value from
795 the HID Main Array Item.
797 A properly initialized Report packet is one of the correct byte length,
800 NOTE: A packet that has already been set with a call to a HidP_Set routine
801 can also be passed in. This routine then processes the UsageList
802 in the same fashion but verifies that the ReportID already set in
803 Report matches the report ID for the given usages.
806 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
808 UsagePage All of the usages in the usage array, which HidP_UnsetUsages will
809 unset in the report, refer to this same usage page.
810 If a client wishes to unset usages in a report for multiple
811 usage pages then that client needs to make multiple calls to
812 HidP_UnsetUsages for each of the usage pages.
814 UsageList A usage array containing the usages that HidP_UnsetUsages will
815 unset in the report packet.
817 UsageLength The length of the given usage array in array elements.
818 The parser will set this value to the position in the usage
819 array where it stopped processing. If successful, UsageLength
820 will be unchanged. In any error condition, this parameter
821 reflects how many of the usages in the usage list have
822 actually been unset by the parser. This is useful for finding
823 the usage in the list which caused the error.
825 PreparsedData The preparsed data recevied from HIDCLASS
827 Report The report packet.
829 ReportLength Length of the given report packet...Must be equal to the
830 value reported in the HIDP_CAPS structure for the device
831 and corresponding report type.
834 HidP_UnsetUsages returns the following error codes. On error, the report
835 packet will be correct up until the usage element that caused the error.
837 HIDP_STATUS_SUCCESS -- upon successful "unsetting" of all usages
838 in the report packet.
839 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
840 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
841 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
842 equal to the length specified in
843 the HIDP_CAPS structure for the given
845 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
846 for the given ReportType
847 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a
848 different report. If the report is
849 zero-initialized on entry the first
850 usage in the list will determine which
851 report ID is used. Otherwise, the
852 parser will verify that usage matches
853 the passed in report's ID
854 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage does not exist for any
855 report (no matter what the report ID)
856 for the given report type.
857 HIDP_STATUS_BUTTON_NOT_PRESSED -- if a usage corresponds to a button that
858 is not already set in the given report
861 #define HidP_GetButtons(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) \
862 HidP_GetUsages(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe)
867 HIDP_REPORT_TYPE ReportType,
869 USHORT LinkCollection,
872 PHIDP_PREPARSED_DATA PreparsedData,
879 This function returns the binary values (buttons) that are set in a HID
880 report. Given a report packet of correct length, it searches the report
881 packet for each usage for the given usage page and returns them in the
885 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
887 UsagePage All of the usages in the usage list, which HidP_GetUsages will
888 retrieve in the report, refer to this same usage page.
889 If the client wishes to get usages in a packet for multiple
890 usage pages then that client needs to make multiple calls
893 LinkCollection An optional value which can limit which usages are returned
894 in the UsageList to those usages that exist in a specific
895 LinkCollection. A non-zero value indicates the index into
896 the HIDP_LINK_COLLECITON_NODE list returned by
897 HidP_GetLinkCollectionNodes of the link collection the
898 usage should belong to. A value of 0 indicates this
899 should value be ignored.
901 UsageList The usage array that will contain all the usages found in
904 UsageLength The length of the given usage array in array elements.
905 On input, this value describes the length of the usage list.
906 On output, HidP_GetUsages sets this value to the number of
907 usages that was found. Use HidP_MaxUsageListLength to
908 determine the maximum length needed to return all the usages
909 that a given report packet may contain.
911 PreparsedData Preparsed data structure returned by HIDCLASS
913 Report The report packet.
915 ReportLength Length (in bytes) of the given report packet
919 HidP_GetUsages returns the following error codes:
921 HIDP_STATUS_SUCCESS -- upon successfully retrieving all the
922 usages from the report packet
923 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
924 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
925 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
926 equal to the length specified in
927 the HIDP_CAPS structure for the given
929 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
930 for the given ReportType
931 HIDP_STATUS_BUFFER_TOO_SMALL -- if the UsageList is not big enough to
932 hold all the usages found in the report
933 packet. If this is returned, the buffer
934 will contain UsageLength number of
935 usages. Use HidP_MaxUsageListLength to
936 find the maximum length needed
937 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages
938 that match the UsagePage and
939 LinkCollection specified could be found
940 in a report with a different report ID
941 HIDP_STATUS_USAGE_NOT_FOUND -- if there are no usages in a reports for
942 the device and ReportType that match the
943 UsagePage and LinkCollection that were
947 #define HidP_GetButtonsEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe) \
948 HidP_GetUsagesEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe)
952 HIDP_REPORT_TYPE ReportType,
953 USHORT LinkCollection, // Optional
954 PUSAGE_AND_PAGE ButtonList,
956 PHIDP_PREPARSED_DATA PreparsedData,
957 reads_bytes_(ReportLength) PCHAR Report,
964 This function returns the binary values (buttons) in a HID report.
965 Given a report packet of correct length, it searches the report packet
966 for all buttons and returns the UsagePage and Usage for each of the buttons
970 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
972 LinkCollection An optional value which can limit which usages are returned
973 in the ButtonList to those usages that exist in a specific
974 LinkCollection. A non-zero value indicates the index into
975 the HIDP_LINK_COLLECITON_NODE list returned by
976 HidP_GetLinkCollectionNodes of the link collection the
977 usage should belong to. A value of 0 indicates this
978 should value be ignored.
980 ButtonList An array of USAGE_AND_PAGE structures describing all the
981 buttons currently ``down'' in the device.
983 UsageLength The length of the given array in terms of elements.
984 On input, this value describes the length of the list. On
985 output, HidP_GetUsagesEx sets this value to the number of
986 usages that were found. Use HidP_MaxUsageListLength to
987 determine the maximum length needed to return all the usages
988 that a given report packet may contain.
990 PreparsedData Preparsed data returned by HIDCLASS
992 Report The report packet.
994 ReportLength Length (in bytes) of the given report packet.
998 HidP_GetUsagesEx returns the following error codes:
1000 HIDP_STATUS_SUCCESS -- upon successfully retrieving all the
1001 usages from the report packet
1002 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1003 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1004 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1005 equal to the length specified in
1006 the HIDP_CAPS structure for the given
1008 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
1009 for the given ReportType
1010 HIDP_STATUS_BUFFER_TOO_SMALL -- if ButtonList is not big enough to
1011 hold all the usages found in the report
1012 packet. If this is returned, the buffer
1013 will contain UsageLength number of
1014 usages. Use HidP_MaxUsageListLength to
1015 find the maximum length needed
1016 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages
1017 that match the specified LinkCollection
1018 exist in report with a different report
1020 HIDP_STATUS_USAGE_NOT_FOUND -- if there are no usages in any reports that
1021 match the LinkCollection parameter
1024 _IRQL_requires_max_(PASSIVE_LEVEL)
1026 HidP_MaxUsageListLength (
1027 HIDP_REPORT_TYPE ReportType,
1028 USAGE UsagePage, // Optional
1029 PHIDP_PREPARSED_DATA PreparsedData
1032 Routine Description:
1033 This function returns the maximum number of usages that a call to
1034 HidP_GetUsages or HidP_GetUsagesEx could return for a given HID report.
1035 If calling for number of usages returned by HidP_GetUsagesEx, use 0 as
1036 the UsagePage value.
1039 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
1041 UsagePage Specifies the optional UsagePage to query for. If 0, will
1042 return all the maximum number of usage values that could be
1043 returned for a given ReportType. If non-zero, will return
1044 the maximum number of usages that would be returned for the
1045 ReportType with the given UsagePage.
1047 PreparsedData Preparsed data returned from HIDCLASS
1050 The length of the usage list array required for the HidP_GetUsages or
1051 HidP_GetUsagesEx function call. If an error occurs (such as
1052 HIDP_STATUS_INVALID_REPORT_TYPE or HIDP_INVALID_PREPARSED_DATA, this
1058 HidP_SetUsageValue (
1059 HIDP_REPORT_TYPE ReportType,
1061 USHORT LinkCollection,
1064 PHIDP_PREPARSED_DATA PreparsedData,
1065 updates_bytes_(ReportLength) PCHAR Report,
1070 HidP_SetUsageValue inserts a value into the HID Report Packet in the field
1071 corresponding to the given usage page and usage. HidP_SetUsageValue
1072 casts this value to the appropriate bit length. If a report packet
1073 contains two different fields with the same Usage and UsagePage,
1074 they can be distinguished with the optional LinkCollection field value.
1075 Using this function sets the raw value into the report packet with
1076 no checking done as to whether it actually falls within the logical
1077 minimum/logical maximum range. Use HidP_SetScaledUsageValue for this...
1079 NOTE: Although the UsageValue parameter is a ULONG, any casting that is
1080 done will preserve or sign-extend the value. The value being set
1081 should be considered a LONG value and will be treated as such by
1086 ReportType One of HidP_Output or HidP_Feature.
1088 UsagePage The usage page to which the given usage refers.
1090 LinkCollection (Optional) This value can be used to differentiate
1091 between two fields that may have the same
1092 UsagePage and Usage but exist in different
1093 collections. If the link collection value
1094 is zero, this function will set the first field
1095 it finds that matches the usage page and
1098 Usage The usage whose value HidP_SetUsageValue will set.
1100 UsageValue The raw value to set in the report buffer. This value must be within
1101 the logical range or if a NULL value this value should be the
1102 most negative value that can be represented by the number of bits
1105 PreparsedData The preparsed data returned for HIDCLASS
1107 Report The report packet.
1109 ReportLength Length (in bytes) of the given report packet.
1113 HidP_SetUsageValue returns the following error codes:
1115 HIDP_STATUS_SUCCESS -- upon successfully setting the value
1116 in the report packet
1117 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1118 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1119 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1120 equal to the length specified in
1121 the HIDP_CAPS structure for the given
1123 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
1124 for the given ReportType
1125 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1126 link collection exist but exists in
1127 a report with a different report ID
1128 than the report being passed in. To
1129 set this value, call HidP_SetUsageValue
1130 again with a zero-initizialed report
1132 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1133 collection combination does not exist
1134 in any reports for this ReportType
1138 HidP_SetScaledUsageValue (
1139 HIDP_REPORT_TYPE ReportType,
1141 USHORT LinkCollection,
1144 PHIDP_PREPARSED_DATA PreparsedData,
1145 updates_bytes_(ReportLength) PCHAR Report,
1151 HidP_SetScaledUsageValue inserts the UsageValue into the HID report packet
1152 in the field corresponding to the given usage page and usage. If a report
1153 packet contains two different fields with the same Usage and UsagePage,
1154 they can be distinguished with the optional LinkCollection field value.
1156 If the specified field has a defined physical range, this function converts
1157 the physical value specified to the corresponding logical value for the
1158 report. If a physical value does not exist, the function will verify that
1159 the value specified falls within the logical range and set according.
1161 If the range checking fails but the field has NULL values, the function will
1162 set the field to the defined NULL value (most negative number possible) and
1163 return HIDP_STATUS_NULL. In other words, use this function to set NULL
1164 values for a given field by passing in a value that falls outside the
1165 physical range if it is defined or the logical range otherwise.
1167 If the field does not support NULL values, an out of range error will be
1172 ReportType One of HidP_Output or HidP_Feature.
1174 UsagePage The usage page to which the given usage refers.
1176 LinkCollection (Optional) This value can be used to differentiate
1177 between two fields that may have the same
1178 UsagePage and Usage but exist in different
1179 collections. If the link collection value
1180 is zero, this function will set the first field
1181 it finds that matches the usage page and
1184 Usage The usage whose value HidP_SetScaledUsageValue will set.
1186 UsageValue The value to set in the report buffer. See the routine
1187 description above for the different interpretations of this
1190 PreparsedData The preparsed data returned from HIDCLASS
1192 Report The report packet.
1194 ReportLength Length (in bytes) of the given report packet.
1198 HidP_SetScaledUsageValue returns the following error codes:
1200 HIDP_STATUS_SUCCESS -- upon successfully setting the value
1201 in the report packet
1202 HIDP_STATUS_NULL -- upon successfully setting the value
1203 in the report packet as a NULL value
1204 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1205 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1206 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1207 equal to the length specified in
1208 the HIDP_CAPS structure for the given
1210 HIDP_STATUS_VALUEOF_RANGE -- if the value specified failed to fall
1211 within the physical range if it exists
1212 or within the logical range otherwise
1213 and the field specified by the usage
1214 does not allow NULL values
1215 HIDP_STATUS_BAD_LOG_PHY_VALUES -- if the field has a physical range but
1216 either the logical range is invalid
1217 (max <= min) or the physical range is
1219 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1220 link collection exist but exists in
1221 a report with a different report ID
1222 than the report being passed in. To
1223 set this value, call
1224 HidP_SetScaledUsageValue again with
1225 a zero-initialized report packet
1226 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1227 collection combination does not exist
1228 in any reports for this ReportType
1232 HidP_SetUsageValueArray (
1233 HIDP_REPORT_TYPE ReportType,
1235 USHORT LinkCollection,
1237 reads_bytes_(UsageValueByteLength) PCHAR UsageValue,
1238 USHORT UsageValueByteLength,
1239 PHIDP_PREPARSED_DATA PreparsedData,
1240 updates_bytes_(ReportLength) PCHAR Report,
1246 A usage value array occurs when the last usage in the list of usages
1247 describing a main item must be repeated because there are less usages defined
1248 than there are report counts declared for the given main item. In this case
1249 a single value cap is allocated for that usage and the report count of that
1250 value cap is set to reflect the number of fields to which that usage refers.
1252 HidP_SetUsageValueArray sets the raw bits for that usage which spans
1253 more than one field in a report.
1255 NOTE: This function currently does not support value arrays where the
1256 ReportSize for each of the fields in the array is not a multiple
1259 The UsageValue buffer should have the values set as they would appear
1260 in the report buffer. If this function supported non 8-bit multiples
1261 for the ReportSize then caller should format the input buffer so that
1262 each new value begins at the bit immediately following the last bit
1263 of the previous value
1267 ReportType One of HidP_Output or HidP_Feature.
1269 UsagePage The usage page to which the given usage refers.
1271 LinkCollection (Optional) This value can be used to differentiate
1272 between two fields that may have the same
1273 UsagePage and Usage but exist in different
1274 collections. If the link collection value
1275 is zero, this function will set the first field
1276 it finds that matches the usage page and
1279 Usage The usage whose value array HidP_SetUsageValueArray will set.
1281 UsageValue The buffer with the values to set into the value array.
1282 The number of BITS required is found by multiplying the
1283 BitSize and ReportCount fields of the Value Cap for this
1284 control. The least significant bit of this control found in the
1285 given report will be placed in the least significan bit location
1286 of the array given (little-endian format), regardless of whether
1287 or not the field is byte alligned or if the BitSize is a multiple
1290 See the above note for current implementation limitations.
1292 UsageValueByteLength Length of the UsageValue buffer (in bytes)
1294 PreparsedData The preparsed data returned from HIDCLASS
1296 Report The report packet.
1298 ReportLength Length (in bytes) of the given report packet.
1302 HIDP_STATUS_SUCCESS -- upon successfully setting the value
1303 array in the report packet
1304 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1305 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1306 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1307 equal to the length specified in
1308 the HIDP_CAPS structure for the given
1310 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
1311 for the given ReportType
1312 HIDP_STATUS_NOT_VALUE_ARRAY -- if the control specified is not a
1313 value array -- a value array will have
1314 a ReportCount field in the
1315 HIDP_VALUE_CAPS structure that is > 1
1316 Use HidP_SetUsageValue instead
1317 HIDP_STATUS_BUFFER_TOO_SMALL -- if the size of the passed in buffer with
1318 the values to set is too small (ie. has
1319 fewer values than the number of fields in
1321 HIDP_STATUS_NOT_IMPLEMENTED -- if the usage value array has field sizes
1322 that are not multiples of 8 bits, this
1323 error code is returned since the function
1324 currently does not handle setting into
1326 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1327 link collection exist but exists in
1328 a report with a different report ID
1329 than the report being passed in. To
1330 set this value, call
1331 HidP_SetUsageValueArray again with
1332 a zero-initialized report packet
1333 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1334 collection combination does not exist
1335 in any reports for this ReportType
1340 HidP_GetUsageValue (
1341 HIDP_REPORT_TYPE ReportType,
1343 USHORT LinkCollection,
1346 PHIDP_PREPARSED_DATA PreparsedData,
1347 reads_bytes_(ReportLength) PCHAR Report,
1353 HidP_GetUsageValue retrieves the value from the HID Report for the usage
1354 specified by the combination of usage page, usage and link collection.
1355 If a report packet contains two different fields with the same
1356 Usage and UsagePage, they can be distinguished with the optional
1357 LinkCollection field value.
1361 ReportType One of HidP_Input or HidP_Feature.
1363 UsagePage The usage page to which the given usage refers.
1365 LinkCollection (Optional) This value can be used to differentiate
1366 between two fields that may have the same
1367 UsagePage and Usage but exist in different
1368 collections. If the link collection value
1369 is zero, this function will set the first field
1370 it finds that matches the usage page and
1373 Usage The usage whose value HidP_GetUsageValue will retrieve
1375 UsageValue The raw value that is set for the specified field in the report
1376 buffer. This value will either fall within the logical range
1377 or if NULL values are allowed, a number outside the range to
1380 PreparsedData The preparsed data returned for HIDCLASS
1382 Report The report packet.
1384 ReportLength Length (in bytes) of the given report packet.
1388 HidP_GetUsageValue returns the following error codes:
1390 HIDP_STATUS_SUCCESS -- upon successfully retrieving the value
1391 from the report packet
1392 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1393 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1394 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1395 equal to the length specified in
1396 the HIDP_CAPS structure for the given
1398 HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device
1399 for the given ReportType
1400 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1401 link collection exist but exists in
1402 a report with a different report ID
1403 than the report being passed in. To
1404 set this value, call HidP_GetUsageValue
1405 again with a different report packet
1406 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1407 collection combination does not exist
1408 in any reports for this ReportType
1413 HidP_GetScaledUsageValue (
1414 HIDP_REPORT_TYPE ReportType,
1416 USHORT LinkCollection,
1419 PHIDP_PREPARSED_DATA PreparsedData,
1420 reads_bytes_(ReportLength) PCHAR Report,
1426 HidP_GetScaledUsageValue retrieves a UsageValue from the HID report packet
1427 in the field corresponding to the given usage page and usage. If a report
1428 packet contains two different fields with the same Usage and UsagePage,
1429 they can be distinguished with the optional LinkCollection field value.
1431 If the specified field has a defined physical range, this function converts
1432 the logical value that exists in the report packet to the corresponding
1433 physical value. If a physical range does not exist, the function will
1434 return the logical value. This function will check to verify that the
1435 logical value in the report falls within the declared logical range.
1437 When doing the conversion between logical and physical values, this
1438 function assumes a linear extrapolation between the physical max/min and
1439 the logical max/min. (Where logical is the values reported by the device
1440 and physical is the value returned by this function). If the data field
1441 size is less than 32 bits, then HidP_GetScaledUsageValue will sign extend
1442 the value to 32 bits.
1444 If the range checking fails but the field has NULL values, the function
1445 will set UsageValue to 0 and return HIDP_STATUS_NULL. Otherwise, it
1446 returns a HIDP_STATUSOF_RANGE error.
1450 ReportType One of HidP_Output or HidP_Feature.
1452 UsagePage The usage page to which the given usage refers.
1454 LinkCollection (Optional) This value can be used to differentiate
1455 between two fields that may have the same
1456 UsagePage and Usage but exist in different
1457 collections. If the link collection value
1458 is zero, this function will retrieve the first
1459 field it finds that matches the usage page
1462 Usage The usage whose value HidP_GetScaledUsageValue will retrieve
1464 UsageValue The value retrieved from the report buffer. See the routine
1465 description above for the different interpretations of this
1468 PreparsedData The preparsed data returned from HIDCLASS
1470 Report The report packet.
1472 ReportLength Length (in bytes) of the given report packet.
1476 HidP_GetScaledUsageValue returns the following error codes:
1478 HIDP_STATUS_SUCCESS -- upon successfully retrieving the value
1479 from the report packet
1480 HIDP_STATUS_NULL -- if the report packet had a NULL value
1482 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1483 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1484 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1485 equal to the length specified in
1486 the HIDP_CAPS structure for the given
1488 HIDP_STATUS_VALUEOF_RANGE -- if the value retrieved from the packet
1489 falls outside the logical range and
1490 the field does not support NULL values
1491 HIDP_STATUS_BAD_LOG_PHY_VALUES -- if the field has a physical range but
1492 either the logical range is invalid
1493 (max <= min) or the physical range is
1495 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1496 link collection exist but exists in
1497 a report with a different report ID
1498 than the report being passed in. To
1499 set this value, call
1500 HidP_GetScaledUsageValue with a
1501 different report packet
1502 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1503 collection combination does not exist
1504 in any reports for this ReportType
1508 HidP_GetUsageValueArray (
1509 HIDP_REPORT_TYPE ReportType,
1511 USHORT LinkCollection,
1513 updates_bytes_(UsageValueByteLength) PCHAR UsageValue,
1514 USHORT UsageValueByteLength,
1515 PHIDP_PREPARSED_DATA PreparsedData,
1516 reads_bytes_(ReportLength) PCHAR Report,
1522 A usage value array occurs when the last usage in the list of usages
1523 describing a main item must be repeated because there are less usages defined
1524 than there are report counts declared for the given main item. In this case
1525 a single value cap is allocated for that usage and the report count of that
1526 value cap is set to reflect the number of fields to which that usage refers.
1528 HidP_GetUsageValueArray returns the raw bits for that usage which spans
1529 more than one field in a report.
1531 NOTE: This function currently does not support value arrays where the
1532 ReportSize for each of the fields in the array is not a multiple
1535 The UsageValue buffer will have the raw values as they are set
1536 in the report packet.
1540 ReportType One of HidP_Input, HidP_Output or HidP_Feature.
1542 UsagePage The usage page to which the given usage refers.
1544 LinkCollection (Optional) This value can be used to differentiate
1545 between two fields that may have the same
1546 UsagePage and Usage but exist in different
1547 collections. If the link collection value
1548 is zero, this function will set the first field
1549 it finds that matches the usage page and
1552 Usage The usage whose value HidP_GetUsageValueArray will retreive.
1554 UsageValue A pointer to an array of characters where the value will be
1555 placed. The number of BITS required is found by multiplying the
1556 BitSize and ReportCount fields of the Value Cap for this
1557 control. The least significant bit of this control found in the
1558 given report will be placed in the least significant bit location
1559 of the buffer (little-endian format), regardless of whether
1560 or not the field is byte aligned or if the BitSize is a multiple
1563 See note above about current implementation limitations
1565 UsageValueByteLength
1566 the length of the given UsageValue buffer.
1568 PreparsedData The preparsed data returned by the HIDCLASS
1570 Report The report packet.
1572 ReportLength Length of the given report packet.
1576 HIDP_STATUS_SUCCESS -- upon successfully retrieving the value
1577 from the report packet
1578 HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid.
1579 HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
1580 HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not
1581 equal to the length specified in
1582 the HIDP_CAPS structure for the given
1584 HIDP_STATUS_NOT_VALUE_ARRAY -- if the control specified is not a
1585 value array -- a value array will have
1586 a ReportCount field in the
1587 HIDP_VALUE_CAPS structure that is > 1
1588 Use HidP_GetUsageValue instead
1589 HIDP_STATUS_BUFFER_TOO_SMALL -- if the size of the passed in buffer in
1590 which to return the array is too small
1591 (ie. has fewer values than the number of
1593 HIDP_STATUS_NOT_IMPLEMENTED -- if the usage value array has field sizes
1594 that are not multiples of 8 bits, this
1595 error code is returned since the function
1596 currently does not handle getting values
1598 HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and
1599 link collection exist but exists in
1600 a report with a different report ID
1601 than the report being passed in. To
1602 set this value, call
1603 HidP_GetUsageValueArray with a
1604 different report packet
1605 HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link
1606 collection combination does not exist
1607 in any reports for this ReportType
1611 _IRQL_requires_max_(PASSIVE_LEVEL)
1613 HidP_UsageListDifference (
1614 reads_(UsageListLength) PUSAGE PreviousUsageList,
1615 reads_(UsageListLength) PUSAGE CurrentUsageList,
1616 writes_(UsageListLength) PUSAGE BreakUsageList,
1617 writes_(UsageListLength) PUSAGE MakeUsageList,
1618 ULONG UsageListLength
1621 Routine Description:
1622 This function will return the difference between a two lists of usages
1623 (as might be returned from HidP_GetUsages), In other words, it will return
1624 return a list of usages that are in the current list but not the previous
1625 list as well as a list of usages that are in the previous list but not
1630 PreviousUsageList The list of usages before.
1631 CurrentUsageList The list of usages now.
1632 BreakUsageList Previous - Current.
1633 MakeUsageList Current - Previous.
1634 UsageListLength Represents the length of the usage lists in array
1635 elements. If comparing two lists with a differing
1636 number of array elements, this value should be
1637 the size of the larger of the two lists. Any
1638 zero found with a list indicates an early termination
1639 of the list and any usages found after the first zero
1644 _IRQL_requires_max_(PASSIVE_LEVEL)
1646 HidP_UsageAndPageListDifference (
1647 reads_(UsageListLength) PUSAGE_AND_PAGE PreviousUsageList,
1648 reads_(UsageListLength) PUSAGE_AND_PAGE CurrentUsageList,
1649 writes_(UsageListLength) PUSAGE_AND_PAGE BreakUsageList,
1650 writes_(UsageListLength) PUSAGE_AND_PAGE MakeUsageList,
1651 ULONG UsageListLength
1655 // Produce Make or Break Codes
1657 typedef enum _HIDP_KEYBOARD_DIRECTION {
1658 HidP_Keyboard_Break,
1660 } HIDP_KEYBOARD_DIRECTION;
1663 // A bitmap of the current shift state of the keyboard when using the
1664 // below keyboard usages to i8042 translation function.
1666 typedef struct _HIDP_KEYBOARD_MODIFIER_STATE {
1669 ULONG LeftControl: 1;
1673 ULONG RightControl: 1;
1674 ULONG RightShift: 1;
1685 } HIDP_KEYBOARD_MODIFIER_STATE, * PHIDP_KEYBOARD_MODIFIER_STATE;
1688 // A call back function to give the i8042 scan codes to the caller of
1689 // the below translation function.
1691 typedef BOOLEAN (* PHIDP_INSERT_SCANCODES) (
1692 PVOID Context, // Some caller supplied context.
1693 reads_bytes_(Length) PCHAR NewScanCodes, // A list of i8042 scan codes.
1694 ULONG Length // the length of the scan codes.
1699 HidP_TranslateUsageAndPagesToI8042ScanCodes (
1700 reads_(UsageListLength) PUSAGE_AND_PAGE ChangedUsageList,
1701 ULONG UsageListLength,
1702 HIDP_KEYBOARD_DIRECTION KeyAction,
1703 PHIDP_KEYBOARD_MODIFIER_STATE ModifierState,
1704 PHIDP_INSERT_SCANCODES InsertCodesProcedure,
1705 PVOID InsertCodesContext
1708 Routine Description:
1713 HidP_TranslateUsagesToI8042ScanCodes (
1714 reads_(UsageListLength) PUSAGE ChangedUsageList,
1715 ULONG UsageListLength,
1716 HIDP_KEYBOARD_DIRECTION KeyAction,
1717 PHIDP_KEYBOARD_MODIFIER_STATE ModifierState,
1718 PHIDP_INSERT_SCANCODES InsertCodesProcedure,
1719 PVOID InsertCodesContext
1722 Routine Description:
1729 // Define NT Status codes with Facility Code of FACILITY_HID_ERROR_CODE
1732 // FACILITY_HID_ERROR_CODE defined in ntstatus.h
1733 #ifndef FACILITY_HID_ERROR_CODE
1734 #define FACILITY_HID_ERROR_CODE 0x11
1737 #define HIDP_ERROR_CODES(SEV, CODE) \
1738 ((NTSTATUS) (((SEV) << 28) | (FACILITY_HID_ERROR_CODE << 16) | (CODE)))
1740 #define HIDP_STATUS_SUCCESS (HIDP_ERROR_CODES(0x0,0))
1741 #define HIDP_STATUS_NULL (HIDP_ERROR_CODES(0x8,1))
1742 #define HIDP_STATUS_INVALID_PREPARSED_DATA (HIDP_ERROR_CODES(0xC,1))
1743 #define HIDP_STATUS_INVALID_REPORT_TYPE (HIDP_ERROR_CODES(0xC,2))
1744 #define HIDP_STATUS_INVALID_REPORT_LENGTH (HIDP_ERROR_CODES(0xC,3))
1745 #define HIDP_STATUS_USAGE_NOT_FOUND (HIDP_ERROR_CODES(0xC,4))
1746 #define HIDP_STATUS_VALUEOF_RANGE (HIDP_ERROR_CODES(0xC,5))
1747 #define HIDP_STATUS_BAD_LOG_PHY_VALUES (HIDP_ERROR_CODES(0xC,6))
1748 #define HIDP_STATUS_BUFFER_TOO_SMALL (HIDP_ERROR_CODES(0xC,7))
1749 #define HIDP_STATUS_INTERNAL_ERROR (HIDP_ERROR_CODES(0xC,8))
1750 #define HIDP_STATUS_I8042_TRANS_UNKNOWN (HIDP_ERROR_CODES(0xC,9))
1751 #define HIDP_STATUS_INCOMPATIBLE_REPORT_ID (HIDP_ERROR_CODES(0xC,0xA))
1752 #define HIDP_STATUS_NOT_VALUE_ARRAY (HIDP_ERROR_CODES(0xC,0xB))
1753 #define HIDP_STATUS_IS_VALUE_ARRAY (HIDP_ERROR_CODES(0xC,0xC))
1754 #define HIDP_STATUS_DATA_INDEX_NOT_FOUND (HIDP_ERROR_CODES(0xC,0xD))
1755 #define HIDP_STATUS_DATA_INDEXOF_RANGE (HIDP_ERROR_CODES(0xC,0xE))
1756 #define HIDP_STATUS_BUTTON_NOT_PRESSED (HIDP_ERROR_CODES(0xC,0xF))
1757 #define HIDP_STATUS_REPORT_DOES_NOT_EXIST (HIDP_ERROR_CODES(0xC,0x10))
1758 #define HIDP_STATUS_NOT_IMPLEMENTED (HIDP_ERROR_CODES(0xC,0x20))
1761 // We blundered this status code.
1763 #define HIDP_STATUS_I8242_TRANS_UNKNOWN HIDP_STATUS_I8042_TRANS_UNKNOWN
1767 Copyright (c) Microsoft Corporation. All rights reserved.
1775 This module contains the PUBLIC definitions for the
1776 code that implements the HID dll.
1787 typedef struct _HIDD_CONFIGURATION {
1790 ULONG RingBufferSize;
1791 } HIDD_CONFIGURATION, *PHIDD_CONFIGURATION;
1793 typedef struct _HIDD_ATTRIBUTES {
1794 ULONG Size; // = sizeof (struct _HIDD_ATTRIBUTES)
1797 // Vendor ids of this hid device
1801 USHORT VersionNumber;
1804 // Additional fields will be added to the end of this structure.
1806 } HIDD_ATTRIBUTES, *PHIDD_ATTRIBUTES;
1810 HidD_GetAttributes (
1811 HANDLE HidDeviceObject,
1812 PHIDD_ATTRIBUTES Attributes
1815 Routine Description:
1816 Fill in the given HIDD_ATTRIBUTES structure with the attributes of the
1829 HidD_GetPreparsedData (
1830 HANDLE HidDeviceObject,
1831 PHIDP_PREPARSED_DATA * PreparsedData
1834 Routine Description:
1835 Given a handle to a valid Hid Class Device Object, retrieve the preparsed
1836 data for the device. This routine will allocate the appropriately
1837 sized buffer to hold this preparsed data. It is up to client to call
1838 HidP_FreePreparsedData to free the memory allocated to this structure when
1839 it is no longer needed.
1842 HidDeviceObject A handle to a Hid Device that the client obtains using
1843 a call to CreateFile on a valid Hid device string name.
1844 The string name can be obtained using standard PnP calls.
1846 PreparsedData An opaque data structure used by other functions in this
1847 library to retrieve information about a given device.
1851 FALSE otherwise -- Use GetLastError() to get extended error information
1854 HidD_FreePreparsedData (
1855 __drv_freesMem(Mem) PHIDP_PREPARSED_DATA PreparsedData
1860 HANDLE HidDeviceObject
1863 Routine Description:
1864 Flush the input queue for the given HID device.
1867 HidDeviceObject A handle to a Hid Device that the client obtains using
1868 a call to CreateFile on a valid Hid device string name.
1869 The string name can be obtained using standard PnP calls.
1873 FALSE otherwise -- Use GetLastError() to get extended error information
1877 HidD_GetConfiguration (
1878 HANDLE HidDeviceObject,
1879 PHIDD_CONFIGURATION Configuration,
1880 ULONG ConfigurationLength
1883 Routine Description:
1884 Get the configuration information for this Hid device
1887 HidDeviceObject A handle to a Hid Device Object.
1889 Configuration A configuration structure. HidD_GetConfiguration MUST
1890 be called before the configuration can be modified and
1891 set using HidD_SetConfiguration
1893 ConfigurationLength That is ``sizeof (HIDD_CONFIGURATION)''. Using this
1894 parameter, we can later increase the length of the
1895 configuration array and not break older apps.
1899 FALSE otherwise -- Use GetLastError() to get extended error information
1903 HidD_SetConfiguration (
1904 HANDLE HidDeviceObject,
1905 reads_bytes_(ConfigurationLength) PHIDD_CONFIGURATION Configuration,
1906 ULONG ConfigurationLength
1909 Routine Description:
1910 Set the configuration information for this Hid device...
1912 NOTE: HidD_GetConfiguration must be called to retrieve the current
1913 configuration information before this information can be modified
1917 HidDeviceObject A handle to a Hid Device Object.
1919 Configuration A configuration structure. HidD_GetConfiguration MUST
1920 be called before the configuration can be modified and
1921 set using HidD_SetConfiguration
1923 ConfigurationLength That is ``sizeof (HIDD_CONFIGURATION)''. Using this
1924 parameter, we can later increase the length of the
1925 configuration array and not break older apps.
1929 FALSE otherwise -- Use GetLastError() to get extended error information
1934 HANDLE HidDeviceObject,
1936 ULONG ReportBufferLength
1939 Routine Description:
1940 Retrieve a feature report from a HID device.
1943 HidDeviceObject A handle to a Hid Device Object.
1945 ReportBuffer The buffer that the feature report should be placed
1946 into. The first byte of the buffer should be set to
1947 the report ID of the desired report
1949 ReportBufferLength The size (in bytes) of ReportBuffer. This value
1950 should be greater than or equal to the
1951 FeatureReportByteLength field as specified in the
1952 HIDP_CAPS structure for the device
1955 FALSE otherwise -- Use GetLastError() to get extended error information
1960 HANDLE HidDeviceObject,
1961 reads_bytes_(ReportBufferLength) PVOID ReportBuffer,
1962 ULONG ReportBufferLength
1965 Routine Description:
1966 Send a feature report to a HID device.
1969 HidDeviceObject A handle to a Hid Device Object.
1971 ReportBuffer The buffer of the feature report to send to the device
1973 ReportBufferLength The size (in bytes) of ReportBuffer. This value
1974 should be greater than or equal to the
1975 FeatureReportByteLength field as specified in the
1976 HIDP_CAPS structure for the device
1979 FALSE otherwise -- Use GetLastError() to get extended error information
1985 HidD_GetInputReport (
1986 HANDLE HidDeviceObject,
1988 ULONG ReportBufferLength
1991 Routine Description:
1992 Retrieve an input report from a HID device.
1995 HidDeviceObject A handle to a Hid Device Object.
1997 ReportBuffer The buffer that the input report should be placed
1998 into. The first byte of the buffer should be set to
1999 the report ID of the desired report
2001 ReportBufferLength The size (in bytes) of ReportBuffer. This value
2002 should be greater than or equal to the
2003 InputReportByteLength field as specified in the
2004 HIDP_CAPS structure for the device
2007 FALSE otherwise -- Use GetLastError() to get extended error information
2011 HidD_SetOutputReport (
2012 HANDLE HidDeviceObject,
2013 reads_bytes_(ReportBufferLength) PVOID ReportBuffer,
2014 ULONG ReportBufferLength
2017 Routine Description:
2018 Send an output report to a HID device.
2021 HidDeviceObject A handle to a Hid Device Object.
2023 ReportBuffer The buffer of the output report to send to the device
2025 ReportBufferLength The size (in bytes) of ReportBuffer. This value
2026 should be greater than or equal to the
2027 OutputReportByteLength field as specified in the
2028 HIDP_CAPS structure for the device
2031 FALSE otherwise -- Use GetLastError() to get extended error information
2037 HidD_GetNumInputBuffers (
2038 HANDLE HidDeviceObject,
2039 PULONG NumberBuffers
2042 Routine Description:
2043 This function returns the number of input buffers used by the specified
2044 file handle to the Hid device. Each file object has a number of buffers
2045 associated with it to queue reports read from the device but which have
2046 not yet been read by the user-mode app with a handle to that device.
2049 HidDeviceObject A handle to a Hid Device Object.
2051 NumberBuffers Number of buffers currently being used for this file
2052 handle to the Hid device
2056 FALSE otherwise -- Use GetLastError() to get extended error information
2060 HidD_SetNumInputBuffers (
2061 HANDLE HidDeviceObject,
2066 Routine Description:
2067 This function sets the number of input buffers used by the specified
2068 file handle to the Hid device. Each file object has a number of buffers
2069 associated with it to queue reports read from the device but which have
2070 not yet been read by the user-mode app with a handle to that device.
2073 HidDeviceObject A handle to a Hid Device Object.
2075 NumberBuffers New number of buffers to use for this file handle to
2080 FALSE otherwise -- Use GetLastError() to get extended error information
2084 HidD_GetPhysicalDescriptor (
2085 HANDLE HidDeviceObject,
2090 Routine Description:
2091 This function retrieves the raw physical descriptor for the specified
2095 HidDeviceObject A handle to a Hid Device Object.
2097 Buffer Buffer which on return will contain the physical
2098 descriptor if one exists for the specified device
2101 BufferLength Length of buffer (in bytes)
2106 FALSE otherwise -- Use GetLastError() to get extended error information
2110 HidD_GetManufacturerString (
2111 HANDLE HidDeviceObject,
2116 Routine Description:
2117 This function retrieves the manufacturer string from the specified
2121 HidDeviceObject A handle to a Hid Device Object.
2123 Buffer Buffer which on return will contain the manufacturer
2124 string returned from the device. This string is a
2125 wide-character string
2127 BufferLength Length of Buffer (in bytes)
2132 FALSE otherwise -- Use GetLastError() to get extended error information
2136 HidD_GetProductString (
2137 HANDLE HidDeviceObject,
2142 Routine Description:
2143 This function retrieves the product string from the specified
2147 HidDeviceObject A handle to a Hid Device Object.
2149 Buffer Buffer which on return will contain the product
2150 string returned from the device. This string is a
2151 wide-character string
2153 BufferLength Length of Buffer (in bytes)
2158 FALSE otherwise -- Use GetLastError() to get extended error information
2162 HidD_GetIndexedString (
2163 HANDLE HidDeviceObject,
2169 Routine Description:
2170 This function retrieves a string from the specified Hid device that is
2171 specified with a certain string index.
2174 HidDeviceObject A handle to a Hid Device Object.
2176 StringIndex Index of the string to retrieve
2178 Buffer Buffer which on return will contain the product
2179 string returned from the device. This string is a
2180 wide-character string
2182 BufferLength Length of Buffer (in bytes)
2186 FALSE otherwise -- Use GetLastError() to get extended error information
2190 HidD_GetSerialNumberString (
2191 HANDLE HidDeviceObject,
2196 Routine Description:
2197 This function retrieves the serial number string from the specified
2201 HidDeviceObject A handle to a Hid Device Object.
2203 Buffer Buffer which on return will contain the serial number
2204 string returned from the device. This string is a
2205 wide-character string
2207 BufferLength Length of Buffer (in bytes)
2211 FALSE otherwise -- Use GetLastError() to get extended error information
2217 HidD_GetMsGenreDescriptor (
2218 HANDLE HidDeviceObject,