/src/archutils/Win32/ddk/hidpi.h
C Header | 1788 lines | 443 code | 88 blank | 1257 comment | 1 complexity | 6aa3e1b5761adb8806ce8eacfb663ea9 MD5 | raw file
Possible License(s): ISC, LGPL-2.1, BSD-3-Clause
Large files files are truncated, but you can click here to view the full file
- /*++
- Copyright (c) 1996-1998 Microsoft Corporation
- Module Name:
- HIDPI.H
- Abstract:
- Public Interface to the HID parsing library.
- Environment:
- Kernel & user mode
- --*/
- #ifndef __HIDPI_H__
- #define __HIDPI_H__
- #include <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
- );
- /*++
- D…
Large files files are truncated, but you can click here to view the full file