3.2.4.14 USB_HOST_DeviceStringDescriptorGet Function

C

USB_HOST_RESULT USB_HOST_DeviceStringDescriptorGet(
    USB_HOST_DEVICE_OBJ_HANDLE deviceObjHandle, 
    USB_HOST_DEVICE_STRING stringType, 
    uint16_t languageID, 
    void * stringDescriptor, 
    size_t length, 
    USB_HOST_REQUEST_HANDLE * requestHandle, 
    USB_HOST_STRING_REQUEST_COMPLETE_CALLBACK callback, 
    uintptr_t context
);

Summary

This function retrieves the specified string descriptor from the device. This function will cause the host layer to issue a control transfer to the device. When the string descriptor is available, the host layer will call the callback function to let the application know that the request has completed.

The function will return a valid request handle in requestHandle, if the request was successful. This request handle will be returned in the callback function. The size of the stringDescriptor buffer is specified by the length parameter. Only length number of bytes will be retrieved. The type of device string descriptor to be retrieved is specified by the stringType parameter. The supported language IDs, manufacturer, product and serial number strings can be obtained. While obtaining the supported language IDs, the languageID parameter will be ignored.

Precondition

The USB_HOST_BusEnable() function should have been called.

Parameters


Parameters	Description
deviceObjHandle	handle to the device whose string descriptor is to be retrieved.
stringType	type of string descriptor to be retrieved.
languageID	the language ID of the string descriptor.
stringDescriptor	output buffer for the descriptor.
length	size of the specified output buffer.
requestHandle	This is an output parameter. It will contain a valid request handle if the request was successful. It will contain USB_HOST_REQUEST_HANDLE_INVALID is the request was not successful.
callback	Function that will be called when this request completes. If this is NULL, then the application will not receive indication of completion.
context	Calling application context to be returned in the callback function.

Returns

USB_HOST_RESULT_SUCCESS - The request was scheduled successfully. requestHandle will contain a valid request handle.

USB_HOST_RESULT_DEVICE_UNKNOWN - The request failed because the device was detached.

USB_HOST_RESULT_FAILURE - An unknown error occurred.

USB_HOST_RESULT_REQUEST_BUSY - The host layer cannot take more requests at this point. The application should try later.

USB_HOST_RESULT_STRING_DESCRIPTOR_UNSUPPORTED - The device does not support the specified string descriptor type.

Remarks

None.