UsbStartCtrlTransfer: Difference between revisions
Appearance
mNo edit summary |
|||
(One intermediate revision by one other user not shown) | |||
Line 1: | Line 1: | ||
Starts asynchronous Control Transfer with a specific endpoint. | Starts asynchronous Control Transfer with a specific endpoint. | ||
;Warning: Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint. | |||
==Syntax== | ==Syntax== | ||
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType, | |||
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue,usIndex,pucParm,pucData,ulEvent) | ucRequest,usValue,usIndex,pucParm,pucData,ulEvent) | ||
==Parameters== | ==Parameters== | ||
; Handle : the Device Handle received from the previous UsbOpen. | ; Handle : the Device Handle received from the previous UsbOpen. | ||
; ucEndpoint : the Endpoint Number appropriate for the control transfer. | ; ucEndpoint : the Endpoint Number appropriate for the control transfer. | ||
; ucAltSetting : the Alternate Setting of the interface having this endpoint. | ; ucAltSetting : the Alternate Setting of the interface having this endpoint. | ||
; ucRequestType : the characteristics of the Standard Device Request. | ; ucRequestType : the characteristics of the Standard Device Request. | ||
; ucRequest : the specific request code of the Standard Device Request. | ; ucRequest : the specific request code of the Standard Device Request. | ||
; usValue : the request dependent value of the Standard Device Request. | ; usValue : the request dependent value of the Standard Device Request. | ||
; usIndex : the request dependent index of the Standard Device Request. | ; usIndex : the request dependent index of the Standard Device Request. | ||
; ulEvent : the handle of the event semaphore to be posted on completion. | ; ulEvent : the handle of the event semaphore to be posted on completion. | ||
; pucParm : the address of the buffer with variables usDatalength and usStatus. | ; pucParm : the address of the buffer with variables usDatalength and usStatus. | ||
; usDataLength : the variable to specify/receive the number of data bytes. | ; usDataLength : the variable to specify/receive the number of data bytes. | ||
; usStatus : the variable to receive the asynchronous Completion Status. | ; usStatus : the variable to receive the asynchronous Completion Status. | ||
Line 41: | Line 29: | ||
==Return Code== | ==Return Code== | ||
0x0000 - NO_ERROR | |||
0x0000 - NO_ERROR | |||
===Errors=== | ===Errors=== | ||
0x0057 - ERROR_INVALID_PARAMETER | |||
0x0057 - ERROR_INVALID_PARAMETER | 0x1B58 - USB_NOT_INIT | ||
0x1B58 - USB_NOT_INIT | 0xFF0D - ERROR_INVALID_DATA | ||
0xFF0D - ERROR_INVALID_DATA | 0xFF13 - ERROR_I24_INVALID_PARAMETER | ||
0xFF13 - ERROR_I24_INVALID_PARAMETER | 0xFF13 - USB_IDC_PARMERR | ||
0xFF13 - USB_IDC_PARMERR | 0xFF18 - USB_IDC_ADDRINV | ||
0xFF18 - USB_IDC_ADDRINV | 0xFF37 - ERROR_DEV_NOT_EXIST | ||
0xFF37 - ERROR_DEV_NOT_EXIST | 0xFF5D - EROR_NO_ITEMS | ||
0xFF5D - EROR_NO_ITEMS | 0xFFA7 - ERROR_LOCK_FAILED | ||
0xFFA7 - ERROR_LOCK_FAILED | |||
==Status Code== | ==Status Code== | ||
0x0000 - USB_IORB_DONE | |||
0x0000 - USB_IORB_DONE | |||
===Errors=== | ===Errors=== | ||
0x4000 - USB_IORB_REQUEST | |||
0x4000 - USB_IORB_REQUEST | 0x80XX - USB_IORB_FAILED | ||
0x80XX - USB_IORB_FAILED | |||
==Remarks== | ==Remarks== | ||
;Warning:Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint. | |||
==Example Code== | ==Example Code== | ||
<pre> | <pre> | ||
Line 100: | Line 84: | ||
CtrlResponse.usDataLength = usLength; | CtrlResponse.usDataLength = usLength; | ||
pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; | pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; | ||
ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue,usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); | ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue, | ||
usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); | |||
printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); | printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); | ||
Line 131: | Line 116: | ||
CtrlResponse.usDataLength = usLength; | CtrlResponse.usDataLength = usLength; | ||
pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; | pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; | ||
ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue,usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); | ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest, | ||
usValue,usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); | |||
printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); | printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); | ||
Line 161: | Line 147: | ||
==Related Functions== | ==Related Functions== | ||
* [[UsbCancelTransfer]] | |||
* [[UsbCtrlTransfer]] | |||
* [[UsbOpen]] | |||
[[Category:USBCalls]] | [[Category:USBCalls]] |
Latest revision as of 22:22, 28 February 2020
Starts asynchronous Control Transfer with a specific endpoint.
- Warning
- Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint.
Syntax
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType, ucRequest,usValue,usIndex,pucParm,pucData,ulEvent)
Parameters
- Handle
- the Device Handle received from the previous UsbOpen.
- ucEndpoint
- the Endpoint Number appropriate for the control transfer.
- ucAltSetting
- the Alternate Setting of the interface having this endpoint.
- ucRequestType
- the characteristics of the Standard Device Request.
- ucRequest
- the specific request code of the Standard Device Request.
- usValue
- the request dependent value of the Standard Device Request.
- usIndex
- the request dependent index of the Standard Device Request.
- ulEvent
- the handle of the event semaphore to be posted on completion.
- pucParm
- the address of the buffer with variables usDatalength and usStatus.
- usDataLength
- the variable to specify/receive the number of data bytes.
- usStatus
- the variable to receive the asynchronous Completion Status.
For device-to-host data transfer:
- pucData
- the address of the buffer to receive the data bytes transferred.
For host-to-device data transfer:
- pucData
- the address of the buffer with the data bytes to be transferred.
Return Code
0x0000 - NO_ERROR
Errors
0x0057 - ERROR_INVALID_PARAMETER 0x1B58 - USB_NOT_INIT 0xFF0D - ERROR_INVALID_DATA 0xFF13 - ERROR_I24_INVALID_PARAMETER 0xFF13 - USB_IDC_PARMERR 0xFF18 - USB_IDC_ADDRINV 0xFF37 - ERROR_DEV_NOT_EXIST 0xFF5D - EROR_NO_ITEMS 0xFFA7 - ERROR_LOCK_FAILED
Status Code
0x0000 - USB_IORB_DONE
Errors
0x4000 - USB_IORB_REQUEST 0x80XX - USB_IORB_FAILED
Remarks
- Warning
- Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint.
Example Code
//Code Snippet - UsbStartCtrlTransfer { APIRET ulrc; PUCHAR pucData; UCHAR ucAltSetting = 0; UCHAR ucEndpoint = 0; UCHAR ucData[4096]; UCHAR ucRequestType; UCHAR ucRequest; ULONG ulPostCount; ULONG ulTimeout = 8000; USHORT usIndex; USHORT usLength; USHORT usValue; HEV hCtrlComplete; PHEV phCtrlComplete; PUSBCALLS_CTRL_RSP pCtrlResponse; USBCALLS_CTRL_RSP CtrlResponse; //acquire semaphore phCtrlComplete = &hCtrlComplete; ulrc = DosCreateEventSem(NULL,phCtrlComplete,DC_SEM_SHARED,FALSE); printf("\nDosCreateEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc); //start asynchronous control transfer ucRequestType = 0xA1; ucRequest = 0x01; //get interface class report usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report CtrlResponse.usDataLength = usLength; pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue, usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); //await asynchronous control transfer complete ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout); printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc); if (!ulrc) //success { ulrc = CtrlResponse.usStatus; printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc); usLength = CtrlResponse.usDataLength; if (!ulrc) //success { int i; printf(" - hid input report:\n"); for (i=0;i<usLength;i++) printf("%02X",ucData[i]); } } else { // failure awaiting control transfer completion UsbCancelTransfer(Handle,ucEndpoint,ucAltSetting,hCtrlComplete); } ulrc = DosResetEventSem(hCtrlComplete,&ulPostCount); printf("\nDosResetEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc); //start asynchronous control transfer ucRequestType = 0x21; ucRequest = 0x09; //set interface class report usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report CtrlResponse.usDataLength = usLength; pCtrlResponse = &CtrlResponse; pucData = &ucData[0]; ulrc=UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest, usValue,usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete); printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc); //await asynchronous control transfer complete ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout); printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc); if (!ulrc) //success { ulrc = CtrlResponse.usStatus; printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc); usLength = CtrlResponse.usDataLength; if (!ulrc) //success { int i; printf(" - hid output report:\n"); for (i=0;i<usLength;i++) printf("%02X",ucData[i]); } } else { // failure awaiting control transfer completion UsbCancelTransfer(Handle,ucEndpoint,ucAltSetting,hCtrlComplete); } //release semaphore ulrc = DosCloseEventSem(hCtrlComplete); printf("\nDosCloseEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc); }