]> git.zerfleddert.de Git - proxmark3-svn/blob - client/include/hidpi.h
e0d9c9dbb6858d1a649c67e99f694b6c862e9522
[proxmark3-svn] / 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
Impressum, Datenschutz