hid.pas

human interface devices.zip 一套组件

//     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

function HidP_SetData(ReportType: THIDPReportType; DataList: PHIDPData;
  var DataLength: ULONG; PreparsedData: PHIDPPreparsedData;
  var Report; ReportLength: ULONG): NTSTATUS; stdcall;

// 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.

function HidP_MaxDataListLength(ReportType: THIDPReportType;
  PreparsedData: PHIDPPreparsedData): ULONG; stdcall;

// 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

function HidP_GetUsages(ReportType: THIDPReportType; UsagePage: TUsage;
  LinkCollection: Word; UsageList: PUsage; var UsageLength: ULONG;
  PreparsedData: PHIDPPreparsedData; var Report;
  ReportLength: ULONG): NTSTATUS; stdcall;

function HidP_GetButtons(ReportType: THIDPReportType; UsagePage: TUsage;
  LinkCollection: Word; UsageList: PUsage; var UsageLength: ULONG;
  PreparsedData: PHIDPPreparsedData; var Report;
  ReportLength: ULONG): NTSTATUS; stdcall;

// Routine Description:
//     This function returns the binary values (buttons) in a HID report.
//     Given a report packet of correct length, it searches the report packet
//     for all buttons and returns the UsagePage and Usage for each of the buttons
//     it finds.
// 
// Parameters:
//     ReportType  One of HidP_Input, HidP_Output or HidP_Feature.
//
//     LinkCollection  An optional value which can limit which usages are returned
//                     in the ButtonList to those usages that exist in a specific
//                     LinkCollection.  A non-zero value indicates the index into
//                     the HIDP_LINK_COLLECITON_NODE list returned by
//                     HidP_GetLinkCollectionNodes of the link collection the
//                     usage should belong to.  A value of 0 indicates this
//                     should value be ignored.
// 
//     ButtonList  An array of USAGE_AND_PAGE structures describing all the
//                 buttons currently ``down'' in the device.
// 
//     UsageLength The length of the given array in terms of elements.
//                 On input, this value describes the length of the list.  On
//                 output, HidP_GetUsagesEx sets this value to the number of
//                 usages that were found.  Use HidP_MaxUsageListLength to
//                 determine the maximum length needed to return all the usages
//                 that a given report packet may contain.
// 
//     PreparsedData Preparsed data returned by HIDCLASS
// 
//     Report       The report packet.
// 
//     ReportLength Length (in bytes) of the given report packet.
// 
// 
// Return Value
//     HidP_GetUsagesEx returns the following error codes:
// 
// - HIDP_STATUS_SUCCESS                -- upon successfully retrieving all the
//                                         usages from the report packet
// - HIDP_STATUS_INVALID_REPORT_TYPE    -- if ReportType is not valid.
// - HIDP_STATUS_INVALID_PREPARSED_DATA -- if PreparsedData is not valid
// - HIDP_STATUS_INVALID_REPORT_LENGTH  -- the length of the report packet is not
//                                         equal to the length specified in
//                                         the HIDP_CAPS structure for the given
//                                         ReportType
// - HIDP_STATUS_REPORT_DOES_NOT_EXIST  -- if there are no reports on this device
//                                         for the given ReportType
// - HIDP_STATUS_BUFFER_TOO_SMALL       -- if ButtonList is not big enough to
//                                         hold all the usages found in the report
//                                         packet.  If this is returned, the buffer
//                                         will contain UsageLength number of
//                                         usages.  Use HidP_MaxUsageListLength to
//                                         find the maximum length needed
// - HIDP_STATUS_INCOMPATIBLE_REPORT_ID -- if no usages were found but usages
//                                         that match the specified LinkCollection
//                                         exist in report with a different report
//                                         ID.
// - HIDP_STATUS_USAGE_NOT_FOUND        -- if there are no usages in any reports that
//                                         match the LinkCollection parameter

function HidP_GetUsagesEx(ReportType: THIDPReportType; LinkCollection: Word;
  UsageList: PUsageAndPage; var UsageLength: ULONG;
  PreparsedData: PHIDPPreparsedData; var Report;
  ReportLength: ULONG): NTSTATUS; stdcall;

function HidP_GetButtonsEx(ReportType: THIDPReportType; LinkCollection: Word;
  UsageList: PUsageAndPage; var UsageLength: ULONG;
  PreparsedData: PHIDPPreparsedData; var Report;
  ReportLength: ULONG): NTSTATUS; stdcall;

// 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抯, 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