Files added to implement Audio (v1.0) Host functions:
- usb-host-audio-v1_0.h
- usb-host-audio-v1_0.c
Application Programming Interfaces (APIs) provided:
Client Access:
- USB_HOST_AUDIO_V1_0_AttachEventHandlerSet
- USB_HOST_AUDIO_V1_0_DeviceObjHandleGet
- USB_HOST_AUDIO_V1_0_ControlRequest
- USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet
- USB_HOST_AUDIO_V1_0_StreamGetFirst
- USB_HOST_AUDIO_V1_0_StreamGetNext
Audio Stream Access :
- USB_HOST_AUDIO_V1_0_StreamOpen
- USB_HOST_AUDIO_V1_0_StreamEventHandlerSet
- USB_HOST_AUDIO_V1_0_StreamEnable
- USB_HOST_AUDIO_V1_0_StreamDisable
- USB_HOST_AUDIO_V1_0_StreamSamplingRateSet
- USB_HOST_AUDIO_V1_0_StreamWrite
- USB_HOST_AUDIO_V1_0_StreamRead
USB_HOST_AUDIO_V1_0_AttachEventHandlerSet
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_AttachEventHandlerSet Sets an attach event handler. The attach event handler is called each time an Audio v1.0 device has been attached or detached. The context can be modified and returned by the event handler. This function should be called before the bus is enabled. | Event Handler Context | USB_HOST_AUDIO_V1_0_RESULT |
Parameters:
Event Handler: pointer to the attach event handler.
Context: an application-defined context that can be modified by the event handler.
Example of Setting an Attach Event Handler:
USB_HOST_AUDIO_V1_RESULT result;
USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_V1_0_EVENT event;
// create the attach event handler
void App_MyAttachHandler(audioObj, event , 0)
{ … }
//set the attach event handler
result = USB_HOST_AUDIO_V1_0_AttachEventHandlerSet( &App_MyAttachHandler, 0 );
if(result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.
}
USB_HOST_AUDIO_V1_0_DeviceObjHandleGet
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_DeviceObjHandleGet Returns the Device Object Handle for an Audio v1.0 device. This returned Device Object Handle is used by the application to perform device level operations such as getting the string descriptors. | Audio Device Object | USB_HOST_DEVICE_OBJ_HANDLE |
Example of Getting a Device Handle:
USB_HOST_DEVICE_OBJ_HANDLE MyHandle;
USB_HOST_AUDIO_V1_0_OBJ audioObj;
MyHandle = USB_HOST_AUDIO_V1_0_DeviceObjHandleGet(audioObj) ;
if ( MyHandle == USB_HOST_DEVICE_OBJ_HANDLE_INVALID)
// process error
USB_HOST_AUDIO_V1_0_ControlRequest
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_ControlRequest Schedules an Audio v1.0 control transfer. | audioObject Request Handle Setup Packet Data Callback Context |
USB_HOST_AUDIO_V1_0_RESULT |
Parameters:
audioObj: Audio v1.0 Client Driver Object.
Request Handle: output parameter that will contain the handle for the transfer.
Setup Packet: pointer to the setup packet to send to the device in the setup.
Data: for control transfer with a data stage, this points to data to be sent.
Callback: pointer to the callback function that will be called.
Context: user-defined parameter that is passed to the callback function.
Example of scheduling an Audio v1.0 Control Transfer:
USB_HOST_AUDIO_V1_RESULT result;
USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_V1_0_REQUEST_HANDLE requestHandle ;
USB_AUDIO_FEATURE_UNIT_CONTROL_REQUEST setupPacket;
result = USB_HOST_AUDIO_V1_0_ControlRequest (audioObj, &requestHandle,
(USB_SETUP_PACKET *)&setupPacket, mute,
App_MyAudioControlRequestCallback,
(uintptr_t)context );
if( result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.
}
USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet Returns the number of stream groups present in an attached Audio v1.0 device. | Audio Device Object | uint8_t |
Example of Getting a Number of Stream Groups:
USB_HOST_AUDIO_V1_0_OBJ audioObj;
/* Get Number of Stream Groups */
*numberofStreamGroups = USB_HOST_AUDIO_V1_0_NumberOfStreamGroupsGet(audioObj);
USB_HOST_AUDIO_V1_0_StreamGetFirst
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamGetFirst Retrieves information from the first audio stream in the specified audio stream index. The object pointed to by the USB_HOST_AUDIO_V1_0_STREAM_INFO input parameter is loaded with the stream information. | Audio Device object. Stream Group index Stream Info |
USB_HOST_AUDIO_V1_RESULT |
Parameters:
Audio Device Object: Audio v1.0 Client Driver Object.
Stream Group Index: Stream Group Index.
Stream Info Object: pointer to Stream Object.
Example of Getting the First Stream in the Device:
USB_HOST_AUDIO_V1_0_OBJ audioObj;
USB_HOST_AUDIO_STREAM_FORTMAT audioStream;
USB_HOST_AUDIO_V1_RESULT result;
. . .
result = USB_HOST_AUDIO_V1_0_StreamGetFirst*(audioObj,0 , &audioStream);
if( result != USB_HOST_AUDIO_V1_0_RESULT_SUCCESS)
{
//Handle error.
}
USB_HOST_AUDIO_V1_0_StreamGetNext
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamGetNext Returns information about next audio stream in the specified audio stream group. The function USB_HOST_AUDIO_V1_0_StreamGetFirst() should have been called before calling this function. | Audio Device Object Stream Info |
USB_HOST_AUDIO_V1_RESULT |
Parameters:
Audio Device Object: Audio v1.0 Client Driver Object
Stream Info: pointer to Stream Info oObject
Example of Getting the Next Stream in the Device:
USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_STREAM_INFO audioStream;
USB_HOST_AUDIO_V1_RESULT result;
. . .
// put next stream info in structure pointed to by audioStream
result = USB_HOST_AUDIO_V1_0_StreamGetNext*(audioObj, &audioStream);
if( result != USB_HOST_AUDIO_V1_0_RESULT_END_OF_STREAM_LIST)
{
//There are more streams
}
USB_HOST_AUDIO_V1_0_StreamOpen
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamOpen Opens the specified audio stream and returns a handle to access the stream. | Audio Stream Object | USB_HOST_AUDIO_V1_0_STREAM_HANDLE |
Example of Obtaining a Stream Handle:
USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;
. . .
audioStreamHandle = USB_HOST_AUDIO_V1_0_StreamOpen( audioStreamObj) ;
USB_HOST_AUDIO_V1_0_StreamEventHandlerSet
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamEventHandlerSet Registers an event handler to be called in response to events occurring during transfers with the attached device. | Handle EventFunction Context |
USB_HOST_AUDIO_V1_0_STREAM_RESULT |
Parameters:
Handle: handle to the audio stream.
EventFunction: pointer to the desired event handler function.
Context: user-defined parameter passed to event handler.
Example of Setting an Event Handler for Host Audio:
USB_HOST_AUDIO_V1_0_STREAM_HANDLE MyStreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_RESULT result;
. . .
// user written event handler function
USB_HOST_AUDIO_V1_0_STREAM_EVENT_RESPONSE MyEventHandler
( USB_HOST_AUDIO_V1_0_STREAM_HANDLE streamHandle,
USB_HOST_AUDIO_V1_0_STREAM_EVENT event,
void * eventData,
uintptr_t context ) { … }
. . .
result = USB_HOST_AUDIO_V1_0_StreamEventHandlerSet( MyStreamHandle,
&MyEventHandler , 0);
if ( result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_TRUE)
// process error
USB_HOST_AUDIO_V1_0_StreamEnable
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamEnable Opens the specified audio stream and return a handle to access the stream. | Audio Stream Object | USB_HOST_AUDIO_V1_0_STREAM_HANDLE |
Example of Enabling a Stream:
USB_HOST_AUDIO_V1_0_STREAM_OBJ audioStreamObj;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;
. . .
audioStreamHandle = USB_HOST_AUDIO_V1_0_StreamOpen( audioStreamObj) ;
USB_HOST_AUDIO_V1_0_StreamDisable
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamDisable Schedules an audio stream disable request. | Audio Stream Handle RequestHandle |
USB_HOST_AUDIO_V1_0_STREAM_RESULT |
Parameters:
Audio Stream Handle: handle to the audio stream.
RequestHandle: handle to the stream disable request.
Example of Disabling a Stream
USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE audioStreamHandle;
. . .
result= USB_HOST_AUDIO_V1_0_StreamDisable( audioStreamHandle, &StreamRequest) ;
if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// The disable request was unsuccessful !
}
USB_HOST_AUDIO_V1_0_StreamSampleRateSet
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StreamSampleRateSet Sets the sample rate for an audio stream. | StreamHandle RequestHandle Rate |
USB_HOST_AUDIO_V1_0_STREAM_RESULT |
Parameters:
StreamHandle: handle to the audio stream.
RequestHandle: handle to the Stream Write request.
Source: pointer to the buffer containing data to be written to the device.
Length: length of transfer.
Example of Setting a Sampling Rate:
USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
. . .
result= USB_HOST_AUDIO_V1_0_StreamSampleRateSet( StreamHandle, &StreamRequest, 440) ;
if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// function request was unsuccessful !
}
USB_HOST_AUDIO_V1_0_StreamWrite
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StremWrite Schedules a write to an audio stream. | StreamHandle TransferHandle Source Length |
USB_HOST_AUDIO_V1_0_STREAM_RESULT |
Parameters:
StreamHandle: handle to the audio stream.
TransferHandle: handle to the Write Transfer request.
Source: location of output buffer.
Length: amount of data (in bytes).
Example of Writing a Stream:
uint16_t audioSamples[96] = { } // 192 bytes of initialized data
USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
. . .
result= USB_HOST_AUDIO_V1_0_StreamWrite( StreamHandle, &StreamRequest, &audoSemples,192) ;
if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// Write Function was unsuccessful !
}
USB_HOST_AUDIO_V1_0_StreamRead
| Description | Parameters | Returns |
|---|---|---|
| USB_HOST_AUDIO_V1_0_StremRead Schedules a read from an audio stream. | StreamHandle TransferHandle Destination Length |
USB_HOST_AUDIO_V1_0_STREAM_RESULT |
Parameters:
StreamHandle: handle to the audio stream.
TransferHandle: handle to the Write Transfer request.
Destination: location of input buffer.
Length: amount of data (in bytes).
Example of Reading a Stream:
uint16_t audioSamples[96]; // 192 bytes of uninitialized data
USB_HOST_AUDIO_V1_0_STREAM_RESULT result ;
USB_HOST_AUDIO_V1_0_STREAM_HANDLE StreamHandle;
USB_HOST_AUDIO_V1_0_STREAM_REQUEST_HANDLE StreamRequest;
. . .
result= USB_HOST_AUDIO_V1_0_StreamRead( StreamHandle, &StreamRequest, &audoSemples,192) ;
if (result != USB_HOST_AUDIO_V1_0_STREAM_RESULT_SUCCESS)
{
// Write Function was unsuccessful !
}