Jump to content

UsbStartDataTransfer: Difference between revisions

From EDM2
← Older edit
W.m.brul (talk | contribs)
272 edits
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(3 intermediate revisions by one other user not shown)
Line 5: Line 5:


==Syntax==
==Syntax==
<pre>
ulrc = UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,pucParm,pucData,ulEvent,usFlags)
ulrc = UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,pucParm,pucData,ulEvent,usFlags)
</pre>


==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 data transfer.
; ucEndpoint : the Endpoint Number appropriate for the data transfer.
; ucAltSetting : the Alternate Setting of the interface having this endpoint.
; ucAltSetting : the Alternate Setting of the interface having this endpoint.
; ulEvent : the handle of the event semaphore to be posted on completion.
; 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.
; usFlags : use 1 to transfer all data or 0 to allow less transferred.
; 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.
''For device-to-host data transfer:''
''For device-to-host data transfer:''
; pucData : the address of the buffer to receive the data bytes transferred.
; pucData : the address of the buffer to receive the data bytes transferred.
''For host-to-device data transfer:''
''For host-to-device data transfer:''
; pucData : the address of the buffer with the data bytes to be transferred.
; pucData : the address of the buffer with the data bytes to be transferred.


==Return Code==
==Return Code==
<pre>
0x0000 - NO_ERROR
0x0000 - NO_ERROR
 
</pre>
===Errors===
===Errors===
<pre>
<pre>
Line 52: Line 38:


==Status Code==
==Status Code==
<pre>
0x0000 - USB_IORB_DONE
0x0000 - USB_IORB_DONE  
 
</pre>
===Errors===
===Errors===
<pre>
0x4000 - USB_IORB_REQUEST
0x4000 - USB_IORB_REQUEST
0x80XX - USB_IORB_FAILED
0x80XX - USB_IORB_FAILED
 
</pre>
==Remarks==
==Remarks==
'''Warning:''' Only one UsbStartDataTransfer may be outstanding to a particular endpoint.
'''Warning:''' Only one UsbStartDataTransfer may be outstanding to a particular endpoint.
Line 79: Line 63:
   HEV hDataComplete;
   HEV hDataComplete;
   PHEV phDataComplete;
   PHEV phDataComplete;
   PUSBCALLS_CTRL_RSP pDataResponse;
   PUSBCALLS_DATA_RSP pDataResponse;
   USBCALLS_CTRL_RSP DataResponse;
   USBCALLS_DATA_RSP DataResponse;


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


   //start asynchronous data transfer
   //start asynchronous data transfer
Line 92: Line 76:
   ucEndpoint = 0x81; usFlags = 0; //device-to-host transfer
   ucEndpoint = 0x81; usFlags = 0; //device-to-host transfer
   ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
   ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
   printf("\nUsbStartDataTransfer - ulrc: [%04X] (%hu)",ulrc,ulrc);
   printf("\nUsbStartDataTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //await asynchronous data transfer complete
   //await asynchronous data transfer complete
   ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
   ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
   printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
   printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
   if (!ulrc) //success
   if (!ulrc) //success
   {
   {
     ulrc = DataResponse.usStatus;
     ulrc = DataResponse.usStatus;
     printf("\nCompletion Status - ulrc: [%04X] (%hu)",ulrc,ulrc);
     printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc);
     usLength = DataResponse.usDataLength;
     usLength = DataResponse.usDataLength;
     if (!ulrc) //success
     if (!ulrc) //success
Line 115: Line 99:


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


   //start asynchronous data transfer
   //start asynchronous data transfer
Line 122: Line 106:
   ucEndpoint = 0x02; usFlags = USB_TRANSFER_FULL_SIZE; //host-to-device transfer
   ucEndpoint = 0x02; usFlags = USB_TRANSFER_FULL_SIZE; //host-to-device transfer
   ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
   ulrc=UsbStartDataTransfer(Handle,ucEndpoint,ucAltSetting,(PUCHAR)pDataResponse,pucData,hDataComplete,usFlags);
   printf("\nUsbStartDataTransfer - ulrc: [%04X] (%hu)",ulrc,ulrc);
   printf("\nUsbStartDataTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //await asynchronous data transfer complete
   //await asynchronous data transfer complete
   ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
   ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
   printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
   printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
   if (!ulrc) //success
   if (!ulrc) //success
   {
   {
     ulrc = DataResponse.usStatus;
     ulrc = DataResponse.usStatus;
     printf("\nCompletion Status - ulrc: [%04X] (%hu)",ulrc,ulrc);
     printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc);
     usLength = DataResponse.usDataLength;
     usLength = DataResponse.usDataLength;
     if (!ulrc) //success
     if (!ulrc) //success
     {
     {
       int i; printf(" - device-to-host data:\n");
       int i; printf(" - bulk/interrupt data:\n");
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
     }
     }
Line 146: Line 130:
   //release semaphore
   //release semaphore
   ulrc = DosCloseEventSem(hDataComplete);
   ulrc = DosCloseEventSem(hDataComplete);
   printf("\nDosCloseEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
   printf("\nDosCloseEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
}
}
</pre>
</pre>
==Related Functions==
==Related Functions==
* [[UsbCancelTransfer]]
* [[UsbDataTransfer]]
* [[UsbOpen]]


[[Category:USBCalls]]
[[Category:USBCalls]]

Latest revision as of 20:42, 13 September 2021

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
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 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_DATA_RSP pDataResponse;
  USBCALLS_DATA_RSP DataResponse;

  //acquire semaphore
  phDataComplete = &hDataComplete;
  ulrc = DosCreateEventSem(NULL,phDataComplete,DC_SEM_SHARED,FALSE);
  printf("\nDosCreateEventSem - ulrc: 0x%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: 0x%04X (%hu)",ulrc,ulrc);

  //await asynchronous data transfer complete
  ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = DataResponse.usStatus;
    printf("\nCompletion Status - ulrc: 0x%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: 0x%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: 0x%04X (%hu)",ulrc,ulrc);

  //await asynchronous data transfer complete
  ulrc = DosWaitEventSem(hDataComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = DataResponse.usStatus;
    printf("\nCompletion Status - ulrc: 0x%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);
  }

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

Related Functions

Retrieved from "https://www.edm2.com/index.php?title=UsbStartDataTransfer&oldid=76879"