|
|
/*++
Copyright (c) Microsoft Corporation. All rights reserved.
Module Name:
HIDPI.H
Abstract:
Public Interface to the HID parsing library.
Environment:
Kernel & user mode
--*/
#ifndef __HIDPI_H__
#define __HIDPI_H__
#include <pshpack4.h>
// 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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 ValueHidP_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 __stdcallHidP_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 __stdcallHidP_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 ValueHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 __stdcallHidP_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 <poppack.h>
#endif
|
