/*++
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 __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 <poppack.h>
#endif