Changed the parameters and behaviour of the USB_GetDeviceConfigDescriptor() function...

[pub/lufa.git] / LUFA / Drivers / USB / HighLevel / ConfigDescriptor.h

diff --git a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
index a9b0b14..8c4e2c2 100644 (file)
--- a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
+++ b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
@@ -163,6 +163,23 @@
                        uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine);\r
                        \r
                /* Enums: */\r
+                       enum USB_Host_GetConfigDescriptor_ErrorCodes_t\r
+                       {\r
+                               HOST_GETCONFIG_Successful       = 0, /**< No error occurred while retrieving the configuration descriptor */\r
+                               HOST_GETCONFIG_DeviceDisconnect = 1, /**< The attached device was disconnected while retrieving the configuration\r
+                                                                       * descriptor\r
+                                                                       */\r
+                               HOST_GETCONFIG_PipeError        = 2, /**< An error occurred in the pipe while sending the request */\r
+                               HOST_GETCONFIG_SetupStalled     = 3, /**< The attached device stalled the request to retrieve the configuration\r
+                                                                       * descriptor\r
+                                                                       */\r
+                               HOST_GETCONFIG_SoftwareTimeOut  = 4, /**< The request or data transfer timed out */\r
+                               HOST_GETCONFIG_BuffOverflow     = 5, /**< The device's configuration descriptor is too large to fit into the allocated\r
+                                                                       * buffer\r
+                                                                       */\r
+                               HOST_GETCONFIG_InvalidData      = 6, /**< The device returned invalid configuration descriptor data */\r
+                       };\r
+               \r
                        /** Enum for return values of a descriptor comparator function. */\r
                        enum DSearch_Return_ErrorCodes_t\r
                        {\r
@@ -181,22 +198,19 @@
                        };\r
        \r
                /* Function Prototypes: */\r
-                       /** Retrieves the configuration descriptor data or size from an attached device via a standard request.\r
+                       /** Retrieves the configuration descriptor data from an attached device via a standard request into a buffer,\r
+                        *  including validity and size checking to prevent a buffer overflow.\r
                         *\r
                         *  \param[in] ConfigNumber  Device configuration descriptor number to fetch from the device (usually set to 1 for\r
                         *                           single configuration devices)\r
+                        *  \param[in,out] ConfigSizePtr  Pointer to a uint16_t for storing the retrieved configuration descriptor size\r
+                        *  \param[out] BufferPtr  Pointer to the buffer for storing the configuration descriptor data.\r
+                        *  \param[out] BufferSize  Size of the allocated buffer where the configuration descriptor is to be stored\r
                         *\r
-                        *  \param[in,out] ConfigSizePtr  Pointer to a uint16_t for either storing or retrieving the configuration\r
-                        *                                descriptor size\r
-                        *\r
-                        *  \param[out] BufferPtr  Pointer to the buffer for storing the configuration descriptor data. If this is\r
-                        *                         NULL, the size of the configuration descriptor will be retrieved instead and\r
-                        *                         placed in the variable pointed to by ConfigSizePtr. If this is non-NULL, the number\r
-                        *                         of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded\r
-                        *                         into the buffer\r
+                        *  \return A value from the \ref USB_Host_GetConfigDescriptor_ErrorCodes_t enum\r
                         */\r
-                       uint8_t USB_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr)\r
-                                                             ATTR_NON_NULL_PTR_ARG(2);\r
+                       uint8_t USB_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr,\r
+                                                             uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(2, 3);\r
 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.\r
                         *  The bytes remaining value is automatically decremented.\r