2.3.4.8 USB_DEVICE_AUDIO_EVENT Enumeration

C

typedef enum {
  USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE,
  USB_DEVICE_AUDIO_EVENT_READ_COMPLETE,
  USB_DEVICE_AUDIO_EVENT_STATUS_SEND_COMPLETE,
  USB_DEVICE_AUDIO_EVENT_INTERFACE_SETTING_CHANGED,
  USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_RECEIVED,
  USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_SENT,
  USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_UNKNOWN,
  USB_DEVICE_AUDIO_EVENT_CONTROL_SET_CUR,
  USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MIN,
  USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MAX,
  USB_DEVICE_AUDIO_EVENT_CONTROL_SET_RES,
  USB_DEVICE_AUDIO_EVENT_ENTITY_SET_MEM,
  USB_DEVICE_AUDIO_EVENT_CONTROL_GET_CUR,
  USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MIN,
  USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MAX,
  USB_DEVICE_AUDIO_EVENT_CONTROL_GET_RES,
  USB_DEVICE_AUDIO_EVENT_ENTITY_GET_MEM,
  USB_DEVICE_AUDIO_EVENT_ENTITY_GET_STAT
} USB_DEVICE_AUDIO_EVENT;

Description

USB Device Audio Function Driver Events

These events are specific to a USB Device Audio Function Driver instance. An event may have some data associated with it. This is provided to the event handling function. Each event description contains details about this event data (pData) and other parameters passed along with the event, to the event handler.

Events associated with the Audio Function Driver Specific Control Transfers require application response. The application should respond to these events by using the USB_DEVICE_ControlReceive, USB_DEVICE_ControlSend and USB_DEVICE_ControlStatus functions.

Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_ERROR will stall the control transfer request. The application would do this if the control transfer request is not supported. Calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK will complete the status stage of the control transfer request. The application would do this if the control transfer request is supported.

The following code shows an example of a possible event handling scheme.

// This code example shows all USB Audio Function Driver possible events and
// a possible scheme for handling these events. In this case event responses
// are not deferred.

