//

// SL: We use this file to generate P/Invoke using P/Invoke Interop Assistant.

//

typedef USHORT USAGE, *PUSAGE;

typedef LONG NTSTATUS;

#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 (

         PHIDP_PREPARSED_DATA      PreparsedData,

        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 (

        PHIDP_LINK_COLLECTION_NODE LinkCollectionNodes,

      PULONG                     LinkCollectionNodesLength,

         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_GetSpecificButtonCaps (

          HIDP_REPORT_TYPE     ReportType,

          USAGE                UsagePage,      // Optional (0 => ignore)

          USHORT               LinkCollection, // Optional (0 => ignore)

          USAGE                Usage,          // Optional (0 => ignore)

   PHIDP_BUTTON_CAPS    ButtonCaps,

     PUSHORT              ButtonCapsLength,

          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_GetButtonCaps (

          HIDP_REPORT_TYPE     ReportType,

   PHIDP_BUTTON_CAPS ButtonCaps,

       PUSHORT              ButtonCapsLength,

          PHIDP_PREPARSED_DATA PreparsedData

);

NTSTATUS __stdcall

HidP_GetSpecificValueCaps (

          HIDP_REPORT_TYPE     ReportType,

          USAGE                UsagePage,      // Optional (0 => ignore)

          USHORT               LinkCollection, // Optional (0 => ignore)

          USAGE                Usage,          // Optional (0 => ignore)

          PHIDP_VALUE_CAPS     ValueCaps,

       PUSHORT              ValueCapsLength,

          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_GetValueCaps (

          HIDP_REPORT_TYPE     ReportType,

   PHIDP_VALUE_CAPS ValueCaps,

       PUSHORT              ValueCapsLength,

          PHIDP_PREPARSED_DATA PreparsedData

);

NTSTATUS __stdcall

HidP_GetExtendedAttributes (

          HIDP_REPORT_TYPE            ReportType,

          USHORT                      DataIndex,

          PHIDP_PREPARSED_DATA        PreparsedData,

    PHIDP_EXTENDED_ATTRIBUTES Attributes,

       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 (

    HIDP_REPORT_TYPE ReportType,

    UCHAR ReportID,

    PHIDP_PREPARSED_DATA PreparsedData,

   PCHAR Report,

    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 (

     HIDP_REPORT_TYPE ReportType,

    PHIDP_DATA DataList,

     PULONG DataLength,

     PHIDP_PREPARSED_DATA PreparsedData,

    PCHAR Report,

     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 (

     HIDP_REPORT_TYPE ReportType,

    PHIDP_DATA DataList,

     PULONG DataLength,

     PHIDP_PREPARSED_DATA PreparsedData,

    PCHAR Report,

     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 (

    HIDP_REPORT_TYPE      ReportType,

    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 (

    HIDP_REPORT_TYPE    ReportType,

    USAGE   UsagePage,

    USHORT  LinkCollection,

   PUSAGE  UsageList,

     PULONG  UsageLength,

    PHIDP_PREPARSED_DATA  PreparsedData,

   PCHAR   Report,

    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 (

    HIDP_REPORT_TYPE      ReportType,

    USAGE   UsagePage,

   USHORT  LinkCollection,

   PUSAGE  UsageList,

     PULONG  UsageLength,

    PHIDP_PREPARSED_DATA  PreparsedData,

   PCHAR   Report,

    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 (

    HIDP_REPORT_TYPE    ReportType,

    USAGE   UsagePage,

    USHORT  LinkCollection,

   PUSAGE UsageList,

       PULONG UsageLength,

    PHIDP_PREPARSED_DATA PreparsedData,

   PCHAR Report,

    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 (

        HIDP_REPORT_TYPE    ReportType,

        USHORT  LinkCollection, // Optional

    PUSAGE_AND_PAGE  ButtonList,

       ULONG * UsageLength,

     PHIDP_PREPARSED_DATA PreparsedData,

    reads_bytes_(ReportLength)   PCHAR   Report,

     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.