hidpi.h

/*++
 
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);
 
/*++
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