View source for UsbStartCtrlTransfer

==Description==
Starts asynchronous Control Transfer with a specific endpoint.

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

==Syntax==
<pre>
ulrc = UsbStartCtrlTransfer(Handle,ucEndpoint,ucAltSetting,ucRequestType,ucRequest,usValue,usIndex,pucParm,pucData,ulEvent)
</pre>

==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==
<pre>
0x0000 - NO_ERROR
</pre>
===Errors===
<pre>
0x0057 - ERROR_INVALID_PARAMETER
0x1B58 - USB_NOT_INIT
0xFF0D - ERROR_INVALID_DATA
0xFF37 - ERROR_DEV_NOT_EXIST
0xFFA7 - ERROR_LOCK_FAILED
</pre>
==Status Code==
<pre>
0x0000 - USB_IORB_DONE
</pre>
===Errors===
<pre>
0x4000 - USB_IORB_REQUEST
0x80XX - USB_IORB_FAILED
</pre>
==Remarks==
'''Warning:''' Only one UsbStartCtrlTransfer may be outstanding to a particular endpoint.
==Example Code==
<pre>
//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: [%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: [%04X] (%hu)",ulrc,ulrc);

  //await asynchronous control transfer complete
  ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = CtrlResponse.usStatus;
    printf("\nCompletion Status - ulrc: [%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: [%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: [%04X] (%hu)",ulrc,ulrc);

  //await asynchronous control transfer complete
  ulrc = DosWaitEventSem(hCtrlComplete,ulTimeout);
  printf("\nDosWaitEventSem - ulrc: [%04X] (%hu)",ulrc,ulrc);
  if (!ulrc) //success
  {
    ulrc = CtrlResponse.usStatus;
    printf("\nCompletion Status - ulrc: [%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: [%04X] (%hu)",ulrc,ulrc);
}
</pre>
==Related Functions==

[[Category:USBCalls]]