Synchronous device I/O

Functions
int API_EXPORTED	libusb_control_transfer (libusb_device_handle *dev_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout)
int API_EXPORTED	libusb_bulk_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)
int API_EXPORTED	libusb_interrupt_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)

Detailed Description

This page documents libusb's synchronous (blocking) API for USB device I/O. This interface is easy to use but has some limitations. More advanced users may wish to consider using the asynchronous I/O API instead.

Function Documentation

libusb_bulk_transfer()

int API_EXPORTED libusb_bulk_transfer	(	libusb_device_handle *	dev_handle,
		unsigned char	endpoint,
		unsigned char *	data,
		int	length,
		int *	transferred,
		unsigned int	timeout
	)

Perform a USB bulk transfer. The direction of the transfer is inferred from the direction bits of the endpoint address.

For bulk reads, the length field indicates the maximum length of data you are expecting to receive. If less data arrives than expected, this function will return that data, so be sure to check the transferred output parameter.

You should also check the transferred parameter for bulk writes. Not all of the data may have been written.

Also check transferred when dealing with a timeout error code. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O. See Timeouts for more details.

Parameters

dev_handle	a handle for the device to communicate with
endpoint	the address of a valid endpoint to communicate with
data	a suitably-sized data buffer for either input or output (depending on endpoint)
length	for bulk writes, the number of bytes from data to be sent. for bulk reads, the maximum number of bytes to receive into the data buffer.
transferred	output location for the number of bytes actually transferred. Since version 1.0.21 (LIBUSB_API_VERSION >= 0x01000105), it is legal to pass a NULL pointer if you do not wish to receive this information.
timeout	timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

Returns

0 on success (and populates transferred)

LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates transferred)

LIBUSB_ERROR_PIPE if the endpoint halted

LIBUSB_ERROR_OVERFLOW if the device offered more data, see Packets and overflows

LIBUSB_ERROR_NO_DEVICE if the device has been disconnected

LIBUSB_ERROR_BUSY if called from event handling context

LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see Transfer length limitations)

another LIBUSB_ERROR code on other failures

libusb_control_transfer()

int API_EXPORTED libusb_control_transfer	(	libusb_device_handle *	dev_handle,
		uint8_t	bmRequestType,
		uint8_t	bRequest,
		uint16_t	wValue,
		uint16_t	wIndex,
		unsigned char *	data,
		uint16_t	wLength,
		unsigned int	timeout
	)

Perform a USB control transfer.

The direction of the transfer is inferred from the bmRequestType field of the setup packet.

The wValue, wIndex and wLength fields values should be given in host-endian byte order.

Parameters

dev_handle	a handle for the device to communicate with
bmRequestType	the request type field for the setup packet
bRequest	the request field for the setup packet
wValue	the value field for the setup packet
wIndex	the index field for the setup packet
data	a suitably-sized data buffer for either input or output (depending on direction bits within bmRequestType)
wLength	the length field for the setup packet. The data buffer should be at least this size.
timeout	timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

Returns

on success, the number of bytes actually transferred

LIBUSB_ERROR_TIMEOUT if the transfer timed out

LIBUSB_ERROR_PIPE if the control request was not supported by the device

LIBUSB_ERROR_NO_DEVICE if the device has been disconnected

LIBUSB_ERROR_BUSY if called from event handling context

LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see Transfer length limitations)

another LIBUSB_ERROR code on other failures

libusb_interrupt_transfer()

int API_EXPORTED libusb_interrupt_transfer	(	libusb_device_handle *	dev_handle,
		unsigned char	endpoint,
		unsigned char *	data,
		int	length,
		int *	transferred,
		unsigned int	timeout
	)

Perform a USB interrupt transfer. The direction of the transfer is inferred from the direction bits of the endpoint address.

For interrupt reads, the length field indicates the maximum length of data you are expecting to receive. If less data arrives than expected, this function will return that data, so be sure to check the transferred output parameter.

You should also check the transferred parameter for interrupt writes. Not all of the data may have been written.

Also check transferred when dealing with a timeout error code. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O. See Timeouts for more details.

The default endpoint bInterval value is used as the polling interval.

Parameters

dev_handle	a handle for the device to communicate with
endpoint	the address of a valid endpoint to communicate with
data	a suitably-sized data buffer for either input or output (depending on endpoint)
length	for bulk writes, the number of bytes from data to be sent. for bulk reads, the maximum number of bytes to receive into the data buffer.
transferred	output location for the number of bytes actually transferred. Since version 1.0.21 (LIBUSB_API_VERSION >= 0x01000105), it is legal to pass a NULL pointer if you do not wish to receive this information.
timeout	timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

Returns

0 on success (and populates transferred)

LIBUSB_ERROR_TIMEOUT if the transfer timed out

LIBUSB_ERROR_PIPE if the endpoint halted

LIBUSB_ERROR_OVERFLOW if the device offered more data, see Packets and overflows

LIBUSB_ERROR_NO_DEVICE if the device has been disconnected

LIBUSB_ERROR_BUSY if called from event handling context

LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see Transfer length limitations)

another LIBUSB_ERROR code on other error