X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/3d4d8e7f628f9dc9981242f69b097333faa9940d..18d91ece3b178a04d295518517b2aca5266bb078:/LUFA/Drivers/USB/Class/Common/HIDParser.h diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.h b/LUFA/Drivers/USB/Class/Common/HIDParser.h index cd32093ca..39c5817da 100644 --- a/LUFA/Drivers/USB/Class/Common/HIDParser.h +++ b/LUFA/Drivers/USB/Class/Common/HIDParser.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2011. + Copyright (C) Dean Camera, 2012. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2012 Dean Camera (dean [at] fourwalledcubicle [dot] com) Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted @@ -38,6 +38,7 @@ /** \ingroup Group_USB * \defgroup Group_HIDParser HID Report Parser + * \brief USB Human Interface Device (HID) Class report descriptor parser. * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module: @@ -53,11 +54,11 @@ * of data exchanged between a HID device and a host, including both the physical encoding of each item * (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" - * as well as other information about each item such as the usages, data range, physical location and other - * characterstics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it - * is not forced to comply with a given report layout or featureset. + * characteristics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it + * is not forced to comply with a given report layout or feature-set. * * This module also contains routines for the processing of data in an actual HID report, using the parsed report - * descritor data as a guide for the encoding. + * descriptor data as a guide for the encoding. * * @{ */ @@ -66,13 +67,10 @@ #define __HIDPARSER_H__ /* Includes: */ - #include - #include + #include "../../../../Common/Common.h" #include "HIDReportData.h" - #include "../Common/HID.h" - - #include "../../../../Common/Common.h" + #include "HIDClassCommon.h" /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) @@ -224,7 +222,7 @@ { uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */ uint8_t ItemType; /**< Report item type, a value in \ref HID_ReportItemTypes_t. */ - uint16_t ItemFlags; /**< Item data flags, a mask of HID_IOF_* constants. */ + uint16_t ItemFlags; /**< Item data flags, a mask of \c HID_IOF_* constants. */ uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */ HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */ @@ -286,8 +284,8 @@ /** Extracts the given report item's value out of the given HID report and places it into the Value * member of the report item's \ref HID_ReportItem_t structure. * - * When called on a report with an item that exists in that report, this copies the report item's Value - * to it's PreviousValue element for easy checking to see if an item's value has changed before processing + * When called on a report with an item that exists in that report, this copies the report item's \c Value + * to its \c PreviousValue element for easy checking to see if an item's value has changed before processing * a report. If the given item does not exist in the report, the function does not modify the report item's * data. * @@ -297,14 +295,14 @@ * \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise. */ bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, - HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); + HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1); - /** Retrieves the given report item's value out of the Value member of the report item's + /** Retrieves the given report item's value out of the \c Value member of the report item's * \ref HID_ReportItem_t structure and places it into the correct position in the HID report * buffer. The report buffer is assumed to have the appropriate bits cleared before calling * this function (i.e., the buffer should be explicitly cleared before report values are added). * - * When called, this copies the report item's Value element to it's PreviousValue element for easy + * When called, this copies the report item's \c Value element to its \c PreviousValue element for easy * checking to see if an item's value has changed before sending a report. * * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item. @@ -313,16 +311,16 @@ * \param[in] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array. */ void USB_SetHIDReportItemInfo(uint8_t* ReportData, - HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); + HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1); - /** Retrieves the size of a given HID report in bytes from it's Report ID. + /** Retrieves the size of a given HID report in bytes from its Report ID. * * \param[in] ParserData Pointer to a \ref HID_ReportInfo_t instance containing the parser output. - * \param[in] ReportID Report ID of the report whose size is to be retrieved. - * \param[in] ReportType Type of the report whose size is to be determined, a valued from the + * \param[in] ReportID Report ID of the report whose size is to be determined. + * \param[in] ReportType Type of the report whose size is to be determined, a value from the * \ref HID_ReportItemTypes_t enum. * - * \return Size of the report in bytes, or 0 if the report does not exist. + * \return Size of the report in bytes, or \c 0 if the report does not exist. */ uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, const uint8_t ReportID, @@ -333,6 +331,10 @@ * \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that * no RAM is wasted storing the attributes for report items which will never be referenced by the application. * + * Report item pointers passed to this callback function may be cached by the user application for later use + * when processing report items. This provides faster report processing in the user application than would + * a search of the entire parsed report item table for each received or sent report. + * * \param[in] CurrentItem Pointer to the current report item for user checking. * * \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if