X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6a10d6b465be27db090d760dc0fbe722c94e4344..d0806c817cbf0c1b5c5362d1577eac6075c94dfc:/LUFA/Drivers/USB/Class/HIDParser.h diff --git a/LUFA/Drivers/USB/Class/HIDParser.h b/LUFA/Drivers/USB/Class/HIDParser.h index 314d08072..49e57c295 100644 --- a/LUFA/Drivers/USB/Class/HIDParser.h +++ b/LUFA/Drivers/USB/Class/HIDParser.h @@ -33,7 +33,14 @@ * USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy * parsing of the complex HID report descriptor, which describes the data that the device transmits to the host. * - * The processed report is presented back to the user application as a flat structure containing each report + */ + +/** \ingroup Group_USB + * @defgroup Group_HIDParser HID Report Parser + * + * Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors. + * + * The processed HID report is presented back to the user application as a flat structure containing each report * item's IN, OUT and FEATURE (if desired) items along with each item's attributes. * * This library portion also allows for easy setting and retrieval of data from a HID report, including devices @@ -43,6 +50,8 @@ * to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or * HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D * switch. + * + * @{ */ #ifndef __HIDPARSER_H__ @@ -105,7 +114,7 @@ /* Public Interface - May be used in end-application: */ /* Enums: */ - /** Enum for indicating what type of report item an entry in a HID_ReportInfo_t ReportItem array is */ + /** Enum for indicating what type of report item an entry in a \ref HID_ReportInfo_t ReportItem array is */ enum HID_ReportItemTypes_t { REPORT_ITEM_TYPE_In = 0, /**< Indicates that the item is an IN report type. */ @@ -113,16 +122,16 @@ REPORT_ITEM_TYPE_Feature = 2, /**< Indicates that the item is a FEATURE report type. */ }; - /** Enum for the possible error codes in the return value of the ProcessHIDReport() function */ + /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */ enum HID_Parse_ErrorCodes_t { HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */ - HID_PARSE_HIDStackOverflow = 1, /**< More than HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ + HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */ HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */ - HID_PARSE_InsufficientReportItems = 3, /**< More than HID_MAX_REPORTITEMS report items in the report. */ + HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */ HID_PARSE_UnexpectedEndCollection = 4, /**< END COLLECTION found without matching COLLECTION item. */ - HID_PARSE_InsufficientCollectionPaths = 5, /**< More than HID_MAX_COLLECTIONS collections in the report. */ - HID_PARSE_UsageStackOverflow = 6, /**< More than HID_USAGE_STACK_DEPTH usages listed in a row. */ + HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */ + HID_PARSE_UsageStackOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */ }; /* Type Defines: */ @@ -153,7 +162,7 @@ */ typedef struct CollectionPath { - uint8_t Type; /**< Collection type (for example "Generic Desktop"). */ + uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */ HID_Usage_t Usage; /**< Collection usage. */ struct CollectionPath* Parent; /**< Reference to parent collection, or NULL if root collection. */ } HID_CollectionPath_t; @@ -198,40 +207,40 @@ /* Function Prototypes: */ /** Function to process a given HID report returned from an attached device, and store it into a given - * HID_ReportInfo_t structure. + * \ref HID_ReportInfo_t structure. * * \param ReportData Buffer containing the device's HID report table * \param ReportSize Size in bytes of the HID report table - * \param ParserData Pointer to a HID_ReportInfo_t instance for the parser output + * \param ParserData Pointer to a \ref HID_ReportInfo_t instance for the parser output * - * \return A value in the HID_Parse_ErrorCodes_t enum + * \return A value in the \ref HID_Parse_ErrorCodes_t enum */ - uint8_t ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData) - ATTR_NON_NULL_PTR_ARG(1, 3); + uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData) + ATTR_NON_NULL_PTR_ARG(1, 3); /** 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 HID_ReportItem_t structure. + * member of the report item's \ref HID_ReportItem_t structure. * * \param ReportData Buffer containing an IN or FEATURE report from an attached device - * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array + * \param ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array * * \returns Boolean true if the item to retrieve was located in the given report, false otherwise */ - bool GetReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem) - ATTR_NON_NULL_PTR_ARG(1, 2); + bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem) + ATTR_NON_NULL_PTR_ARG(1, 2); - /** Retreives the given report item's value out of the Value member of the report item's - * HID_ReportItem_t structure and places it into the correct position in the HID report + /** Retrieves the given report item's value out of the 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). * * If the device has multiple HID reports, the report ID is set to the report ID of the given item. * * \param ReportData Buffer holding the current OUT report data - * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array + * \param ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array */ - void SetReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem) - ATTR_NON_NULL_PTR_ARG(1, 2); + void USB_SetHIDReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem) + ATTR_NON_NULL_PTR_ARG(1, 2); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -250,3 +259,5 @@ #endif #endif + +/** @} */