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

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.