Remove output files from the incomplete AudioInputHost demo, and improve the logic...

[pub/lufa.git] / Demos / Host / Incomplete / AudioInputHost / ConfigDescriptor.c

diff --git a/Demos/Host/Incomplete/AudioInputHost/ConfigDescriptor.c b/Demos/Host/Incomplete/AudioInputHost/ConfigDescriptor.c
index d0ca91a..5dcd602 100644 (file)
--- a/Demos/Host/Incomplete/AudioInputHost/ConfigDescriptor.c
+++ b/Demos/Host/Incomplete/AudioInputHost/ConfigDescriptor.c
@@ -37,10 +37,24 @@
 \r
 #include "ConfigDescriptor.h"\r
 \r
+/** Index of the currently used Audio Streaming Interface within the device. */\r
 uint8_t StreamingInterfaceIndex      = 0;\r
+\r
+/** Alternative Setting of the currently used Audio Streaming Interface within the device. */\r
 uint8_t StreamingInterfaceAltSetting = 0;\r
+\r
+/** Address of the streaming audio endpoint currently in use within the device. */\r
 uint8_t StreamingEndpointAddress     = 0;\r
 \r
+\r
+/** Reads and processes an attached device's descriptors, to determine compatibility and pipe configurations. This\r
+ *  routine will read in the entire configuration descriptor, and configure the hosts pipes to correctly communicate\r
+ *  with compatible devices.\r
+ *\r
+ *  This routine searches for a Streaming Audio interface descriptor containing a valid Isochronous audio endpoint.\r
+ *\r
+ *  \return An error code from the \ref RNDISHost_GetConfigDescriptorDataCodes_t enum.\r
+ */\r
 uint8_t ProcessConfigurationDescriptor(void)\r
 {\r
        uint8_t  ConfigDescriptorData[512];\r
@@ -66,12 +80,17 @@ uint8_t ProcessConfigurationDescriptor(void)
 \r
        while (!(DataINEndpoint))\r
        {\r
+               /* See if we've found a likely compatible interface, and if there is an endpoint within that interface */\r
                if (!(AudioControlInterface) ||\r
                    USB_GetNextDescriptorComp(&CurrConfigBytesRem, &CurrConfigLocation,\r
                                              DComp_NextAudioInterfaceDataEndpoint) != DESCRIPTOR_SEARCH_COMP_Found)\r
                {\r
-                       if (!(AudioControlInterface))\r
+                       /* Check if we haven't found an Audio Control interface yet, or if we have run out of related Audio Streaming interfaces */\r
+                       if (!(AudioControlInterface) ||\r
+                           USB_GetNextDescriptorComp(&CurrConfigBytesRem, &CurrConfigLocation,\r
+                                                     DComp_NextAudioStreamInterface) != DESCRIPTOR_SEARCH_COMP_Found)\r
                        {\r
+                               /* Find a new Audio Control interface if the current one doesn't contain a compatible streaming interface */\r
                                if (USB_GetNextDescriptorComp(&CurrConfigBytesRem, &CurrConfigLocation,\r
                                                                                          DComp_NextAudioControlInterface) != DESCRIPTOR_SEARCH_COMP_Found)\r
                                {\r
@@ -81,20 +100,14 @@ uint8_t ProcessConfigurationDescriptor(void)
 \r
                                /* Save the interface in case we need to refer back to it later */\r
                                AudioControlInterface = DESCRIPTOR_PCAST(CurrConfigLocation, USB_Descriptor_Interface_t);                       \r
-                       }\r
-               \r
-                       if (USB_GetNextDescriptorComp(&CurrConfigBytesRem, &CurrConfigLocation,\r
-                                                                                 DComp_NextAudioStreamInterface) != DESCRIPTOR_SEARCH_COMP_Found)\r
-                       {\r
+\r
+                               /* Find the next Audio Streaming interface within that Audio Control interface */\r
                                if (USB_GetNextDescriptorComp(&CurrConfigBytesRem, &CurrConfigLocation,\r
-                                                                                         DComp_NextAudioControlInterface) != DESCRIPTOR_SEARCH_COMP_Found)\r
+                                                                                 DComp_NextAudioStreamInterface) != DESCRIPTOR_SEARCH_COMP_Found)\r
                                {\r
                                        /* Descriptor not found, error out */\r
                                        return NoCompatibleInterfaceFound;\r
                                }\r
-\r
-                               /* Save the interface in case we need to refer back to it later */\r
-                               AudioControlInterface = DESCRIPTOR_PCAST(CurrConfigLocation, USB_Descriptor_Interface_t);\r
                        }\r
 \r
                        /* Save the interface in case we need to refer back to it later */\r
@@ -124,6 +137,14 @@ uint8_t ProcessConfigurationDescriptor(void)
        return SuccessfulConfigRead;\r
 }\r
 \r
+/** Descriptor comparator function. This comparator function is can be called while processing an attached USB device's\r
+ *  configuration descriptor, to search for a specific sub descriptor. It can also be used to abort the configuration\r
+ *  descriptor processing if an incompatible descriptor configuration is found.\r
+ *\r
+ *  This comparator searches for the next Interface descriptor of the correct Audio Control Class, Subclass and Protocol values.\r
+ *\r
+ *  \return A value from the DSEARCH_Return_ErrorCodes_t enum\r
+ */\r
 uint8_t DComp_NextAudioControlInterface(void* CurrentDescriptor)\r
 {\r
        USB_Descriptor_Header_t* Header = DESCRIPTOR_PCAST(CurrentDescriptor, USB_Descriptor_Header_t);\r
@@ -143,6 +164,14 @@ uint8_t DComp_NextAudioControlInterface(void* CurrentDescriptor)
        return DESCRIPTOR_SEARCH_NotFound;\r
 }\r
 \r
+/** Descriptor comparator function. This comparator function is can be called while processing an attached USB device's\r
+ *  configuration descriptor, to search for a specific sub descriptor. It can also be used to abort the configuration\r
+ *  descriptor processing if an incompatible descriptor configuration is found.\r
+ *\r
+ *  This comparator searches for the next Interface descriptor of the correct Audio Streaming Class, Subclass and Protocol values.\r
+ *\r
+ *  \return A value from the DSEARCH_Return_ErrorCodes_t enum\r
+ */\r
 uint8_t DComp_NextAudioStreamInterface(void* CurrentDescriptor)\r
 {\r
        USB_Descriptor_Header_t* Header = DESCRIPTOR_PCAST(CurrentDescriptor, USB_Descriptor_Header_t);\r
@@ -162,6 +191,15 @@ uint8_t DComp_NextAudioStreamInterface(void* CurrentDescriptor)
        return DESCRIPTOR_SEARCH_NotFound;\r
 }\r
 \r
+/** Descriptor comparator function. This comparator function is can be called while processing an attached USB device's\r
+ *  configuration descriptor, to search for a specific sub descriptor. It can also be used to abort the configuration\r
+ *  descriptor processing if an incompatible descriptor configuration is found.\r
+ *\r
+ *  This comparator searches for the next Isochronous Endpoint descriptor within the current interface, aborting the\r
+ *  search if another interface descriptor is found before the next endpoint.\r
+ *\r
+ *  \return A value from the DSEARCH_Return_ErrorCodes_t enum\r
+ */\r
 uint8_t DComp_NextAudioInterfaceDataEndpoint(void* CurrentDescriptor)\r
 {\r
        USB_Descriptor_Header_t* Header = DESCRIPTOR_PCAST(CurrentDescriptor, USB_Descriptor_Header_t);\r
@@ -180,4 +218,3 @@ uint8_t DComp_NextAudioInterfaceDataEndpoint(void* CurrentDescriptor)
 \r
        return DESCRIPTOR_SEARCH_NotFound;\r
 }\r
-\r