X-Git-Url: http://git.zerfleddert.de/cgi-bin/gitweb.cgi/proxmark3-svn/blobdiff_plain/cd00aa3043b507ed10bf79a37b83b88741d176d7..4cd41f34ead6351f3b0a897453b25c036021c53f:/client/include/hidpi.h diff --git a/client/include/hidpi.h b/client/include/hidpi.h deleted file mode 100644 index e9816cf4..00000000 --- a/client/include/hidpi.h +++ /dev/null @@ -1,1787 +0,0 @@ -/*++ - -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