void APP_USBDeviceAudioEventHandler
(
    USB_DEVICE_AUDIO_INDEX instanceIndex ,
    USB_DEVICE_AUDIO_EVENT event ,
    void * pData,
    uintptr_t context
)
{
    switch (event)
    {
        case USB_DEVICE_AUDIO_EVENT_READ_COMPLETE:

            // This event indicates that a Audio Read Transfer request
            // has completed. pData should be interpreted as a 
            // USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE pointer type.
            // This contains the transfer handle of the read transfer
            // that completed and amount of data that was read.

            break;
        
        case USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE:

            // This event indicates that a Audio Write Transfer request
            // has completed. pData should be interpreted as a 
            // USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE pointer type.
            // This contains the transfer handle of the write transfer
            // that completed and amount of data that was written.

            break;

        case USB_DEVICE_AUDIO_EVENT_STATUS_SEND_COMPLETE:
            // This event indicates that a Audio Status Write Transfer
            // request on the interrupt Endpoint has been completed. pData 
            // should be interpreted as a 
            // USB_DEVICE_AUDIO_EVENT_DATA_STATUS_SEND_COMPLETE pointer type.
            // This contains the transfer handle of the transfer.

            break;


        case USB_DEVICE_AUDIO_EVENT_INTERFACE_SETTING_CHANGED:

            // This event occurs when the host sends Set Interface request
            // to the Audio USB Device. pData will be a pointer to a
            // USB_DEVICE_AUDIO_EVENT_DATA_INTERFACE_SETTING_CHANGED. This
            // contains the interface number whose setting was
            // changed and the index of the alternate setting.
            // The application should typically enable the audio function
            // if the interfaceAlternateSettting member of pData is greater
            // than 0.

            break;
        
        case USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_UNKNOWN:
         
            // This event indicates that the Audio function driver has
            // received a control transfer which it cannot decode. pData
            // will be a pointer to USB_SETUP_PACKET type pointer. The
            // application should decode the packet and take the required
            // action using the USB_DEVICE_ControlStatus(),
            // USB_DEVICE_ControlSend() and USB_DEVICE_ControlReceive()
            // functions.

            break;

        case USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_SENT:
            
            // This event indicates the data send request associated with
            // the latest USB_DEVICE_ControlSend() function was
            // completed. pData will be NULL. 

        case USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_RECEIVED:

            // This event indicates the data receive request associated with
            // the latest USB_DEVICE_ControlReceive() function was
            // completed. pData will be NULL. The application can either
            // acknowledge the received data or reject it by calling the 
            // USB_DEVICE_ControlStatus() function. 

            break;

        case USB_DEVICE_AUDIO_EVENT_CONTROL_SET_CUR:
            
            // This event indicates that the host is trying to set the
            // current setting attribute of a control. The data type will be
            // USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_CUR type.  The
            // application should identify the entity type based on the
            // entity ID. This mapping is application specific. The
            // following example assumes entity type to be a Feature Unit. 

            if(APP_EntityIdentify(((USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_CUR *)pData)->entityID) 
                    == APP_AUDIO_ENTITY_FEATURE_UNIT)
            {
                // The entity type is a feature unit. Type cast pData as
                // a USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST type and find
                // identify the control selector. This example shows the 
                // handling for VOLUME control 

                switch(((USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST *)pData)->controlSelector)
                {
                    case USB_AUDIO_VOLUME_CONTROL:
                        // This means the host is trying to set the volume.
                        // Use the USB_DEVICE_ControlReceive() function to
                        // receive the volume settings for each channel.

                        USB_DEVICE_ControlReceive(usbDeviceHandle, volumeSetting,
                                ((USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST *)pData)->wLength);
                    default:
                        // Only volume control is supported in this example.
                        // So everything else is stalled.
                        USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_ERROR);
                }
            }
            break;

        case USB_DEVICE_AUDIO_EVENT_CONTROL_GET_CUR:
            
            // This event indicates that the host is trying to get the
            // current setting attribute of a control. The data type will be
            // USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_CUR type.  The
            // application should identify the entity type based on the
            // entity ID. This mapping is application specific. The
            // following example assumes entity type to be a Feature Unit. 

            if(APP_EntityIdentify(((USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_CUR *)pData)->entityID) 
                    == APP_AUDIO_ENTITY_FEATURE_UNIT)
            {
                // The entity type is a feature unit. Type cast pData as
                // a USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST type and find
                // identify the control selector. This example shows the 
                // handling for VOLUME control 

                switch(((USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST *)pData)->controlSelector)
                {
                    case USB_AUDIO_VOLUME_CONTROL:
                        // This means the host is trying to get the volume.
                        // Use the USB_DEVICE_ControlReceive() function to
                        // receive the volume settings for each channel.

                        USB_DEVICE_ControlSend(usbDeviceHandle, volumeSetting,
                                ((USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST *)pData)->wLength);
                    default:
                        // Only volume control is supported in this example.
                        // So everything else is stalled.
                        USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_ERROR);
                }
            }
            break;
        
        case USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MAX:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MIN:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_SET_RES:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MEM:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MAX:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MIN:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_GET_RES:
        case USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MEM:
            // In this example these request are not supported and so are
            // stalled.
            USB_DEVICE_ControlStatus(usbDeviceHandle, USB_DEVICE_CONTROL_STATUS_ERROR);
            break;
        
        default:
            break;
    }
    
    return(USB_DEVICE_AUDIO_EVENT_RESPONSE_NONE);
}

Members

