Jump to content

UsbStartCtrlTransfer: Difference between revisions

From EDM2
← Older edit
W.m.brul (talk | contribs)
272 edits
Ak120 (talk | contribs)
35,969 edits
mNo edit summary
 
(2 intermediate revisions by one other user not shown)
Line 1: Line 1:
==Description==
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.
;Warning: Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint.


==Syntax==
==Syntax==
<pre>
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue,usIndex,pucParm,pucData,ulEvent)
                            ucRequest,usValue,usIndex,pucParm,pucData,ulEvent)
</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 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==
<pre>
0x0000 - NO_ERROR
0x0000 - NO_ERROR
 
</pre>
===Errors===
===Errors===
<pre>
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
</pre>


==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 UsbStartCtrlTransfer may be outstanding to a particular endpoint.
;Warning:Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint.
 
==Example Code==
==Example Code==
<pre>
<pre>
Line 91: Line 75:


   //acquire semaphore
   //acquire semaphore
   phCtrlComplete = &amp.hCtrlComplete;
   phCtrlComplete = &hCtrlComplete;
   ulrc = DosCreateEventSem(NULL,phCtrlComplete,DC_SEM_SHARED,FALSE);
   ulrc = DosCreateEventSem(NULL,phCtrlComplete,DC_SEM_SHARED,FALSE);
   printf("\nDosCreateEventSem - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
   printf("\nDosCreateEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //start asynchronous control transfer
   //start asynchronous control transfer
Line 99: Line 83:
   usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report
   usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report
   CtrlResponse.usDataLength = usLength;
   CtrlResponse.usDataLength = usLength;
   pCtrlResponse = &amp.CtrlResponse; pucData = &amp.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,
   printf("\nUsbStartCtrlTransfer - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
                            usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete);
   printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //await asynchronous control transfer complete
   //await asynchronous control transfer complete
   ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
   ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
   printf("\nDosWaitEventSem - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
   printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
   if (!ulrc) //success
   if (!ulrc) //success
   {
   {
     ulrc = CtrlResponse.usStatus;
     ulrc = CtrlResponse.usStatus;
     printf("\nCompletion Status - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
     printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc);
     usLength = CtrlResponse.usDataLength;
     usLength = CtrlResponse.usDataLength;
     if (!ulrc) //success
     if (!ulrc) //success
     {
     {
       int i; printf(" - hid input report&colon.\n");
       int i; printf(" - hid input report:\n");
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
     }
     }
Line 123: Line 108:
   }
   }


   ulrc = DosResetEventSem(hCtrlComplete,&amp.ulPostCount);
   ulrc = DosResetEventSem(hCtrlComplete,&ulPostCount);
   printf("\nDosResetEventSem - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
   printf("\nDosResetEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //start asynchronous control transfer
   //start asynchronous control transfer
Line 130: Line 115:
   usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report
   usIndex = 0x0000; usValue = 0x0200; usLength = 8; //hid output report
   CtrlResponse.usDataLength = usLength;
   CtrlResponse.usDataLength = usLength;
   pCtrlResponse = &amp.CtrlResponse; pucData = &amp.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,
   printf("\nUsbStartCtrlTransfer - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
                            usValue,usIndex,(PUCHAR)pCtrlResponse,pucData,hCtrlComplete);
   printf("\nUsbStartCtrlTransfer - ulrc: 0x%04X (%hu)",ulrc,ulrc);


   //await asynchronous control transfer complete
   //await asynchronous control transfer complete
   ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
   ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
   printf("\nDosWaitEventSem - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
   printf("\nDosWaitEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
   if (!ulrc) //success
   if (!ulrc) //success
   {
   {
     ulrc = CtrlResponse.usStatus;
     ulrc = CtrlResponse.usStatus;
     printf("\nCompletion Status - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
     printf("\nCompletion Status - ulrc: 0x%04X (%hu)",ulrc,ulrc);
     usLength = CtrlResponse.usDataLength;
     usLength = CtrlResponse.usDataLength;
     if (!ulrc) //success
     if (!ulrc) //success
     {
     {
       int i; printf(" - hid output report&colon.\n");
       int i; printf(" - hid output report:\n");
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
       for (i=0;i<usLength;i++) printf("%02X",ucData[i]);
     }
     }
Line 156: Line 142:
   //release semaphore
   //release semaphore
   ulrc = DosCloseEventSem(hCtrlComplete);
   ulrc = DosCloseEventSem(hCtrlComplete);
   printf("\nDosCloseEventSem - ulrc&colon. 0x%04X (%hu)",ulrc,ulrc);
   printf("\nDosCloseEventSem - ulrc: 0x%04X (%hu)",ulrc,ulrc);
}
}
</pre>
</pre>


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

Related Functions

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