| 1 | /*++\r |
| 2 | \r |
| 3 | Copyright (c) 1996-1998 Microsoft Corporation\r |
| 4 | \r |
| 5 | Module Name:\r |
| 6 | \r |
| 7 | HIDPI.H\r |
| 8 | \r |
| 9 | Abstract:\r |
| 10 | \r |
| 11 | Public Interface to the HID parsing library.\r |
| 12 | \r |
| 13 | Environment:\r |
| 14 | \r |
| 15 | Kernel & user mode\r |
| 16 | \r |
| 17 | --*/\r |
| 18 | \r |
| 19 | #ifndef __HIDPI_H__\r |
| 20 | #define __HIDPI_H__\r |
| 21 | \r |
| 22 | #include <pshpack4.h>\r |
| 23 | \r |
| 24 | // Please include "hidsdi.h" to use the user space (dll / parser)\r |
| 25 | // Please include "hidpddi.h" to use the kernel space parser\r |
| 26 | \r |
| 27 | //\r |
| 28 | // Special Link collection values for using the query functions\r |
| 29 | //\r |
| 30 | // Root collection references the collection at the base of the link\r |
| 31 | // collection tree.\r |
| 32 | // Unspecifies, references all collections in the link collection tree.\r |
| 33 | //\r |
| 34 | #define HIDP_LINK_COLLECTION_ROOT ((USHORT) -1)\r |
| 35 | #define HIDP_LINK_COLLECTION_UNSPECIFIED ((USHORT) 0)\r |
| 36 | \r |
| 37 | \r |
| 38 | typedef enum _HIDP_REPORT_TYPE\r |
| 39 | {\r |
| 40 | HidP_Input,\r |
| 41 | HidP_Output,\r |
| 42 | HidP_Feature\r |
| 43 | } HIDP_REPORT_TYPE;\r |
| 44 | \r |
| 45 | typedef struct _USAGE_AND_PAGE\r |
| 46 | {\r |
| 47 | USAGE Usage;\r |
| 48 | USAGE UsagePage;\r |
| 49 | } USAGE_AND_PAGE, *PUSAGE_AND_PAGE;\r |
| 50 | \r |
| 51 | #define HidP_IsSameUsageAndPage(u1, u2) ((* (PULONG) &u1) == (* (PULONG) &u2))\r |
| 52 | \r |
| 53 | typedef struct _HIDP_BUTTON_CAPS\r |
| 54 | {\r |
| 55 | USAGE UsagePage;\r |
| 56 | UCHAR ReportID;\r |
| 57 | BOOLEAN IsAlias;\r |
| 58 | \r |
| 59 | USHORT BitField;\r |
| 60 | USHORT LinkCollection; // A unique internal index pointer\r |
| 61 | \r |
| 62 | USAGE LinkUsage;\r |
| 63 | USAGE LinkUsagePage;\r |
| 64 | \r |
| 65 | BOOLEAN IsRange;\r |
| 66 | BOOLEAN IsStringRange;\r |
| 67 | BOOLEAN IsDesignatorRange;\r |
| 68 | BOOLEAN IsAbsolute;\r |
| 69 | \r |
| 70 | ULONG Reserved[10];\r |
| 71 | union {\r |
| 72 | struct {\r |
| 73 | USAGE UsageMin, UsageMax;\r |
| 74 | USHORT StringMin, StringMax;\r |
| 75 | USHORT DesignatorMin, DesignatorMax;\r |
| 76 | USHORT DataIndexMin, DataIndexMax;\r |
| 77 | } Range;\r |
| 78 | struct {\r |
| 79 | USAGE Usage, Reserved1;\r |
| 80 | USHORT StringIndex, Reserved2;\r |
| 81 | USHORT DesignatorIndex, Reserved3;\r |
| 82 | USHORT DataIndex, Reserved4;\r |
| 83 | } NotRange;\r |
| 84 | };\r |
| 85 | \r |
| 86 | } HIDP_BUTTON_CAPS, *PHIDP_BUTTON_CAPS;\r |
| 87 | \r |
| 88 | \r |
| 89 | typedef struct _HIDP_VALUE_CAPS\r |
| 90 | {\r |
| 91 | USAGE UsagePage;\r |
| 92 | UCHAR ReportID;\r |
| 93 | BOOLEAN IsAlias;\r |
| 94 | \r |
| 95 | USHORT BitField;\r |
| 96 | USHORT LinkCollection; // A unique internal index pointer\r |
| 97 | \r |
| 98 | USAGE LinkUsage;\r |
| 99 | USAGE LinkUsagePage;\r |
| 100 | \r |
| 101 | BOOLEAN IsRange;\r |
| 102 | BOOLEAN IsStringRange;\r |
| 103 | BOOLEAN IsDesignatorRange;\r |
| 104 | BOOLEAN IsAbsolute;\r |
| 105 | \r |
| 106 | BOOLEAN HasNull; // Does this channel have a null report union\r |
| 107 | UCHAR Reserved;\r |
| 108 | USHORT BitSize; // How many bits are devoted to this value?\r |
| 109 | \r |
| 110 | USHORT ReportCount; // See Note below. Usually set to 1.\r |
| 111 | USHORT Reserved2[5];\r |
| 112 | \r |
| 113 | ULONG UnitsExp;\r |
| 114 | ULONG Units;\r |
| 115 | \r |
| 116 | LONG LogicalMin, LogicalMax;\r |
| 117 | LONG PhysicalMin, PhysicalMax;\r |
| 118 | \r |
| 119 | union {\r |
| 120 | struct {\r |
| 121 | USAGE UsageMin, UsageMax;\r |
| 122 | USHORT StringMin, StringMax;\r |
| 123 | USHORT DesignatorMin, DesignatorMax;\r |
| 124 | USHORT DataIndexMin, DataIndexMax;\r |
| 125 | } Range;\r |
| 126 | \r |
| 127 | struct {\r |
| 128 | USAGE Usage, Reserved1;\r |
| 129 | USHORT StringIndex, Reserved2;\r |
| 130 | USHORT DesignatorIndex, Reserved3;\r |
| 131 | USHORT DataIndex, Reserved4;\r |
| 132 | } NotRange;\r |
| 133 | };\r |
| 134 | } HIDP_VALUE_CAPS, *PHIDP_VALUE_CAPS;\r |
| 135 | \r |
| 136 | //\r |
| 137 | // Notes:\r |
| 138 | //\r |
| 139 | // ReportCount: When a report descriptor declares an Input, Output, or\r |
| 140 | // Feature main item with fewer usage declarations than the report count, then\r |
| 141 | // the last usage applies to all remaining unspecified count in that main item.\r |
| 142 | // (As an example you might have data that required many fields to describe,\r |
| 143 | // possibly buffered bytes.) In this case, only one value cap structure is\r |
| 144 | // allocated for these associtated fields, all with the same usage, and Report\r |
| 145 | // Count reflects the number of fields involved. Normally ReportCount is 1.\r |
| 146 | // To access all of the fields in such a value structure would require using\r |
| 147 | // HidP_GetUsageValueArray and HidP_SetUsageValueArray. HidP_GetUsageValue/\r |
| 148 | // HidP_SetScaledUsageValue will also work, however, these functions will only\r |
| 149 | // work with the first field of the structure.\r |
| 150 | //\r |
| 151 | \r |
| 152 | //\r |
| 153 | // The link collection tree consists of an array of LINK_COLLECTION_NODES\r |
| 154 | // where the index into this array is the same as the collection number.\r |
| 155 | //\r |
| 156 | // Given a collection A which contains a subcollection B, A is defined to be\r |
| 157 | // the parent B, and B is defined to be the child.\r |
| 158 | //\r |
| 159 | // Given collections A, B, and C where B and C are children of A, and B was\r |
| 160 | // encountered before C in the report descriptor, B is defined as a sibling of\r |
| 161 | // C. (This implies, of course, that if B is a sibling of C, then C is NOT a\r |
| 162 | // sibling of B).\r |
| 163 | //\r |
| 164 | // B is defined as the NextSibling of C if and only if there exists NO\r |
| 165 | // child collection of A, call it D, such that B is a sibling of D and D\r |
| 166 | // is a sibling of C.\r |
| 167 | //\r |
| 168 | // E is defined to be the FirstChild of A if and only if for all children of A,\r |
| 169 | // F, that are not equivalent to E, F is a sibling of E.\r |
| 170 | // (This implies, of course, that the does not exist a child of A, call it G,\r |
| 171 | // where E is a sibling of G). In other words the first sibling is the last\r |
| 172 | // link collection found in the list.\r |
| 173 | //\r |
| 174 | // In other words, if a collection B is defined within the definition of another\r |
| 175 | // collection A, B becomes a child of A. All collections with the same parent\r |
| 176 | // are considered siblings. The FirstChild of the parent collection, A, will be\r |
| 177 | // last collection defined that has A as a parent. The order of sibling pointers\r |
| 178 | // is similarly determined. When a collection B is defined, it becomes the\r |
| 179 | // FirstChild of it's parent collection. The previously defined FirstChild of the\r |
| 180 | // parent collection becomes the NextSibling of the new collection. As new\r |
| 181 | // collections with the same parent are discovered, the chain of sibling is built.\r |
| 182 | //\r |
| 183 | // With that in mind, the following describes conclusively a data structure\r |
| 184 | // that provides direct traversal up, down, and accross the link collection\r |
| 185 | // tree.\r |
| 186 | //\r |
| 187 | //\r |
| 188 | typedef struct _HIDP_LINK_COLLECTION_NODE\r |
| 189 | {\r |
| 190 | USAGE LinkUsage;\r |
| 191 | USAGE LinkUsagePage;\r |
| 192 | USHORT Parent;\r |
| 193 | USHORT NumberOfChildren;\r |
| 194 | USHORT NextSibling;\r |
| 195 | USHORT FirstChild;\r |
| 196 | ULONG CollectionType: 8; // As defined in 6.2.2.6 of HID spec\r |
| 197 | ULONG IsAlias : 1; // This link node is an allias of the next link node.\r |
| 198 | ULONG Reserved: 23;\r |
| 199 | PVOID UserContext; // The user can hang his coat here.\r |
| 200 | } HIDP_LINK_COLLECTION_NODE, *PHIDP_LINK_COLLECTION_NODE;\r |
| 201 | \r |
| 202 | //\r |
| 203 | // When a link collection is described by a delimiter, alias link collection\r |
| 204 | // nodes are created. (One for each usage within the delimiter).\r |
| 205 | // The parser assigns each capability description listed above only one\r |
| 206 | // link collection.\r |
| 207 | //\r |
| 208 | // If a control is defined within a collection defined by\r |
| 209 | // delimited usages, then that control is said to be within multiple link\r |
| 210 | // collections, one for each usage within the open and close delimiter tokens.\r |
| 211 | // Such multiple link collecions are said to be aliases. The first N-1 such\r |
| 212 | // collections, listed in the link collection node array, have their IsAlias\r |
| 213 | // bit set. The last such link collection is the link collection index used\r |
| 214 | // in the capabilities described above.\r |
| 215 | // Clients wishing to set a control in an aliased collection, should walk the\r |
| 216 | // collection array once for each time they see the IsAlias flag set, and use\r |
| 217 | // the last link collection as the index for the below accessor functions.\r |
| 218 | //\r |
| 219 | // NB: if IsAlias is set, then NextSibling should be one more than the current\r |
| 220 | // link collection node index.\r |
| 221 | //\r |
| 222 | \r |
| 223 | typedef PUCHAR PHIDP_REPORT_DESCRIPTOR;\r |
| 224 | typedef struct _HIDP_PREPARSED_DATA * PHIDP_PREPARSED_DATA;\r |
| 225 | \r |
| 226 | typedef struct _HIDP_CAPS\r |
| 227 | {\r |
| 228 | USAGE Usage;\r |
| 229 | USAGE UsagePage;\r |
| 230 | USHORT InputReportByteLength;\r |
| 231 | USHORT OutputReportByteLength;\r |
| 232 | USHORT FeatureReportByteLength;\r |
| 233 | USHORT Reserved[17];\r |
| 234 | \r |
| 235 | USHORT NumberLinkCollectionNodes;\r |
| 236 | \r |
| 237 | USHORT NumberInputButtonCaps;\r |
| 238 | USHORT NumberInputValueCaps;\r |
| 239 | USHORT NumberInputDataIndices;\r |
| 240 | \r |
| 241 | USHORT NumberOutputButtonCaps;\r |
| 242 | USHORT NumberOutputValueCaps;\r |
| 243 | USHORT NumberOutputDataIndices;\r |
| 244 | \r |
| 245 | USHORT NumberFeatureButtonCaps;\r |
| 246 | USHORT NumberFeatureValueCaps;\r |
| 247 | USHORT NumberFeatureDataIndices;\r |
| 248 | } HIDP_CAPS, *PHIDP_CAPS;\r |
| 249 | \r |
| 250 | typedef struct _HIDP_DATA\r |
| 251 | {\r |
| 252 | USHORT DataIndex;\r |
| 253 | USHORT Reserved;\r |
| 254 | union {\r |
| 255 | ULONG RawValue; // for values\r |
| 256 | BOOLEAN On; // for buttons MUST BE TRUE for buttons.\r |
| 257 | };\r |
| 258 | } HIDP_DATA, *PHIDP_DATA;\r |
| 259 | //\r |
| 260 | // The HIDP_DATA structure is used with HidP_GetData and HidP_SetData\r |
| 261 | // functions.\r |
| 262 | //\r |
| 263 | // The parser contiguously assigns every control (button or value) in a hid\r |
| 264 | // device a unique data index from zero to NumberXXXDataIndices -1 , inclusive.\r |
| 265 | // This value is found in the HIDP_BUTTON_CAPS and HIDP_VALUE_CAPS structures.\r |
| 266 | //\r |
| 267 | // Most clients will find the Get/Set Buttons / Value accessor functions\r |
| 268 | // sufficient to their needs, as they will allow the clients to access the\r |
| 269 | // data known to them while ignoring the other controls.\r |
| 270 | //\r |
| 271 | // More complex clients, which actually read the Button / Value Caps, and which\r |
| 272 | // do a value add service to these routines (EG Direct Input), will need to\r |
| 273 | // access all the data in the device without interest in the individual usage\r |
| 274 | // or link collection location. These are the clients that will find\r |
| 275 | // HidP_Data useful.\r |
| 276 | //\r |
| 277 | \r |
| 278 | typedef struct _HIDP_UNKNOWN_TOKEN\r |
| 279 | {\r |
| 280 | UCHAR Token;\r |
| 281 | UCHAR Reserved[3];\r |
| 282 | ULONG BitField;\r |
| 283 | } HIDP_UNKNOWN_TOKEN, *PHIDP_UNKNOWN_TOKEN;\r |
| 284 | \r |
| 285 | typedef struct _HIDP_EXTENDED_ATTRIBUTES\r |
| 286 | {\r |
| 287 | UCHAR NumGlobalUnknowns;\r |
| 288 | UCHAR Reserved [3];\r |
| 289 | PHIDP_UNKNOWN_TOKEN GlobalUnknowns;\r |
| 290 | // ... Additional attributes\r |
| 291 | ULONG Data [1]; // variableLength DO NOT ACCESS THIS FIELD\r |
| 292 | } HIDP_EXTENDED_ATTRIBUTES, *PHIDP_EXTENDED_ATTRIBUTES;\r |
| 293 | \r |
| 294 | NTSTATUS __stdcall\r |
| 295 | HidP_GetCaps (\r |
| 296 | IN PHIDP_PREPARSED_DATA PreparsedData,\r |
| 297 | OUT PHIDP_CAPS Capabilities\r |
| 298 | );\r |
| 299 | /*++\r |
| 300 | Routine Description:\r |
| 301 | Returns a list of capabilities of a given hid device as described by its\r |
| 302 | preparsed data.\r |
| 303 | \r |
| 304 | Arguments:\r |
| 305 | PreparsedData The preparsed data returned from HIDCLASS.\r |
| 306 | Capabilities a HIDP_CAPS structure\r |
| 307 | \r |
| 308 | Return Value:\r |
| 309 |