UsbStartDataTransfer

Description

Starts asynchronous Bulk or Interrupt Transfer with a specific endpoint.

Warning: Only one UsbStartDataTransfer may be outstanding to a particular endpoint.

Syntax

ulrc = UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,pucParm,pucData,ulEvent,usFlags)

Parameters

Handle

the Device Handle received from the previous UsbOpen.

ucEndpoint

the Endpoint Number appropriate for the data transfer.

ucAltSetting

the Alternate Setting of the interface having this endpoint.

ulEvent

the handle of the event semaphore to be posted on completion.

usFlags

use 1 to transfer all data or 0 to allow less transferred.

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
0xFF37 - ERROR_DEV_NOT_EXIST
0xFFA7 - ERROR_LOCK_FAILED

Status Code

0x0000 - USB_IORB_DONE 

Errors

0x4000 - USB_IORB_REQUEST
0x80XX - USB_IORB_FAILED

Remarks

Warning: Only one UsbStartDataTransfer may be outstanding to a particular endpoint.

Example Code

//Code Snippet - UsbStartDataTransfer
{
  APIRET ulrc;
  PUCHAR pucData;
  UCHAR ucAltSetting = 0;
  UCHAR ucData[4096];
  UCHAR ucEndpoint;
  ULONG ulPostCount;
  ULONG ulTimeout = 8000;
  USHORT usLength = sizeof(ucData);
  USHORT usFlags;

  HEV hDataComplete;
  PHEV phDataComplete;
  PUSBCALLS_CTRL_RSP pDataResponse;
  USBCALLS_CTRL_RSP DataResponse;

  //acquire semaphore
  phDataComplete = &hDataComplete;
  ulrc = DosCreateEventSem(NULL,phDataComplete,DC_SEM_SHARED,FALSE);
  printf("\nDosCreateEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);

  //start asynchronous data transfer
  DataResponse.usDataLength = usLength;
  pDataResponse = &DataResponse; pucData = &ucData[0];
  ucEndpoint = 0x81; usFlags = 0; //device-to-host transfer
  ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
  printf("\nUsbStartDataTransfer - ulrc: [%04X] (%hu)",ulrc,ulrc);

  //await asynchronous data transfer complete
  ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = DataResponse.usStatus;
    printf("\nCompletion Status - ulrc: [%04X] (%hu)",ulrc,ulrc);
    usLength = DataResponse.usDataLength;
    if (!ulrc) //success
    {
      int i; printf(" - bulk/interrupt data:\n");
      for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
    }
  }
  else
  {
    // failure awaiting data transfer completion
    UsbCancelTransfer(Handle,ucEndpoint,ucAltSetting,hDataComplete);
  }

  ulrc = DosResetEventSem(hDataComplete,&ulPostCount);
  printf("\nDosResetEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);

  //start asynchronous data transfer
  DataResponse.usDataLength = usLength;
  pDataResponse = &DataResponse; pucData = &ucData[0];
  ucEndpoint = 0x02; usFlags = USB_TRANSFER_FULL_SIZE; //host-to-device transfer
  ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
  printf("\nUsbStartDataTransfer - ulrc: [%04X] (%hu)",ulrc,ulrc);

  //await asynchronous data transfer complete
  ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = DataResponse.usStatus;
    printf("\nCompletion Status - ulrc: [%04X] (%hu)",ulrc,ulrc);
    usLength = DataResponse.usDataLength;
    if (!ulrc) //success
    {
      int i; printf(" - device-to-host data:\n");
      for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
    }
  }
  else
  {
    // failure awaiting data transfer completion
    UsbCancelTransfer(Handle,ucEndpoint,ucAltSetting,hDataComplete);
  }

  //release semaphore
  ulrc = DosCloseEventSem(hDataComplete);
  printf("\nDosCloseEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
}