Members Description
USB_DEVICE_AUDIO_EVENT_WRITE_COMPLETE This event occurs when a write operation scheduled by calling the USB_DEVICE_AUDIO_Write() function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_WRITE_COMPLETE type.
USB_DEVICE_AUDIO_EVENT_READ_COMPLETE This event occurs when a read operation scheduled by calling the USB_DEVICE_AUDIO_Read() function has completed. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_READ_COMPLETE type.
USB_DEVICE_AUDIO_EVENT_STATUS_SEND_COMPLETE This event occurs when a status write opearttion is complete which was scheduled using the USB_DEVICE_AUDIO_StatusSend() function. The pData parameter in the event handler will point to the USB_DEVICE_AUDIO_EVENT_DATA_STATUS_SEND_COMPLETE type.
USB_DEVICE_AUDIO_EVENT_INTERFACE_SETTING_CHANGED This event occurs when the Host requests the Audio USB device to set an alternate setting on an interface present in this audio function. An Audio USB Device will typically feature a default interface setting and one or more alternate interface settings. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_INTERFACE_SETTING_CHANGED type. This contains the index of the interface whose setting must be changed and the index of the alternate setting. The application may enable or disable audio functions based on the interface setting.
USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_RECEIVED This event occurs when the data stage of a control write transfer has completed. This would occur after the application would respond with a USB_DEVICE_ControlReceive function, which may possibly have been called in response to a USB_DEVICE_AUDIO_EVENT_ENTITY_SETTINGS_RECEIVED event This event notifies the application that the data is received from Host and is available at the location passed by the USB_DEVICE_ControlReceive function. If the received data is acceptable to the application, it should acknowledge the data by calling the USB_DEVICE_ControlStatus function with a USB_DEVICE_CONTROL_STATUS_OK flag.The application can reject the received data by calling the USB_DEVICE_ControlStatus function with the USB_DEVICE_CONTROL_STATUS_ERROR flag. The pData parameter will be NULL.
USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_DATA_SENT This event occurs when the data stage of a control read transfer has completed. This would occur when the application has called the USB_DEVICE_ControlSend function to complete the data stage of a control transfer. The event indicates that the data has been transmitted to the host. The pData parameter will be NULL.
USB_DEVICE_AUDIO_EVENT_CONTROL_TRANSFER_UNKNOWN This event occurs when the Audio function driver receives a control transfer request that could not be decoded by Audio Function driver.The pData parameter will point to a USB_SETUP_PACKET type containing the SETUP packet. The application must analyze this SETUP packet and use the USB_DEVICE_ControlSend or USB_DEVICE_ControlReceive or the USB_DEVICE_ControlStatus functions to advance the control transfer or complete it.
USB_DEVICE_AUDIO_EVENT_CONTROL_SET_CUR This event occurs when the Host sends an Audio Control specific Set Current Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_CUR type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlReceive functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MIN This event occurs when the Host sends an Audio Control specific Set Minimum Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_MIN type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlReceive functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_SET_MAX This event occurs when the Host sends an Audio Control specific Set Maximum Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_MAX type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlReceive functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_SET_RES This event occurs when the Host sends an Audio Control specific Set Resolution Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_RES type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus USB_DEVICE_ControlSend and/or USB_DEVICE_ControlReceive functions.
USB_DEVICE_AUDIO_EVENT_ENTITY_SET_MEM This event occurs when the Host sends an Audio Entity specific Set Memory Space Attribute Control Transfer request to an Audio Device Entity. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_MEM type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus USB_DEVICE_ControlSend and/or USB_DEVICE_ControlReceive functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_GET_CUR This event occurs when the Host sends an Audio Control specific Get Current Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_GET_CUR type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlSend functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MIN This event occurs when the Host sends an Audio Control specific Get Minimum Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_GET_MIN type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlSend functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_GET_MAX This event occurs when the Host sends an Audio Control specific Get Maximum Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_GET_MAX type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlSend functions.
USB_DEVICE_AUDIO_EVENT_CONTROL_GET_RES This event occurs when the Host sends an Audio Control specific Get Resolution Setting Attribute Control Transfer request to an Audio Device Control. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_GET_RES type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus and USB_DEVICE_ControlSend functions.
USB_DEVICE_AUDIO_EVENT_ENTITY_GET_MEM This event occurs when the Host sends an Audio Entity specific Get Memory Space Attribute Control Transfer request to an Audio Device Entity. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_CONTROL_SET_MEM type. The application must use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlStatus or USB_DEVICE_ControlSend functions.
USB_DEVICE_AUDIO_EVENT_ENTITY_GET_STAT This event occurs when the Host sends a Audio Entity specific Get Status Control Transfer request to an Audio Device Entity. The pData member in the event handler will point to USB_DEVICE_AUDIO_EVENT_DATA_ENTITY_GET_STAT type. The application mus use the entityID, interface, endpoint and the wValue field in the event data to determine the entity and control type and then respond to the control transfer with a USB_DEVICE_ControlSend and or USB_DEVICE_ControlStatus functions.

Remarks

The application can defer responses to events triggered by control transfers. In that, the application can respond to the control transfer event after exiting the event handler. This allows the application some time to obtain the response data rather than having to respond to the event immediately. Note that a USB host will typically wait for an event response for a finite time duration before timing out and canceling the event and associated transactions. Even when deferring response, the application must respond promptly if such time-out have to be avoided.