/*++ Copyright (c) 1996 Microsoft Corporation Module Name: HIDPI.H Abstract: Public Interface to the HID parsing library. Environment: Kernel & user mode Revision History: 09-29-95 : created by Kenneth D. Ray --*/ #ifndef __HIDPI_H__ #define __HIDPI_H__ #include // Please include "hidsdi.h" to use the user space (dll / parser) // Please include "hidpddi.h" to use the kernel space parser 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; 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. // // // 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. // // 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, exclusive. // This value is found in HidP_ButtonCaps and HIDP_VALUE_CAPS and // HIDP_BUTTON_CAPS structures. // // Most clients will find the Get/Set Buttons / Value accessor functions // sufficient to their needs, as it will allow them 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. // 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 node 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. ButtonCaps A _HIDP_BUTTON_CAPS array contain information about all the binary values in the given report. This buffer is provided by the caller. ButtonLength Starts off as the length of the caller provided buffer, and ends up the length of the button values. Both are in units array elemenst, not byte length. The number of button caps returned can be found in the HIDP_CAPS structure. PreparsedData The preparsed data returned from Hidclass. Return Value HidP_GetButtonCaps returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_BUFFER_TOO_SMALL --*/ 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. ValueCaps A _HIDP_Value_CAPS array contain information about all the binary values in the given report. This buffer is provided by the caller. ValueLength Starts off as the length of the caller provided buffer, and ends up the length of the button values. Both are in units array elemenst, not byte length. The number returned can be found in the HIDP_CAPS structure. PreparsedData The preparsed data returned from Hidclass. Return Value HidP_GetValueCaps returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_BUFFER_TOO_SMALL (all given entries however have been filled in) --*/ 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: For obvious reasons HidP_SetData and HidP_GetData will not access UsageValueArrays. Parameters: Return Value HidP_SetData returns the following error codes. Upon an error the report packet is in an unknown state. · HIDP_STATUS_SUCCESS upon successful insertion of usages into the report packet. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if there exists a byte in the usage list for which there is no corresponding control. · HIDP_STATUS_INVALID_REPORT_LENGTH the length of the report packet is not the size expected. · 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 user needs to split his request to set usages up. --*/ 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: Return Value --*/ 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 or HidP_Feature. UsagePage All of the usages in the usage array, for which HidP_GetUsage will search in the report, refer to this same usage page. PreparsedData the preparsed data recevied from the HidClass device object. Return Value: The length of the usage list array required for the HidpGetUsage function call. If UsagePage is set to zero, then MaxUsageListLength returns the number of --*/ #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 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 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 byte array (usageList). HidP_SetUsage 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. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage All of the usages in the usage array, which HidP_SetUsage will set in the report, refer to this same usage page. If the client wishes to set usages in a packet for multiple usage pages then that client needs to make subsequent SetUsages calls. UsageList A byte array containing the usages that HidP_SetUsage will set in the report packet. UsageLength The length of the given byte array. The parser sets this value to the position in the usage array at where it stoped processing. In the successful case UsageList 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. However, in the event of an error condition, the report packet itself is in an unknown state. PreparsedData the preparsed data recevied from the HidClass device object. Report The report packet. ReportLength Length of the given report packet. Return Value HidP_SetUsage returns the following error codes. Upon an error the report packet is in an unknown state. · HIDP_STATUS_SUCCESS upon successful insertion of usages into the report packet. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if there exists a byte in the usage list for which there is no corresponding control. · HIDP_STATUS_INVALID_REPORT_LENGTH the length of the report packet is not the size expected. · 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 user needs to split his request to set usages up. --*/ #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 sets 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 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 byte array (usageList). HidP_SetUsage 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. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage All of the usages in the usage array, which HidP_SetUsage will set in the report, refer to this same usage page. If the client wishes to set usages in a packet for multiple usage pages then that client needs to make subsequent SetUsages calls. UsageList A byte array containing the usages that HidP_SetUsage will set in the report packet. UsageLength The length of the given byte array. The parser sets this value to the position in the usage array at where it stoped processing. In the successful case UsageList 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. However, in the event of an error condition, the report packet itself is in an unknown state. PreparsedData the preparsed data recevied from the HidClass device object. Report The report packet. ReportLength Length of the given report packet. Return Value HidP_SetUsage returns the following error codes. Upon an error the report packet is in an unknown state. · HIDP_STATUS_SUCCESS upon successful insertion of usages into the report packet. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if there exists a byte in the usage list for which there is no corresponding control. · HIDP_STATUS_INVALID_REPORT_LENGTH the length of the report packet is not the size expected. · 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 user needs to split his request to set usages up. --*/ #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) 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_Output or HidP_Feature. UsagePage All of the usages in the usage array, which HidP_SetUsage 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 subsequent getUsages calls. UsageList A byte array containing the usages that HidP_GetUsage found in the report packet. UsageLength The length of the given byte array. This value initially describes the length of the usage list, but HidP_GetUsage sets this value to the length of found usages. Use HidP_MaxUsageListLength to determine the maximum length list of usages that a given report packet may contain. PreparsedData the preparsed data recevied from the HidClass device object. Report The report packet. ReportLength Length of the given report packet. Return Value HidpGetUsage returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if no control for this device matches the given usagePage. · HIDP_STATUS_BUFFER_TOO_SMALL if the given usageList is not long enough to hold the usages found in the given report packet. HidP_MaxUsageListLength should be used to prevent this error. · HIDP_STATUS_INVALID_PREPARSED_DATA if the given preparsed data is invalid · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected. --*/ #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 each usage for the given usage page and returns them in the usage list. Parameters: ReportType One of HidP_Output or HidP_Feature. 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. This value initially describes the length of the usage list, but HidP_GetUsage sets this value to the length of found usages. Use HidP_MaxUsageListLength to determine the maximum length list of usages that a given report packet may contain. PreparsedData the preparsed data recevied from the HidClass device object. Report The report packet. ReportLength Length of the given report packet. Return Value HidpGetUsage returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if no button controls are found for this device. · HIDP_STATUS_BUFFER_TOO_SMALL if the given usageList is not long enough to hold the usages found in the given report packet. HidP_MaxUsageListLength should be used to prevent this error. · HIDP_STATUS_INVALID_PREPARSED_DATA if the given preparsed data is invalid · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected. --*/ #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 length of usages that a HidpGetUsage could return for the given HID Report and Usage Page. Parameters: ReportType One of HidP_Input or HidP_Feature. UsagePage All of the usages in the usage array, for which HidP_GetUsage will search in the report, refer to this same usage page. PreparsedData the preparsed data recevied from the HidClass device object. Return Value: The length of the usage list array required for the HidpGetUsage function call. If UsagePage is set to zero, then MaxUsageListLength returns the number of --*/ 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: HidpSetUsageValue inserts the given value into the given 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 there are two channel in the report packet with the same usage and UsagePage, then they can be destinguished with the optional LinkCollection Field. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_SetUsageValue will set. UsageValue The value. This value must be within the logical range or null value specified by the Report Descriptor. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. Return Value: HidpSetUsageValue returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if the given usage does not correspond to a control on the device, or if it refers to a button style control. · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected given the HIDP_CHANNELS structure. --*/ 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: HidpSetUsageValue inserts the given value into the given 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 there are two channel in the report packet with the same usage and UsagePage, then they can be destinguished with the optional LinkCollection Field. ScaledUsageValue converts from the signed physical value given as UsageValue to the logical value placed in the report. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_SetUsageValue will set. UsageValue The value. This value must be within the logical range or null value specified by the Report Descriptor. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. Return Value: HidpSetUsageValue returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if the given usage does not correspond to a control on the device, or if it refers to a button style control. · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected given the HIDP_CHANNELS structure. · HIDP_STATUS_VALUE_OUT_OF_RANGE The physical value given was out of range, but this field does not accept null values. In this case the field remains unchanged. · HIDP_STATUS_BAD_LOG_PHY_VALUES · HIDP_STATUS_NULL A null value was written into the field, because the physical value given was out of range and this field supports null values. The value written was outside the range of LogicalMin and LogicalMax and is specifically set to the most negative value. --*/ 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: The last usage in the list of usages describing a main item must be repeated if there are less usages 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 refect the numer 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. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_SetUsageValueArray will set. UsageValue A pointer to an array characters where the value will be placed. The number of BITS required is found by multiplying the BitSize and ReportCount fields of the given 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). UsageValueByteLength the length of the given UsageValue buffer. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. Return Value: Same as others HIDP_STATUS_NOT_VALUE_ARRAY this is not a value array control use instead HidP_SetUsageValue. --*/ 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 given value from the given HID Report Packet, for the specified usage. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_GetUsageValue will retreive. UsageValue The value. This value must be within the logical range or null value specified by the Report Descriptor. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. Return Value: HidpSetUsageValue returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if the given usage does not correspond to a control on the device, or if it refers to a button style control. · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected given the HIDP_CHANNELS structure. --*/ 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 the given value from the given HID Report Packet, for the specified usage. This function assums 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 requested is of fewer bytes than 32, then HidP_GetScaledUsageValue will sign extend those bits to 32. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_GetUsageValue will retreive. UsageValue The value. This value must be within the logical range or null value specified by the Report Descriptor. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. Return Value: HidpSetUsageValue returns the following error codes: · HIDP_STATUS_SUCCESS. · HIDP_STATUS_INVALID_REPORT_TYPE if reportType is not valid. · HIDP_STATUS_USAGE_NOT_FOUND if the given usage does not correspond to a control on the device, or if it refers to a button style control. · HIDP_STATUS_INVALID_REPORT_LENGTH if the length of the report packet is not the size expected given the HIDP_CHANNELS structure. · HIDP_STATUS_VALUE_OUT_OF_RANGE · HIDP_STATUS_BAD_LOG_PHY_VALUES · HIDP_STATUS_NULL --*/ 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: The last usage in the list of usages describing a main item must be repeated if there are less usages 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 refect the numer of fields to which that usage refers. HidP_GetUsageValueArray retrieved the raw bits for that usage which spans more than one field in a report. Parameters: ReportType One of HidP_Output or HidP_Feature. UsagePage The usage page to which the given usage refers. LinkCollection (Optional) If there are more than one channel with the given usage and usage page, then the client may used this field to distinguish them. A LinkValue of zero is ingnored. The first channel that matches the given usage page, usage page, and Link number is the one affected. Usage The usage whose value HidP_GetUsageValueArray will retreive. UsageValue A pointer to an array characters where the value will be placed. The number of BITS required is found by multiplying the BitSize and ReportCount fields of the given 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). UsageValueByteLength the length of the given UsageValue buffer. PreparsedData The data retreived from the HID device Report The report packet. ReportLength Length of the given report packet. --*/ NTSTATUS __stdcall HidP_UsageListDifference ( IN PUSAGE PreviousUsageList, IN PUSAGE CurrentUsageList, OUT PUSAGE BreakUsageList, OUT PUSAGE MakeUsageList, IN ULONG UsageListLength ); /*++ Routine Description: Given two list of usages (as might be returned from HidP_GetUsages), determine the difference; that is, return a list of usages that are in the current list but not in the previous list (NewUsageList), as well as a list of usages that are in the previous list but not the current list (OldUsageList). Parameters: PreviousUsageList The list of usages before. CurrentUsageList The list of usages now. BreakUsageList Previous - Current. MakeUsageList Current - Previous. All usage lists have a maximum of UsageListLength bytes. Any zero found in the list indicates early termination of the list. Any characters found after the first zero will be ignored. --*/ // // 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_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 // // BUGBUG 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_I8242_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)) #include #endif