UsbStartCtrlTransfer

Description

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);
}