X-Git-Url: http://git.zerfleddert.de/cgi-bin/gitweb.cgi/proxmark3-svn/blobdiff_plain/b811cc51f9a21324dc7589d1254e767374488a20..6658905f18a1eebc148836f26c731dea9c1377dc:/winsrc/include/hidpi.h diff --git a/winsrc/include/hidpi.h b/winsrc/include/hidpi.h new file mode 100644 index 00000000..e9816cf4 --- /dev/null +++ b/winsrc/include/hidpi.h @@ -0,0 +1,1787 @@ +/*++ + +Copyright (c) 1996-1998 Microsoft Corporation + +Module Name: + + HIDPI.H + +Abstract: + + Public Interface to the HID parsing library. + +Environment: + + Kernel & user mode + +--*/ + +#ifndef __HIDPI_H__ +#define __HIDPI_H__ + +#include + +// Please include "hidsdi.h" to use the user space (dll / parser) +// Please include "hidpddi.h" to use the kernel space parser + +// +// Special Link collection values for using the query functions +// +// Root collection references the collection at the base of the link +// collection tree. +// Unspecifies, references all collections in the link collection tree. +// +#define HIDP_LINK_COLLECTION_ROOT ((USHORT) -1) +#define HIDP_LINK_COLLECTION_UNSPECIFIED ((USHORT) 0) + + +typedef enum _HIDP_REPORT_TYPE +{ + HidP_Input, + HidP_Output, + HidP_Feature +} HIDP_REPORT_TYPE; + +typedef struct _USAGE_AND_PAGE +{ + USAGE Usage; + USAGE UsagePage; +} USAGE_AND_PAGE, *PUSAGE_AND_PAGE; + +#define HidP_IsSameUsageAndPage(u1, u2) ((* (PULONG) &u1) == (* (PULONG) &u2)) + +typedef struct _HIDP_BUTTON_CAPS +{ + USAGE UsagePage; + UCHAR ReportID; + BOOLEAN IsAlias; + + USHORT BitField; + USHORT LinkCollection; // A unique internal index pointer + + USAGE LinkUsage; + USAGE LinkUsagePage; + + BOOLEAN IsRange; + BOOLEAN IsStringRange; + BOOLEAN IsDesignatorRange; + BOOLEAN IsAbsolute; + + ULONG Reserved[10]; + union { + struct { + USAGE UsageMin, UsageMax; + USHORT StringMin, StringMax; + USHORT DesignatorMin, DesignatorMax; + USHORT DataIndexMin, DataIndexMax; + } Range; + struct { + USAGE Usage, Reserved1; + USHORT StringIndex, Reserved2; + USHORT DesignatorIndex, Reserved3; + USHORT DataIndex, Reserved4; + } NotRange; + }; + +} HIDP_BUTTON_CAPS, *PHIDP_BUTTON_CAPS; + + +typedef struct _HIDP_VALUE_CAPS +{ + USAGE UsagePage; + UCHAR ReportID; + BOOLEAN IsAlias; + + USHORT BitField; + USHORT LinkCollection; // A unique internal index pointer + + USAGE LinkUsage; + USAGE LinkUsagePage; + + BOOLEAN IsRange; + BOOLEAN IsStringRange; + BOOLEAN IsDesignatorRange; + BOOLEAN IsAbsolute; + + BOOLEAN HasNull; // Does this channel have a null report union + UCHAR Reserved; + USHORT BitSize; // How many bits are devoted to this value? + + USHORT ReportCount; // See Note below. Usually set to 1. + USHORT Reserved2[5]; + + ULONG UnitsExp; + ULONG Units; + + LONG LogicalMin, LogicalMax; + LONG PhysicalMin, PhysicalMax; + + union { + struct { + USAGE UsageMin, UsageMax; + USHORT StringMin, StringMax; + USHORT DesignatorMin, DesignatorMax; + USHORT DataIndexMin, DataIndexMax; + } Range; + + struct { + USAGE Usage, Reserved1; + USHORT StringIndex, Reserved2; + USHORT DesignatorIndex, Reserved3; + USHORT DataIndex, Reserved4; + } NotRange; + }; +} HIDP_VALUE_CAPS, *PHIDP_VALUE_CAPS; + +// +// Notes: +// +// ReportCount: When a report descriptor declares an Input, Output, or +// Feature main item with fewer usage declarations than the report count, then +// the last usage applies to all remaining unspecified count in that main item. +// (As an example you might have data that required many fields to describe, +// possibly buffered bytes.) In this case, only one value cap structure is +// allocated for these associtated fields, all with the same usage, and Report +// Count reflects the number of fields involved. Normally ReportCount is 1. +// To access all of the fields in such a value structure would require using +// HidP_GetUsageValueArray and HidP_SetUsageValueArray. HidP_GetUsageValue/ +// HidP_SetScaledUsageValue will also work, however, these functions will only +// work with the first field of the structure. +// + +// +// The link collection tree consists of an array of LINK_COLLECTION_NODES +// where the index into this array is the same as the collection number. +// +// Given a collection A which contains a subcollection B, A is defined to be +// the parent B, and B is defined to be the child. +// +// Given collections A, B, and C where B and C are children of A, and B was +// encountered before C in the report descriptor, B is defined as a sibling of +// C. (This implies, of course, that if B is a sibling of C, then C is NOT a +// sibling of B). +// +// B is defined as the NextSibling of C if and only if there exists NO +// child collection of A, call it D, such that B is a sibling of D and D +// is a sibling of C. +// +// E is defined to be the FirstChild of A if and only if for all children of A, +// F, that are not equivalent to E, F is a sibling of E. +// (This implies, of course, that the does not exist a child of A, call it G, +// where E is a sibling of G). In other words the first sibling is the last +// link collection found in the list. +// +// In other words, if a collection B is defined within the definition of another +// collection A, B becomes a child of A. All collections with the same parent +// are considered siblings. The FirstChild of the parent collection, A, will be +// last collection defined that has A as a parent. The order of sibling pointers +// is similarly determined. When a collection B is defined, it becomes the +// FirstChild of it's parent collection. The previously defined FirstChild of the +// parent collection becomes the NextSibling of the new collection. As new +// collections with the same parent are discovered, the chain of sibling is built. +// +// With that in mind, the following describes conclusively a data structure +// that provides direct traversal up, down, and accross the link collection +// tree. +// +// +typedef struct _HIDP_LINK_COLLECTION_NODE +{ + USAGE LinkUsage; + USAGE LinkUsagePage; + USHORT Parent; + USHORT NumberOfChildren; + USHORT NextSibling; + USHORT FirstChild; + ULONG CollectionType: 8; // As defined in 6.2.2.6 of HID spec + ULONG IsAlias : 1; // This link node is an allias of the next link node. + ULONG Reserved: 23; + PVOID UserContext; // The user can hang his coat here. +} HIDP_LINK_COLLECTION_NODE, *PHIDP_LINK_COLLECTION_NODE; + +// +// When a link collection is described by a delimiter, alias link collection +// nodes are created. (One for each usage within the delimiter). +// The parser assigns each capability description listed above only one +// link collection. +// +// If a control is defined within a collection defined by +// delimited usages, then that control is said to be within multiple link +// collections, one for each usage within the open and close delimiter tokens. +// Such multiple link collecions are said to be aliases. The first N-1 such +// collections, listed in the link collection node array, have their IsAlias +// bit set. The last such link collection is the link collection index used +// in the capabilities described above. +// Clients wishing to set a control in an aliased collection, should walk the +// collection array once for each time they see the IsAlias flag set, and use +// the last link collection as the index for the below accessor functions. +// +// NB: if IsAlias is set, then NextSibling should be one more than the current +// link collection node index. +// + +typedef PUCHAR PHIDP_REPORT_DESCRIPTOR; +typedef struct _HIDP_PREPARSED_DATA * PHIDP_PREPARSED_DATA; + +typedef struct _HIDP_CAPS +{ + USAGE Usage; + USAGE UsagePage; + USHORT InputReportByteLength; + USHORT OutputReportByteLength; + USHORT FeatureReportByteLength; + USHORT Reserved[17]; + + USHORT NumberLinkCollectionNodes; + + USHORT NumberInputButtonCaps; + USHORT NumberInputValueCaps; + USHORT NumberInputDataIndices; + + USHORT NumberOutputButtonCaps; + USHORT NumberOutputValueCaps; + USHORT NumberOutputDataIndices; + + USHORT NumberFeatureButtonCaps; + USHORT NumberFeatureValueCaps; + USHORT NumberFeatureDataIndices; +} HIDP_CAPS, *PHIDP_CAPS; + +typedef struct _HIDP_DATA +{ + USHORT DataIndex; + USHORT Reserved; + union { + ULONG RawValue; // for values + BOOLEAN On; // for buttons MUST BE TRUE for buttons. + }; +} HIDP_DATA, *PHIDP_DATA; +// +// The HIDP_DATA structure is used with HidP_GetData and HidP_SetData +// functions. +// +// The parser contiguously assigns every control (button or value) in a hid +// device a unique data index from zero to NumberXXXDataIndices -1 , inclusive. +// This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures. +// +// Most clients will find the Get/Set Buttons / Value accessor functions +// sufficient to their needs, as they will allow the clients to access the +// data known to them while ignoring the other controls. +// +// More complex clients, which actually read the Button / Value Caps, and which +// do a value add service to these routines (EG Direct Input), will need to +// access all the data in the device without interest in the individual usage +// or link collection location. These are the clients that will find +// HidP_Data useful. +// + +typedef struct _HIDP_UNKNOWN_TOKEN +{ + UCHAR Token; + UCHAR Reserved[3]; + ULONG BitField; +} HIDP_UNKNOWN_TOKEN, *PHIDP_UNKNOWN_TOKEN; + +typedef struct _HIDP_EXTENDED_ATTRIBUTES +{ + UCHAR NumGlobalUnknowns; + UCHAR Reserved [3]; + PHIDP_UNKNOWN_TOKEN GlobalUnknowns; + // ... Additional attributes + ULONG Data [1]; // variableLength DO NOT ACCESS THIS FIELD +} HIDP_EXTENDED_ATTRIBUTES, *PHIDP_EXTENDED_ATTRIBUTES; + +NTSTATUS __stdcall +HidP_GetCaps ( + IN PHIDP_PREPARSED_DATA PreparsedData, + OUT PHIDP_CAPS Capabilities + ); +/*++ +Routine Description: + Returns a list of capabilities of a given hid device as described by its + preparsed data. + +Arguments: + PreparsedData The preparsed data returned from HIDCLASS. + Capabilities a HIDP_CAPS structure + +Return Value: +· HIDP_STATUS_SUCCESS +· HIDP_STATUS_INVALID_PREPARSED_DATA +--*/ + +NTSTATUS __stdcall +HidP_GetLinkCollectionNodes ( + OUT PHIDP_LINK_COLLECTION_NODE LinkCollectionNodes, + IN OUT PULONG LinkCollectionNodesLength, + IN PHIDP_PREPARSED_DATA PreparsedData + ); +/*++ +Routine Description: + Return a list of PHIDP_LINK_COLLECTION_NODEs used to describe the link + collection tree of this hid device. See the above description of + struct _HIDP_LINK_COLLECTION_NODE. + +Arguments: + LinkCollectionNodes - a caller allocated array into which + HidP_GetLinkCollectionNodes will store the information + + LinKCollectionNodesLength - the caller sets this value to the length of the + the array in terms of number of elements. + HidP_GetLinkCollectionNodes sets this value to the actual + number of elements set. The total number of nodes required to + describe this HID device can be found in the + NumberLinkCollectionNodes field in the HIDP_CAPS structure. + +--*/ + +NTSTATUS __stdcall +HidP_GetButtonCaps ( + IN HIDP_REPORT_TYPE ReportType, + OUT PHIDP_BUTTON_CAPS ButtonCaps, + IN OUT PUSHORT ButtonCapsLength, + IN PHIDP_PREPARSED_DATA PreparsedData +); +#define HidP_GetButtonCaps(_Type_, _Caps_, _Len_, _Data_) \ + HidP_GetSpecificButtonCaps (_Type_, 0, 0, 0, _Caps_, _Len_, _Data_) +NTSTATUS __stdcall +HidP_GetSpecificButtonCaps ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, // Optional (0 => ignore) + IN USHORT LinkCollection, // Optional (0 => ignore) + IN USAGE Usage, // Optional (0 => ignore) + OUT PHIDP_BUTTON_CAPS ButtonCaps, + IN OUT PUSHORT ButtonCapsLength, + IN PHIDP_PREPARSED_DATA PreparsedData + ); +/*++ +Description: + HidP_GetButtonCaps returns all the buttons (binary values) that are a part + of the given report type for the Hid device represented by the given + preparsed data. + +Parameters: + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + UsagePage A usage page value used to limit the button caps returned to + those on a given usage page. If set to 0, this parameter is + ignored. Can be used with LinkCollection and Usage parameters + to further limit the number of button caps structures returned. + + LinkCollection HIDP_LINK_COLLECTION node array index used to limit the + button caps returned to those buttons in a given link + collection. If set to 0, this parameter is + ignored. Can be used with UsagePage and Usage parameters + to further limit the number of button caps structures + returned. + + Usage A usage value used to limit the button caps returned to those + with the specified usage value. If set to 0, this parameter + is ignored. Can be used with LinkCollection and UsagePage + parameters to further limit the number of button caps + structures returned. + + ButtonCaps A _HIDP_BUTTON_CAPS array containing information about all the + binary values in the given report. This buffer is provided by + the caller. + + ButtonLength As input, this parameter specifies the length of the + ButtonCaps parameter (array) in number of array elements. + As output, this value is set to indicate how many of those + array elements were filled in by the function. The maximum number of + button caps that can be returned is found in the HIDP_CAPS + structure. If HIDP_STATUS_BUFFER_TOO_SMALL is returned, + this value contains the number of array elements needed to + successfully complete the request. + + PreparsedData The preparsed data returned from HIDCLASS. + + +Return Value +HidP_GetSpecificButtonCaps returns the following error codes: +· HIDP_STATUS_SUCCESS. +· HIDP_STATUS_INVALID_REPORT_TYPE +· HIDP_STATUS_INVALID_PREPARSED_DATA +· HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in) +· HIDP_STATUS_USAGE_NOT_FOUND +--*/ + +NTSTATUS __stdcall +HidP_GetValueCaps ( + IN HIDP_REPORT_TYPE ReportType, + OUT PHIDP_VALUE_CAPS ValueCaps, + IN OUT PUSHORT ValueCapsLength, + IN PHIDP_PREPARSED_DATA PreparsedData +); +#define HidP_GetValueCaps(_Type_, _Caps_, _Len_, _Data_) \ + HidP_GetSpecificValueCaps (_Type_, 0, 0, 0, _Caps_, _Len_, _Data_) +NTSTATUS __stdcall +HidP_GetSpecificValueCaps ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, // Optional (0 => ignore) + IN USHORT LinkCollection, // Optional (0 => ignore) + IN USAGE Usage, // Optional (0 => ignore) + OUT PHIDP_VALUE_CAPS ValueCaps, + IN OUT PUSHORT ValueCapsLength, + IN PHIDP_PREPARSED_DATA PreparsedData + ); +/*++ +Description: + HidP_GetValueCaps returns all the values (non-binary) that are a part + of the given report type for the Hid device represented by the given + preparsed data. + +Parameters: + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + UsagePage A usage page value used to limit the value caps returned to + those on a given usage page. If set to 0, this parameter is + ignored. Can be used with LinkCollection and Usage parameters + to further limit the number of value caps structures returned. + + LinkCollection HIDP_LINK_COLLECTION node array index used to limit the + value caps returned to those buttons in a given link + collection. If set to 0, this parameter is + ignored. Can be used with UsagePage and Usage parameters + to further limit the number of value caps structures + returned. + + Usage A usage value used to limit the value caps returned to those + with the specified usage value. If set to 0, this parameter + is ignored. Can be used with LinkCollection and UsagePage + parameters to further limit the number of value caps + structures returned. + + ValueCaps A _HIDP_VALUE_CAPS array containing information about all the + non-binary values in the given report. This buffer is provided + by the caller. + + ValueLength As input, this parameter specifies the length of the ValueCaps + parameter (array) in number of array elements. As output, + this value is set to indicate how many of those array elements + were filled in by the function. The maximum number of + value caps that can be returned is found in the HIDP_CAPS + structure. If HIDP_STATUS_BUFFER_TOO_SMALL is returned, + this value contains the number of array elements needed to + successfully complete the request. + + PreparsedData The preparsed data returned from HIDCLASS. + + +Return Value +HidP_GetValueCaps returns the following error codes: +· HIDP_STATUS_SUCCESS. +· HIDP_STATUS_INVALID_REPORT_TYPE +· HIDP_STATUS_INVALID_PREPARSED_DATA +· HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in) +· HIDP_STATUS_USAGE_NOT_FOUND + +--*/ + +NTSTATUS __stdcall +HidP_GetExtendedAttributes ( + IN HIDP_REPORT_TYPE ReportType, + IN USHORT DataIndex, + IN PHIDP_PREPARSED_DATA PreparsedData, + OUT PHIDP_EXTENDED_ATTRIBUTES Attributes, + IN OUT PULONG LengthAttributes + ); +/*++ +Description: + Given a data index from the value or button capabilities of a given control + return any extended attributes for the control if any exist. + +Parameters: + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + DataIndex The data index for the given control, found in the capabilities + structure for that control + + PreparsedData The preparsed data returned from HIDCLASS. + + Attributes Pointer to a buffer into which the extended attribute data will + be copied. + + LengthAttributes Length of the given buffer in bytes. + +Return Value + HIDP_STATUS_SUCCESS + HIDP_STATUS_DATA_INDEX_NOT_FOUND +--*/ + +NTSTATUS __stdcall +HidP_InitializeReportForID ( + IN HIDP_REPORT_TYPE ReportType, + IN UCHAR ReportID, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + + Initialize a report based on the given report ID. + +Parameters: + + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + PreparasedData Preparsed data structure returned by HIDCLASS + + Report Buffer which to set the data into. + + ReportLength Length of Report...Report should be at least as long as the + value indicated in the HIDP_CAPS structure for the device and + the corresponding ReportType + +Return Value + +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal + to the length specified in HIDP_CAPS + structure for the given ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType + +--*/ + +NTSTATUS __stdcall +HidP_SetData ( + IN HIDP_REPORT_TYPE ReportType, + IN PHIDP_DATA DataList, + IN OUT PULONG DataLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + + Please Note: Since usage value arrays deal with multiple fields for + for one usage value, they cannot be used with HidP_SetData + and HidP_GetData. In this case, + HIDP_STATUS_IS_USAGE_VALUE_ARRAY will be returned. + +Parameters: + + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + DataList Array of HIDP_DATA structures that contains the data values + that are to be set into the given report + + DataLength As input, length in array elements of DataList. As output, + contains the number of data elements set on successful + completion or an index into the DataList array to identify + the faulting HIDP_DATA value if an error code is returned. + + PreparasedData Preparsed data structure returned by HIDCLASS + + Report Buffer which to set the data into. + + ReportLength Length of Report...Report should be at least as long as the + value indicated in the HIDP_CAPS structure for the device and + the corresponding ReportType + +Return Value + HidP_SetData returns the following error codes. The report packet will + have all the data set up until the HIDP_DATA structure that caused the + error. DataLength, in the error case, will return this problem index. + +· HIDP_STATUS_SUCCESS -- upon successful insertion of all data + into the report packet. +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_DATA_INDEX_NOT_FOUND -- if a HIDP_DATA structure referenced a + data index that does not exist for this + device's ReportType +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal + to the length specified in HIDP_CAPS + structure for the given ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_IS_USAGE_VALUE_ARRAY -- if one of the HIDP_DATA structures + references a usage value array. + DataLength will contain the index into + the array that was invalid +· HIDP_STATUS_BUTTON_NOT_PRESSED -- if a HIDP_DATA structure attempted + to unset a button that was not already + set in the Report +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- a HIDP_DATA structure was found with + a valid index value but is contained + in a different report than the one + currently being processed +· HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough entries in + a given Main Array Item to report all + buttons that have been requested to be + set +--*/ + +NTSTATUS __stdcall +HidP_GetData ( + IN HIDP_REPORT_TYPE ReportType, + OUT PHIDP_DATA DataList, + IN OUT PULONG DataLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + + Please Note: For obvious reasons HidP_SetData and HidP_GetData will not + access UsageValueArrays. + +Parameters: + ReportType One of HidP_Input, HidP_Output, or HidP_Feature. + + DataList Array of HIDP_DATA structures that will receive the data + values that are set in the given report + + DataLength As input, length in array elements of DataList. As output, + contains the number of data elements that were successfully + set by HidP_GetData. The maximum size necessary for DataList + can be determined by calling HidP_MaxDataListLength + + PreparasedData Preparsed data structure returned by HIDCLASS + + Report Buffer which to set the data into. + + ReportLength Length of Report...Report should be at least as long as the + value indicated in the HIDP_CAPS structure for the device and + the corresponding ReportType + +Return Value + HidP_GetData returns the following error codes. + +· HIDP_STATUS_SUCCESS -- upon successful retrieval of all data + from the report packet. +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not equal + to the length specified in HIDP_CAPS + structure for the given ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough array entries in + DataList to store all the indice values + in the given report. DataLength will + contain the number of array entries + required to hold all data +--*/ + +ULONG __stdcall +HidP_MaxDataListLength ( + IN HIDP_REPORT_TYPE ReportType, + IN PHIDP_PREPARSED_DATA PreparsedData + ); +/*++ +Routine Description: + + This function returns the maximum length of HIDP_DATA elements that + HidP_GetData could return for the given report type. + +Parameters: + + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + PreparsedData Preparsed data structure returned by HIDCLASS + +Return Value: + + The length of the data list array required for the HidP_GetData function + call. If an error occurs (either HIDP_STATUS_INVALID_REPORT_TYPE or + HIDP_STATUS_INVALID_PREPARSED_DATA), this function returns 0. + +--*/ + +#define HidP_SetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \ + HidP_SetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) + +NTSTATUS __stdcall +HidP_SetUsages ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN PUSAGE UsageList, + IN OUT PULONG UsageLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + This function sets binary values (buttons) in a report. Given an + initialized packet of correct length, it modifies the report packet so that + each element in the given list of usages has been set in the report packet. + For example, in an output report with 5 LED’s, each with a given usage, + an application could turn on any subset of these lights by placing their + usages in any order into the usage array (UsageList). HidP_SetUsages would, + in turn, set the appropriate bit or add the corresponding byte into the + HID Main Array Item. + + A properly initialized Report packet is one of the correct byte length, + and all zeros. + + NOTE: A packet that has already been set with a call to a HidP_Set routine + can also be passed in. This routine then sets processes the UsageList + in the same fashion but verifies that the ReportID already set in + Report matches the report ID for the given usages. + +Parameters: + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + UsagePage All of the usages in the usage array, which HidP_SetUsages will + set in the report, refer to this same usage page. + If a client wishes to set usages in a report for multiple + usage pages then that client needs to make multiple calls to + HidP_SetUsages for each of the usage pages. + + UsageList A usage array containing the usages that HidP_SetUsages will set in + the report packet. + + UsageLength The length of the given usage array in array elements. + The parser will set this value to the position in the usage + array where it stopped processing. If successful, UsageLength + will be unchanged. In any error condition, this parameter + reflects how many of the usages in the usage list have + actually been set by the parser. This is useful for finding + the usage in the list which caused the error. + + PreparsedData The preparsed data recevied from HIDCLASS + + Report The report packet. + + ReportLength Length of the given report packet...Must be equal to the + value reported in the HIDP_CAPS structure for the device + and corresponding report type. + +Return Value + HidP_SetUsages returns the following error codes. On error, the report packet + will be correct up until the usage element that caused the error. + +· HIDP_STATUS_SUCCESS -- upon successful insertion of all usages + into the report packet. +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a + different report. If the report is + zero-initialized on entry the first + usage in the list will determine which + report ID is used. Otherwise, the + parser will verify that usage matches + the passed in report's ID +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage does not exist for any + report (no matter what the report ID) + for the given report type. +· HIDP_STATUS_BUFFER_TOO_SMALL -- if there are not enough entries in a + given Main Array Item to list all of + the given usages. The caller needs + to split his request into more than + one call +--*/ + +#define HidP_UnsetButtons(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) \ + HidP_UnsetUsages(Rty, Up, Lco, ULi, ULe, Ppd, Rep, Rle) + +NTSTATUS __stdcall +HidP_UnsetUsages ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN PUSAGE UsageList, + IN OUT PULONG UsageLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + This function unsets (turns off) binary values (buttons) in the report. Given + an initialized packet of correct length, it modifies the report packet so + that each element in the given list of usages has been unset in the + report packet. + + This function is the "undo" operation for SetUsages. If the given usage + is not already set in the Report, it will return an error code of + HIDP_STATUS_BUTTON_NOT_PRESSED. If the button is pressed, HidP_UnsetUsages + will unset the appropriate bit or remove the corresponding index value from + the HID Main Array Item. + + A properly initialized Report packet is one of the correct byte length, + and all zeros.. + + NOTE: A packet that has already been set with a call to a HidP_Set routine + can also be passed in. This routine then processes the UsageList + in the same fashion but verifies that the ReportID already set in + Report matches the report ID for the given usages. + +Parameters: + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + UsagePage All of the usages in the usage array, which HidP_UnsetUsages will + unset in the report, refer to this same usage page. + If a client wishes to unset usages in a report for multiple + usage pages then that client needs to make multiple calls to + HidP_UnsetUsages for each of the usage pages. + + UsageList A usage array containing the usages that HidP_UnsetUsages will + unset in the report packet. + + UsageLength The length of the given usage array in array elements. + The parser will set this value to the position in the usage + array where it stopped processing. If successful, UsageLength + will be unchanged. In any error condition, this parameter + reflects how many of the usages in the usage list have + actually been unset by the parser. This is useful for finding + the usage in the list which caused the error. + + PreparsedData The preparsed data recevied from HIDCLASS + + Report The report packet. + + ReportLength Length of the given report packet...Must be equal to the + value reported in the HIDP_CAPS structure for the device + and corresponding report type. + +Return Value + HidP_UnsetUsages returns the following error codes. On error, the report + packet will be correct up until the usage element that caused the error. + +· HIDP_STATUS_SUCCESS -- upon successful "unsetting" of all usages + in the report packet. +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if a usage was found that exists in a + different report. If the report is + zero-initialized on entry the first + usage in the list will determine which + report ID is used. Otherwise, the + parser will verify that usage matches + the passed in report's ID +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage does not exist for any + report (no matter what the report ID) + for the given report type. +· HIDP_STATUS_BUTTON_NOT_PRESSED -- if a usage corresponds to a button that + is not already set in the given report +--*/ + +#define HidP_GetButtons(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) \ + HidP_GetUsages(Rty, UPa, LCo, ULi, ULe, Ppd, Rep, RLe) + +NTSTATUS __stdcall +HidP_GetUsages ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + OUT USAGE * UsageList, + IN OUT ULONG * UsageLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); +/*++ + +Routine Description: + This function returns the binary values (buttons) that are set in a HID + report. Given a report packet of correct length, it searches the report + packet for each usage for the given usage page and returns them in the + usage list. + +Parameters: + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + UsagePage All of the usages in the usage list, which HidP_GetUsages will + retrieve in the report, refer to this same usage page. + If the client wishes to get usages in a packet for multiple + usage pages then that client needs to make multiple calls + to HidP_GetUsages. + + LinkCollection An optional value which can limit which usages are returned + in the UsageList to those usages that exist in a specific + LinkCollection. A non-zero value indicates the index into + the HIDP_LINK_COLLECITON_NODE list returned by + HidP_GetLinkCollectionNodes of the link collection the + usage should belong to. A value of 0 indicates this + should value be ignored. + + UsageList The usage array that will contain all the usages found in + the report packet. + + UsageLength The length of the given usage array in array elements. + On input, this value describes the length of the usage list. + On output, HidP_GetUsages sets this value to the number of + usages that was found. Use HidP_MaxUsageListLength to + determine the maximum length needed to return all the usages + that a given report packet may contain. + + PreparsedData Preparsed data structure returned by HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet + + +Return Value + HidP_GetUsages returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully retrieving all the + usages from the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_BUFFER_TOO_SMALL -- if the UsageList is not big enough to + hold all the usages found in the report + packet. If this is returned, the buffer + will contain UsageLength number of + usages. Use HidP_MaxUsageListLength to + find the maximum length needed +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages + that match the UsagePage and + LinkCollection specified could be found + in a report with a different report ID +· HIDP_STATUS_USAGE_NOT_FOUND -- if there are no usages in a reports for + the device and ReportType that match the + UsagePage and LinkCollection that were + specified +--*/ + +#define HidP_GetButtonsEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe) \ + HidP_GetUsagesEx(Rty, LCo, BLi, ULe, Ppd, Rep, RLe) + +NTSTATUS __stdcall +HidP_GetUsagesEx ( + IN HIDP_REPORT_TYPE ReportType, + IN USHORT LinkCollection, // Optional + OUT PUSAGE_AND_PAGE ButtonList, + IN OUT ULONG * UsageLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); + +/*++ + +Routine Description: + This function returns the binary values (buttons) in a HID report. + Given a report packet of correct length, it searches the report packet + for all buttons and returns the UsagePage and Usage for each of the buttons + it finds. + +Parameters: + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + LinkCollection An optional value which can limit which usages are returned + in the ButtonList to those usages that exist in a specific + LinkCollection. A non-zero value indicates the index into + the HIDP_LINK_COLLECITON_NODE list returned by + HidP_GetLinkCollectionNodes of the link collection the + usage should belong to. A value of 0 indicates this + should value be ignored. + + ButtonList An array of USAGE_AND_PAGE structures describing all the + buttons currently ``down'' in the device. + + UsageLength The length of the given array in terms of elements. + On input, this value describes the length of the list. On + output, HidP_GetUsagesEx sets this value to the number of + usages that were found. Use HidP_MaxUsageListLength to + determine the maximum length needed to return all the usages + that a given report packet may contain. + + PreparsedData Preparsed data returned by HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value + HidP_GetUsagesEx returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully retrieving all the + usages from the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_BUFFER_TOO_SMALL -- if ButtonList is not big enough to + hold all the usages found in the report + packet. If this is returned, the buffer + will contain UsageLength number of + usages. Use HidP_MaxUsageListLength to + find the maximum length needed +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages + that match the specified LinkCollection + exist in report with a different report + ID. +· HIDP_STATUS_USAGE_NOT_FOUND -- if there are no usages in any reports that + match the LinkCollection parameter +--*/ + +#define HidP_GetButtonListLength(RTy, UPa, Ppd) \ + HidP_GetUsageListLength(Rty, UPa, Ppd) + +ULONG __stdcall +HidP_MaxUsageListLength ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, // Optional + IN PHIDP_PREPARSED_DATA PreparsedData + ); +/*++ +Routine Description: + This function returns the maximum number of usages that a call to + HidP_GetUsages or HidP_GetUsagesEx could return for a given HID report. + If calling for number of usages returned by HidP_GetUsagesEx, use 0 as + the UsagePage value. + +Parameters: + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + UsagePage Specifies the optional UsagePage to query for. If 0, will + return all the maximum number of usage values that could be + returned for a given ReportType. If non-zero, will return + the maximum number of usages that would be returned for the + ReportType with the given UsagePage. + + PreparsedData Preparsed data returned from HIDCLASS + +Return Value: + The length of the usage list array required for the HidP_GetUsages or + HidP_GetUsagesEx function call. If an error occurs (such as + HIDP_STATUS_INVALID_REPORT_TYPE or HIDP_INVALID_PREPARSED_DATA, this + returns 0. +--*/ + +NTSTATUS __stdcall +HidP_SetUsageValue ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + IN ULONG UsageValue, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); +/*++ +Description: + HidP_SetUsageValue inserts a value into the HID Report Packet in the field + corresponding to the given usage page and usage. HidP_SetUsageValue + casts this value to the appropriate bit length. If a report packet + contains two different fields with the same Usage and UsagePage, + they can be distinguished with the optional LinkCollection field value. + Using this function sets the raw value into the report packet with + no checking done as to whether it actually falls within the logical + minimum/logical maximum range. Use HidP_SetScaledUsageValue for this... + + NOTE: Although the UsageValue parameter is a ULONG, any casting that is + done will preserve or sign-extend the value. The value being set + should be considered a LONG value and will be treated as such by + this function. + +Parameters: + + ReportType One of HidP_Output or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will set the first field + it finds that matches the usage page and + usage. + + Usage The usage whose value HidP_SetUsageValue will set. + + UsageValue The raw value to set in the report buffer. This value must be within + the logical range or if a NULL value this value should be the + most negative value that can be represented by the number of bits + for this field. + + PreparsedData The preparsed data returned for HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value: + HidP_SetUsageValue returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully setting the value + in the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call HidP_SetUsageValue + again with a zero-initizialed report + packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + +NTSTATUS __stdcall +HidP_SetScaledUsageValue ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + IN LONG UsageValue, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN OUT PCHAR Report, + IN ULONG ReportLength + ); + +/*++ +Description: + HidP_SetScaledUsageValue inserts the UsageValue into the HID report packet + in the field corresponding to the given usage page and usage. If a report + packet contains two different fields with the same Usage and UsagePage, + they can be distinguished with the optional LinkCollection field value. + + If the specified field has a defined physical range, this function converts + the physical value specified to the corresponding logical value for the + report. If a physical value does not exist, the function will verify that + the value specified falls within the logical range and set according. + + If the range checking fails but the field has NULL values, the function will + set the field to the defined NULL value (most negative number possible) and + return HIDP_STATUS_NULL. In other words, use this function to set NULL + values for a given field by passing in a value that falls outside the + physical range if it is defined or the logical range otherwise. + + If the field does not support NULL values, an out of range error will be + returned instead. + +Parameters: + + ReportType One of HidP_Output or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will set the first field + it finds that matches the usage page and + usage. + + Usage The usage whose value HidP_SetScaledUsageValue will set. + + UsageValue The value to set in the report buffer. See the routine + description above for the different interpretations of this + value + + PreparsedData The preparsed data returned from HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value: + HidP_SetScaledUsageValue returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully setting the value + in the report packet +· HIDP_STATUS_NULL -- upon successfully setting the value + in the report packet as a NULL value +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_VALUE_OUT_OF_RANGE -- if the value specified failed to fall + within the physical range if it exists + or within the logical range otherwise + and the field specified by the usage + does not allow NULL values +· HIDP_STATUS_BAD_LOG_PHY_VALUES -- if the field has a physical range but + either the logical range is invalid + (max <= min) or the physical range is + invalid +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call + HidP_SetScaledUsageValue again with + a zero-initialized report packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + +NTSTATUS __stdcall +HidP_SetUsageValueArray ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + IN PCHAR UsageValue, + IN USHORT UsageValueByteLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + OUT PCHAR Report, + IN ULONG ReportLength + ); + +/*++ +Routine Descripton: + A usage value array occurs when the last usage in the list of usages + describing a main item must be repeated because there are less usages defined + than there are report counts declared for the given main item. In this case + a single value cap is allocated for that usage and the report count of that + value cap is set to reflect the number of fields to which that usage refers. + + HidP_SetUsageValueArray sets the raw bits for that usage which spans + more than one field in a report. + + NOTE: This function currently does not support value arrays where the + ReportSize for each of the fields in the array is not a multiple + of 8 bits. + + The UsageValue buffer should have the values set as they would appear + in the report buffer. If this function supported non 8-bit multiples + for the ReportSize then caller should format the input buffer so that + each new value begins at the bit immediately following the last bit + of the previous value + +Parameters: + + ReportType One of HidP_Output or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will set the first field + it finds that matches the usage page and + usage. + + Usage The usage whose value array HidP_SetUsageValueArray will set. + + UsageValue The buffer with the values to set into the value array. + The number of BITS required is found by multiplying the + BitSize and ReportCount fields of the Value Cap for this + control. The least significant bit of this control found in the + given report will be placed in the least significan bit location + of the array given (little-endian format), regardless of whether + or not the field is byte alligned or if the BitSize is a multiple + of sizeof (CHAR). + + See the above note for current implementation limitations. + + UsageValueByteLength Length of the UsageValue buffer (in bytes) + + PreparsedData The preparsed data returned from HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value: +· HIDP_STATUS_SUCCESS -- upon successfully setting the value + array in the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_NOT_VALUE_ARRAY -- if the control specified is not a + value array -- a value array will have + a ReportCount field in the + HIDP_VALUE_CAPS structure that is > 1 + Use HidP_SetUsageValue instead +· HIDP_STATUS_BUFFER_TOO_SMALL -- if the size of the passed in buffer with + the values to set is too small (ie. has + fewer values than the number of fields in + the array +· HIDP_STATUS_NOT_IMPLEMENTED -- if the usage value array has field sizes + that are not multiples of 8 bits, this + error code is returned since the function + currently does not handle setting into + such arrays. +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call + HidP_SetUsageValueArray again with + a zero-initialized report packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + + +NTSTATUS __stdcall +HidP_GetUsageValue ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + OUT PULONG UsageValue, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); + +/* +Description + HidP_GetUsageValue retrieves the value from the HID Report for the usage + specified by the combination of usage page, usage and link collection. + If a report packet contains two different fields with the same + Usage and UsagePage, they can be distinguished with the optional + LinkCollection field value. + +Parameters: + + ReportType One of HidP_Input or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will set the first field + it finds that matches the usage page and + usage. + + Usage The usage whose value HidP_GetUsageValue will retrieve + + UsageValue The raw value that is set for the specified field in the report + buffer. This value will either fall within the logical range + or if NULL values are allowed, a number outside the range to + indicate a NULL + + PreparsedData The preparsed data returned for HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value: + HidP_GetUsageValue returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully retrieving the value + from the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_REPORT_DOES_NOT_EXIST -- if there are no reports on this device + for the given ReportType +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call HidP_GetUsageValue + again with a different report packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + + +NTSTATUS __stdcall +HidP_GetScaledUsageValue ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + OUT PLONG UsageValue, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); + +/*++ +Description + HidP_GetScaledUsageValue retrieves a UsageValue from the HID report packet + in the field corresponding to the given usage page and usage. If a report + packet contains two different fields with the same Usage and UsagePage, + they can be distinguished with the optional LinkCollection field value. + + If the specified field has a defined physical range, this function converts + the logical value that exists in the report packet to the corresponding + physical value. If a physical range does not exist, the function will + return the logical value. This function will check to verify that the + logical value in the report falls within the declared logical range. + + When doing the conversion between logical and physical values, this + function assumes a linear extrapolation between the physical max/min and + the logical max/min. (Where logical is the values reported by the device + and physical is the value returned by this function). If the data field + size is less than 32 bits, then HidP_GetScaledUsageValue will sign extend + the value to 32 bits. + + If the range checking fails but the field has NULL values, the function + will set UsageValue to 0 and return HIDP_STATUS_NULL. Otherwise, it + returns a HIDP_STATUS_OUT_OF_RANGE error. + +Parameters: + + ReportType One of HidP_Output or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will retrieve the first + field it finds that matches the usage page + and usage. + + Usage The usage whose value HidP_GetScaledUsageValue will retrieve + + UsageValue The value retrieved from the report buffer. See the routine + description above for the different interpretations of this + value + + PreparsedData The preparsed data returned from HIDCLASS + + Report The report packet. + + ReportLength Length (in bytes) of the given report packet. + + +Return Value: + HidP_GetScaledUsageValue returns the following error codes: + +· HIDP_STATUS_SUCCESS -- upon successfully retrieving the value + from the report packet +· HIDP_STATUS_NULL -- if the report packet had a NULL value + set +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_VALUE_OUT_OF_RANGE -- if the value retrieved from the packet + falls outside the logical range and + the field does not support NULL values +· HIDP_STATUS_BAD_LOG_PHY_VALUES -- if the field has a physical range but + either the logical range is invalid + (max <= min) or the physical range is + invalid +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call + HidP_GetScaledUsageValue with a + different report packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + +NTSTATUS __stdcall +HidP_GetUsageValueArray ( + IN HIDP_REPORT_TYPE ReportType, + IN USAGE UsagePage, + IN USHORT LinkCollection, // Optional + IN USAGE Usage, + OUT PCHAR UsageValue, + IN USHORT UsageValueByteLength, + IN PHIDP_PREPARSED_DATA PreparsedData, + IN PCHAR Report, + IN ULONG ReportLength + ); + +/*++ +Routine Descripton: + A usage value array occurs when the last usage in the list of usages + describing a main item must be repeated because there are less usages defined + than there are report counts declared for the given main item. In this case + a single value cap is allocated for that usage and the report count of that + value cap is set to reflect the number of fields to which that usage refers. + + HidP_GetUsageValueArray returns the raw bits for that usage which spans + more than one field in a report. + + NOTE: This function currently does not support value arrays where the + ReportSize for each of the fields in the array is not a multiple + of 8 bits. + + The UsageValue buffer will have the raw values as they are set + in the report packet. + +Parameters: + + ReportType One of HidP_Input, HidP_Output or HidP_Feature. + + UsagePage The usage page to which the given usage refers. + + LinkCollection (Optional) This value can be used to differentiate + between two fields that may have the same + UsagePage and Usage but exist in different + collections. If the link collection value + is zero, this function will set the first field + it finds that matches the usage page and + usage. + + Usage The usage whose value HidP_GetUsageValueArray will retreive. + + UsageValue A pointer to an array of characters where the value will be + placed. The number of BITS required is found by multiplying the + BitSize and ReportCount fields of the Value Cap for this + control. The least significant bit of this control found in the + given report will be placed in the least significant bit location + of the buffer (little-endian format), regardless of whether + or not the field is byte aligned or if the BitSize is a multiple + of sizeof (CHAR). + + See note above about current implementation limitations + + UsageValueByteLength + the length of the given UsageValue buffer. + + PreparsedData The preparsed data returned by the HIDCLASS + + Report The report packet. + + ReportLength Length of the given report packet. + +Return Value: + +· HIDP_STATUS_SUCCESS -- upon successfully retrieving the value + from the report packet +· HIDP_STATUS_INVALID_REPORT_TYPE -- if ReportType is not valid. +· HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid +· HIDP_STATUS_INVALID_REPORT_LENGTH -- the length of the report packet is not + equal to the length specified in + the HIDP_CAPS structure for the given + ReportType +· HIDP_STATUS_NOT_VALUE_ARRAY -- if the control specified is not a + value array -- a value array will have + a ReportCount field in the + HIDP_VALUE_CAPS structure that is > 1 + Use HidP_GetUsageValue instead +· HIDP_STATUS_BUFFER_TOO_SMALL -- if the size of the passed in buffer in + which to return the array is too small + (ie. has fewer values than the number of + fields in the array +· HIDP_STATUS_NOT_IMPLEMENTED -- if the usage value array has field sizes + that are not multiples of 8 bits, this + error code is returned since the function + currently does not handle getting values + from such arrays. +· HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- the specified usage page, usage and + link collection exist but exists in + a report with a different report ID + than the report being passed in. To + set this value, call + HidP_GetUsageValueArray with a + different report packet +· HIDP_STATUS_USAGE_NOT_FOUND -- if the usage page, usage, and link + collection combination does not exist + in any reports for this ReportType +--*/ + +NTSTATUS __stdcall +HidP_UsageListDifference ( + IN PUSAGE PreviousUsageList, + IN PUSAGE CurrentUsageList, + OUT PUSAGE BreakUsageList, + OUT PUSAGE MakeUsageList, + IN ULONG UsageListLength + ); +/*++ +Routine Description: + This function will return the difference between a two lists of usages + (as might be returned from HidP_GetUsages), In other words, it will return + return a list of usages that are in the current list but not the previous + list as well as a list of usages that are in the previous list but not + the current list. + +Parameters: + + PreviousUsageList The list of usages before. + CurrentUsageList The list of usages now. + BreakUsageList Previous - Current. + MakeUsageList Current - Previous. + UsageListLength Represents the length of the usage lists in array + elements. If comparing two lists with a differing + number of array elements, this value should be + the size of the larger of the two lists. Any + zero found with a list indicates an early termination + of the list and any usages found after the first zero + will be ignored. +--*/ + +NTSTATUS __stdcall +HidP_UsageAndPageListDifference ( + IN PUSAGE_AND_PAGE PreviousUsageList, + IN PUSAGE_AND_PAGE CurrentUsageList, + OUT PUSAGE_AND_PAGE BreakUsageList, + OUT PUSAGE_AND_PAGE MakeUsageList, + IN ULONG UsageListLength + ); + +// +// Produce Make or Break Codes +// +typedef enum _HIDP_KEYBOARD_DIRECTION { + HidP_Keyboard_Break, + HidP_Keyboard_Make +} HIDP_KEYBOARD_DIRECTION; + +// +// A bitmap of the current shift state of the keyboard when using the +// below keyboard usages to i8042 translation function. +// +typedef struct _HIDP_KEYBOARD_MODIFIER_STATE { + union { + struct { + ULONG LeftControl: 1; + ULONG LeftShift: 1; + ULONG LeftAlt: 1; + ULONG LeftGUI: 1; + ULONG RightControl: 1; + ULONG RightShift: 1; + ULONG RightAlt: 1; + ULONG RigthGUI: 1; + ULONG CapsLock: 1; + ULONG ScollLock: 1; + ULONG NumLock: 1; + ULONG Reserved: 21; + }; + ULONG ul; + }; + +} HIDP_KEYBOARD_MODIFIER_STATE, * PHIDP_KEYBOARD_MODIFIER_STATE; + +// +// A call back function to give the i8042 scan codes to the caller of +// the below translation function. +// +typedef BOOLEAN (* PHIDP_INSERT_SCANCODES) ( + IN PVOID Context, // Some caller supplied context. + IN PCHAR NewScanCodes, // A list of i8042 scan codes. + IN ULONG Length // the length of the scan codes. + ); + +NTSTATUS __stdcall +HidP_TranslateUsageAndPagesToI8042ScanCodes ( + IN PUSAGE_AND_PAGE ChangedUsageList, + IN ULONG UsageListLength, + IN HIDP_KEYBOARD_DIRECTION KeyAction, + IN OUT PHIDP_KEYBOARD_MODIFIER_STATE ModifierState, + IN PHIDP_INSERT_SCANCODES InsertCodesProcedure, + IN PVOID InsertCodesContext + ); +/*++ +Routine Description: +Parameters: +--*/ + +NTSTATUS __stdcall +HidP_TranslateUsagesToI8042ScanCodes ( + IN PUSAGE ChangedUsageList, + IN ULONG UsageListLength, + IN HIDP_KEYBOARD_DIRECTION KeyAction, + IN OUT PHIDP_KEYBOARD_MODIFIER_STATE ModifierState, + IN PHIDP_INSERT_SCANCODES InsertCodesProcedure, + IN PVOID InsertCodesContext + ); +/*++ +Routine Description: +Parameters: +--*/ + + + +// +// Define NT Status codes with Facility Code of FACILITY_HID_ERROR_CODE +// + +// FACILITY_HID_ERROR_CODE defined in ntstatus.h +#ifndef FACILITY_HID_ERROR_CODE +#define FACILITY_HID_ERROR_CODE 0x11 +#endif + +#define HIDP_ERROR_CODES(SEV, CODE) \ + ((NTSTATUS) (((SEV) << 28) | (FACILITY_HID_ERROR_CODE << 16) | (CODE))) + +#define HIDP_STATUS_SUCCESS (HIDP_ERROR_CODES(0x0,0)) +#define HIDP_STATUS_NULL (HIDP_ERROR_CODES(0x8,1)) +#define HIDP_STATUS_INVALID_PREPARSED_DATA (HIDP_ERROR_CODES(0xC,1)) +#define HIDP_STATUS_INVALID_REPORT_TYPE (HIDP_ERROR_CODES(0xC,2)) +#define HIDP_STATUS_INVALID_REPORT_LENGTH (HIDP_ERROR_CODES(0xC,3)) +#define HIDP_STATUS_USAGE_NOT_FOUND (HIDP_ERROR_CODES(0xC,4)) +#define HIDP_STATUS_VALUE_OUT_OF_RANGE (HIDP_ERROR_CODES(0xC,5)) +#define HIDP_STATUS_BAD_LOG_PHY_VALUES (HIDP_ERROR_CODES(0xC,6)) +#define HIDP_STATUS_BUFFER_TOO_SMALL (HIDP_ERROR_CODES(0xC,7)) +#define HIDP_STATUS_INTERNAL_ERROR (HIDP_ERROR_CODES(0xC,8)) +#define HIDP_STATUS_I8042_TRANS_UNKNOWN (HIDP_ERROR_CODES(0xC,9)) +#define HIDP_STATUS_INCOMPATIBLE_REPORT_ID (HIDP_ERROR_CODES(0xC,0xA)) +#define HIDP_STATUS_NOT_VALUE_ARRAY (HIDP_ERROR_CODES(0xC,0xB)) +#define HIDP_STATUS_IS_VALUE_ARRAY (HIDP_ERROR_CODES(0xC,0xC)) +#define HIDP_STATUS_DATA_INDEX_NOT_FOUND (HIDP_ERROR_CODES(0xC,0xD)) +#define HIDP_STATUS_DATA_INDEX_OUT_OF_RANGE (HIDP_ERROR_CODES(0xC,0xE)) +#define HIDP_STATUS_BUTTON_NOT_PRESSED (HIDP_ERROR_CODES(0xC,0xF)) +#define HIDP_STATUS_REPORT_DOES_NOT_EXIST (HIDP_ERROR_CODES(0xC,0x10)) +#define HIDP_STATUS_NOT_IMPLEMENTED (HIDP_ERROR_CODES(0xC,0x20)) + +// +// We blundered this status code. +// +#define HIDP_STATUS_I8242_TRANS_UNKNOWN HIDP_STATUS_I8042_TRANS_UNKNOWN + +#include + +#endif