Share via

IssueBulkTransfer (Compact 2013)

  • Article

3/26/2014

This function initiates a bulk transfer to a universal serial bus (USB) device on the specified endpoint.

Syntax

DWORD IssueBulkTransfer(
  LPCUSB_FUNCS UsbFuncs, 
  USB_PIPE hPipe,
  LPTRANSFER_NOTIFY_ROUTINE NotifyRoutine,
  PVOID NotifyContext,
  DWORD Flags,
  LPVOID pBuffer,
  ULONG PhysAddr,
  DWORD BufferLength,
  LPDWORD pBytesTransferred,
  DWORD dwTimeout, 
  PUSB_ERROR pUsbRc
);

Parameters

  • pUsbFuncs
    [in] Pointer to a USB_FUNCS structure.
  • hPipe
    [in] Handle to an open USB pipe.
  • NotifyRoutine
    [in] Pointer to a transfer completion function of type LPTRANSFER_NOTIFY_ROUTINE, or NULL if no callback function is necessary.
  • NotifyContext
    [in] Pointer to the parameter to pass to the transfer completion routine.
  • Flags
    [in] USB_XXX flags for the transfer. Usbtypes.h declares these values.
  • pBuffer
    [in] Pointer to the transfer buffer. If a physical buffer address, PhysAddr, is specified. This parameter must contain the virtual address of the buffer.
  • PhysAddr
    [in] Physical address of pBuffer, which might be NULL.
  • BufferLength
    [in] Length of transfer buffer in bytes.
  • pBytesTransferred
    [out] Number of bytes transferred by the USB host to the USB host client device.
  • dwTimeout
    [in] Timeout in milliseconds.
  • pUsbRc
    [out] USB_ERROR or USB_TRANSFER.

Return Value

Microsoft® Win32® error code. For more information, see GetLastError.

Remarks

The caller must determine whether the correct number of bytes were transferred. The caller must also determine any Win32 error codes or USB error codes, and handle any USB errors.

IssueBulkTransfer behaves either synchronously or asynchronously, depending on the value you provide for NotifyRoutineand whether Flags contains the USB_NO_WAIT flag. If NotifyRoutineand NotifyContextare NULL, then the call is made synchronously. If NotifyRoutineand NotifyContextare not NULL, then the call is made asynchronously with some restrictions. The following list shows these restrictions:

  • If dwTimeout is not zero, then IssueBulkTransfer waits for either the NotifyContext, which must be an initialized EVENT, or the timeout duration.
  • If dwTimeoutis zero, then IssueBulkTransfer returns immediately.

Note

Under certain timing and thread scheduling conditions, NotifyRoutine may be called before IssueBulkTransfer returns to the calling thread. For this reason, the two routines may need to be synchronized.

The Transfer handle is returned in the pUsbError parameter. It is up to the caller to check transfer status, close the transfer handle, and so on.

When behaving asynchronously, this function invokes the callback function optionally specified by NotifyRoutine when the transfer is complete.

To maximize speed, USB host client drivers should fill pBuffer and use asynchronous mode.

Requirements

Header

usbclient.h

See Also

Reference

USB Host Client Driver Functions
AbortTransfer
GetTransferStatus
LPIS_TRANSFER_COMPLETE
LPTRANSFER_NOTIFY_ROUTINE
USB_FUNCS