fixed an intermitent pain in the ass to track down crash in the GUI client due to...

[proxmark3-svn] / winsrc / include / hidpi.h

/*++\r
\r
Copyright (c) 1996-1998      Microsoft Corporation\r
\r
Module Name:\r
\r
        HIDPI.H\r
\r
Abstract:\r
\r
   Public Interface to the HID parsing library.\r
\r
Environment:\r
\r
    Kernel & user mode\r
\r
--*/\r
\r
#ifndef   __HIDPI_H__\r
#define   __HIDPI_H__\r
\r
#include <pshpack4.h>\r
\r
// Please include "hidsdi.h" to use the user space (dll / parser)\r
// Please include "hidpddi.h" to use the kernel space parser\r
\r
//\r
// Special Link collection values for using the query functions\r
//\r
// Root collection references the collection at the base of the link\r
// collection tree.\r
// Unspecifies, references all collections in the link collection tree.\r
//\r
#define HIDP_LINK_COLLECTION_ROOT ((USHORT) -1)\r
#define HIDP_LINK_COLLECTION_UNSPECIFIED ((USHORT) 0)\r
\r
\r
typedef enum _HIDP_REPORT_TYPE\r
{\r
    HidP_Input,\r
    HidP_Output,\r
    HidP_Feature\r
} HIDP_REPORT_TYPE;\r
\r
typedef struct _USAGE_AND_PAGE\r
{\r
    USAGE Usage;\r
    USAGE UsagePage;\r
} USAGE_AND_PAGE, *PUSAGE_AND_PAGE;\r
\r
#define HidP_IsSameUsageAndPage(u1, u2) ((* (PULONG) &u1) == (* (PULONG) &u2))\r
\r
typedef struct _HIDP_BUTTON_CAPS\r
{\r
    USAGE    UsagePage;\r
    UCHAR    ReportID;\r
    BOOLEAN  IsAlias;\r
\r
    USHORT   BitField;\r
    USHORT   LinkCollection;   // A unique internal index pointer\r
\r
    USAGE    LinkUsage;\r
    USAGE    LinkUsagePage;\r
\r
    BOOLEAN  IsRange;\r
    BOOLEAN  IsStringRange;\r
    BOOLEAN  IsDesignatorRange;\r
    BOOLEAN  IsAbsolute;\r
\r
    ULONG    Reserved[10];\r
    union {\r
        struct {\r
            USAGE    UsageMin,         UsageMax;\r
            USHORT   StringMin,        StringMax;\r
            USHORT   DesignatorMin,    DesignatorMax;\r
            USHORT   DataIndexMin,     DataIndexMax;\r
        } Range;\r
        struct  {\r
            USAGE    Usage,            Reserved1;\r
            USHORT   StringIndex,      Reserved2;\r
            USHORT   DesignatorIndex,  Reserved3;\r
            USHORT   DataIndex,        Reserved4;\r
        } NotRange;\r
    };\r
\r
} HIDP_BUTTON_CAPS, *PHIDP_BUTTON_CAPS;\r
\r
\r
typedef struct _HIDP_VALUE_CAPS\r
{\r
    USAGE    UsagePage;\r
    UCHAR    ReportID;\r
    BOOLEAN  IsAlias;\r
\r
    USHORT   BitField;\r
    USHORT   LinkCollection;   // A unique internal index pointer\r
\r
    USAGE    LinkUsage;\r
    USAGE    LinkUsagePage;\r
\r
    BOOLEAN  IsRange;\r
    BOOLEAN  IsStringRange;\r
    BOOLEAN  IsDesignatorRange;\r
    BOOLEAN  IsAbsolute;\r
\r
    BOOLEAN  HasNull;        // Does this channel have a null report   union\r
    UCHAR    Reserved;\r
    USHORT   BitSize;        // How many bits are devoted to this value?\r
\r
    USHORT   ReportCount;    // See Note below.  Usually set to 1.\r
    USHORT   Reserved2[5];\r
\r
    ULONG    UnitsExp;\r
    ULONG    Units;\r
\r
    LONG     LogicalMin,       LogicalMax;\r
    LONG     PhysicalMin,      PhysicalMax;\r
\r
    union {\r
        struct {\r
            USAGE    UsageMin,         UsageMax;\r
            USHORT   StringMin,        StringMax;\r
            USHORT   DesignatorMin,    DesignatorMax;\r
            USHORT   DataIndexMin,     DataIndexMax;\r
        } Range;\r
\r
        struct {\r
            USAGE    Usage,            Reserved1;\r
            USHORT   StringIndex,      Reserved2;\r
            USHORT   DesignatorIndex,  Reserved3;\r
            USHORT   DataIndex,        Reserved4;\r
        } NotRange;\r
    };\r
} HIDP_VALUE_CAPS, *PHIDP_VALUE_CAPS;\r
\r
//\r
// Notes:\r
//\r
// ReportCount:  When a report descriptor declares an Input, Output, or\r
// Feature main item with fewer usage declarations than the report count, then\r
// the last usage applies to all remaining unspecified count in that main item.\r
// (As an example you might have data that required many fields to describe,\r
// possibly buffered bytes.)  In this case, only one value cap structure is\r
// allocated for these associtated fields, all with the same usage, and Report\r
// Count reflects the number of fields involved.  Normally ReportCount is 1.\r
// To access all of the fields in such a value structure would require using\r
// HidP_GetUsageValueArray and HidP_SetUsageValueArray.   HidP_GetUsageValue/\r
// HidP_SetScaledUsageValue will also work, however, these functions will only\r
// work with the first field of the structure.\r
//\r
\r
//\r
// The link collection tree consists of an array of LINK_COLLECTION_NODES\r
// where the index into this array is the same as the collection number.\r
//\r
// Given a collection A which contains a subcollection B, A is defined to be\r
// the parent B, and B is defined to be the child.\r
//\r
// Given collections A, B, and C where B and C are children of A, and B was\r
// encountered before C in the report descriptor, B is defined as a sibling of\r
// C.  (This implies, of course, that if B is a sibling of C, then C is NOT a\r
// sibling of B).\r
//\r
// B is defined as the NextSibling of C if and only if there exists NO\r
// child collection of A, call it D, such that B is a sibling of D and D\r
// is a sibling of C.\r
//\r
// E is defined to be the FirstChild of A if and only if for all children of A,\r
// F, that are not equivalent to E, F is a sibling of E.\r
// (This implies, of course, that the does not exist a child of A, call it G,\r
// where E is a sibling of G).  In other words the first sibling is the last\r
// link collection found in the list.\r
//\r
// In other words, if a collection B is defined within the definition of another\r
// collection A, B becomes a child of A.  All collections with the same parent\r
// are considered siblings.  The FirstChild of the parent collection, A, will be\r
// last collection defined that has A as a parent.  The order of sibling pointers\r
// is similarly determined.  When a collection B is defined, it becomes the\r
// FirstChild of it's parent collection.  The previously defined FirstChild of the\r
// parent collection becomes the NextSibling of the new collection.  As new\r
// collections with the same parent are discovered, the chain of sibling is built.\r
//\r
// With that in mind, the following describes conclusively a data structure\r
// that provides direct traversal up, down, and accross the link collection\r
// tree.\r
//\r
//\r
typedef struct _HIDP_LINK_COLLECTION_NODE\r
{\r
    USAGE    LinkUsage;\r
    USAGE    LinkUsagePage;\r
    USHORT   Parent;\r
    USHORT   NumberOfChildren;\r
    USHORT   NextSibling;\r
    USHORT   FirstChild;\r
    ULONG    CollectionType: 8;  // As defined in 6.2.2.6 of HID spec\r
    ULONG    IsAlias : 1; // This link node is an allias of the next link node.\r
    ULONG    Reserved: 23;\r
    PVOID    UserContext; // The user can hang his coat here.\r
} HIDP_LINK_COLLECTION_NODE, *PHIDP_LINK_COLLECTION_NODE;\r
\r
//\r
// When a link collection is described by a delimiter, alias link collection\r
// nodes are created.  (One for each usage within the delimiter).\r
// The parser assigns each capability description listed above only one\r
// link collection.\r
//\r
// If a control is defined within a collection defined by\r
// delimited usages, then that control is said to be within multiple link\r
// collections, one for each usage within the open and close delimiter tokens.\r
// Such multiple link collecions are said to be aliases.  The first N-1 such\r
// collections, listed in the link collection node array, have their IsAlias\r
// bit set.  The last such link collection is the link collection index used\r
// in the capabilities described above.\r
// Clients wishing to set a control in an aliased collection, should walk the\r
// collection array once for each time they see the IsAlias flag set, and use\r
// the last link collection as the index for the below accessor functions.\r
//\r
// NB: if IsAlias is set, then NextSibling should be one more than the current\r
// link collection node index.\r
//\r
\r
typedef PUCHAR  PHIDP_REPORT_DESCRIPTOR;\r
typedef struct _HIDP_PREPARSED_DATA * PHIDP_PREPARSED_DATA;\r
\r
typedef struct _HIDP_CAPS\r
{\r
    USAGE    Usage;\r
    USAGE    UsagePage;\r
    USHORT   InputReportByteLength;\r
    USHORT   OutputReportByteLength;\r
    USHORT   FeatureReportByteLength;\r
    USHORT   Reserved[17];\r
\r
    USHORT   NumberLinkCollectionNodes;\r
\r
    USHORT   NumberInputButtonCaps;\r
    USHORT   NumberInputValueCaps;\r
    USHORT   NumberInputDataIndices;\r
\r
    USHORT   NumberOutputButtonCaps;\r
    USHORT   NumberOutputValueCaps;\r
    USHORT   NumberOutputDataIndices;\r
\r
    USHORT   NumberFeatureButtonCaps;\r
    USHORT   NumberFeatureValueCaps;\r
    USHORT   NumberFeatureDataIndices;\r
} HIDP_CAPS, *PHIDP_CAPS;\r
\r
typedef struct _HIDP_DATA\r
{\r
    USHORT  DataIndex;\r
    USHORT  Reserved;\r
    union {\r
        ULONG   RawValue; // for values\r
        BOOLEAN On; // for buttons MUST BE TRUE for buttons.\r
    };\r
} HIDP_DATA, *PHIDP_DATA;\r
//\r
// The HIDP_DATA structure is used with HidP_GetData and HidP_SetData\r
// functions.\r
//\r
// The parser contiguously assigns every control (button or value) in a hid\r
// device a unique data index from zero to NumberXXXDataIndices -1 , inclusive.\r
// This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures.\r
//\r
// Most clients will find the Get/Set Buttons / Value accessor functions\r
// sufficient to their needs, as they will allow the clients to access the\r
// data known to them while ignoring the other controls.\r
//\r
// More complex clients, which actually read the Button / Value Caps, and which\r
// do a value add service to these routines (EG Direct Input), will need to\r
// access all the data in the device without interest in the individual usage\r
// or link collection location.  These are the clients that will find\r
// HidP_Data useful.\r
//\r
\r
typedef struct _HIDP_UNKNOWN_TOKEN\r
{\r
    UCHAR  Token;\r
    UCHAR  Reserved[3];\r
    ULONG  BitField;\r
} HIDP_UNKNOWN_TOKEN, *PHIDP_UNKNOWN_TOKEN;\r
\r
typedef struct _HIDP_EXTENDED_ATTRIBUTES\r
{\r
    UCHAR   NumGlobalUnknowns;\r
    UCHAR   Reserved [3];\r
    PHIDP_UNKNOWN_TOKEN  GlobalUnknowns;\r
    // ... Additional attributes\r
    ULONG   Data [1]; // variableLength  DO NOT ACCESS THIS FIELD\r
} HIDP_EXTENDED_ATTRIBUTES, *PHIDP_EXTENDED_ATTRIBUTES;\r
\r
NTSTATUS __stdcall\r
HidP_GetCaps (\r
   IN      PHIDP_PREPARSED_DATA      PreparsedData,\r
   OUT     PHIDP_CAPS                Capabilities\r
   );\r
/*++\r
Routine Description:\r
   Returns a list of capabilities of a given hid device as described by its\r
   preparsed data.\r
\r
Arguments:\r
   PreparsedData    The preparsed data returned from HIDCLASS.\r
   Capabilities     a HIDP_CAPS structure\r
\r
Return Value:\r