Platforms to show: All Mac Windows Linux Cross-Platform

Back to LibUSBDeviceMBS class.

Next items

LibUSBDeviceMBS.AttachKernelDriver(interfaceNumber as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Re-attach an interface's kernel driver, which was previously detached using libusb_detach_kernel_driver().

This call is only effective on Linux and returns kErrorNotSupported on all other platforms.

This functionality is not available on Darwin or Windows.

Parameters:
interfaceNumber: the interface to attach the driver from

Lasterror is set:
0 on success
kErrorNotFound if no kernel driver was active
kErrorInvalidParam if the interface does not exist
kErrorNoDevice if the device has been disconnected
kErrorNotSupported on platforms where the functionality is not available
kErrorBusy if the driver cannot be attached because the interface is claimed by a program or driver
another error code on other failure

LibUSBDeviceMBS.BulkTransfer(endpoint as Integer, data as Ptr, Length as Integer, byref ActualLength as Integer, Timeout as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
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.

Parameters:
endpointthe address of a valid endpoint to communicate with
dataa suitably-sized data buffer for either input or output (depending on endpoint)
lengthfor 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.
transferredoutput location for the number of bytes actually transferred.
timeouttimeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

Lasterror is set to:
0 on success (and populates transferred)
kErrorTimeout if the transfer timed out (and populates transferred)
kErrorPipe if the endpoint halted
kErrorOverflow if the device offered more data, see Packets and overflows
kErrorNoDevice if the device has been disconnected
another error code on other failures

LibUSBDeviceMBS.ClaimInterface(interfaceNumber as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Claim an interface on a given device handle.

You must claim the interface you wish to use before you can perform I/O on any of its endpoints.

It is legal to attempt to claim an already-claimed interface, in which case libusb just returns 0 without doing anything.

Claiming of interfaces is a purely logical operation; it does not cause any requests to be sent over the bus. Interface claiming is used to instruct the underlying operating system that your application wishes to take ownership of the interface.

This is a non-blocking function.

Parameters:
interfaceNumber: the bInterfaceNumber of the interface you wish to claim

Lasterror is set:
0 on success
kErrorNotFound if the requested interface does not exist
kErrorBusy if another program or driver has claimed the interface
kErrorNoDevice if the device has been disconnected
a error code on other failure

LibUSBDeviceMBS.ClearHalt(endpoint as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Clear the halt/stall condition for an endpoint.

Endpoints with halt status are unable to receive or transmit data until the halt condition is stalled.

You should cancel all pending transfers before attempting to clear the halt condition.

This is a blocking function.

Parameters:
endpoint: the endpoint to clear halt status

Returns:
0 on success
kErrorNotFound if the endpoint does not exist
kErrorNoDevice if the device has been disconnected
another error code on other failure

LibUSBDeviceMBS.Close

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Close a device handle.

Should be called on all open handles before your application exits.
Internally, this function destroys the reference that was added by Open on the given device.
This is a non-blocking function; no requests are sent over the bus.

LibUSBDeviceMBS.ControlTransfer(requestType as Integer, Request as Integer, Value as Integer, Index as Integer, data as Ptr, Length as Integer, Timeout as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Perform a USB control transfer.

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

The Value, Index and Length fields values should be given in host-endian byte order.

Parameters:
RequestTypethe request type field for the setup packet
Requestthe request field for the setup packet
Valuethe value field for the setup packet
Indexthe index field for the setup packet
dataa suitably-sized data buffer for either input or output (depending on direction bits within bmRequestType)
Lengththe length field for the setup packet. The data buffer should be at least this size.
timeouttimeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

on success, the number of bytes actually transferred is returned.

Lasterror is set to:
kErrorTimeout if the transfer timed out
kErrorPipe if the control request was not supported by the device
kErrorNoDevice if the device has been disconnected
another error code on other failures

LibUSBDeviceMBS.DetachKernelDriver(interfaceNumber as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Detach a kernel driver from an interface.

If successful, you will then be able to claim the interface and perform I/O.
This functionality is not available on Darwin or Windows.

Parameters:
interfaceNumber: the interface to detach the driver from

Lasterror is set:
0 on success
kErrorNotFound if no kernel driver was active
kErrorInvalidParam if the interface does not exist
kErrorNoDevice if the device has been disconnected
kErrorNotSupported on platforms where the functionality is not available
another error code on other failure

LibUSBDeviceMBS.GetActiveConfigDescriptor as LibUSBConfigDescriptorMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Get the USB configuration descriptor for the currently active configuration.

This is a non-blocking function which does not involve any requests being sent to the device.

Lasterror is set to:
0 on success
kErrorNotFound if the device is in unconfigured state
another error code on error.

LibUSBDeviceMBS.GetConfigDescriptor(Index as Integer) as LibUSBConfigDescriptorMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Get a USB configuration descriptor based on its index.

This is a non-blocking function which does not involve any requests being sent to the device.

Parameters:
Indexthe index of the configuration you wish to retrieve

Lasterror is set to:
0 on success
kErrorNotFound if the configuration does not exist
another error code on error

Some examples using this method:

LibUSBDeviceMBS.GetConfigDescriptorByValue(Value as Integer) as LibUSBConfigDescriptorMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Get a USB configuration descriptor with a specific ConfigurationValue.

This is a non-blocking function which does not involve any requests being sent to the device.

Value: the bConfigurationValue of the configuration you wish to retrieve.

Lasterror is set to:
0 on success
kErrorNotFound if the configuration does not exist
another error code on error

LibUSBDeviceMBS.GetConfiguration as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Determine the bConfigurationValue of the currently active configuration.

You could formulate your own control request to obtain this information, but this function has the advantage that it may be able to retrieve the information from operating system caches (no I/O involved).

If the OS does not cache this information, then this function will block while a control transfer is submitted to retrieve the information.

This function will return a value of 0 in the config output parameter if the device is in unconfigured state.

Returns Configuration value of the active configuration (only valid for return code 0)

The lasterror is set to:
0 on success
kErrorNoDevice if the device has been disconnected
another error code on other failure

LibUSBDeviceMBS.GetDescriptor(descType as Integer, descIndex as Integer, data as Ptr, Length as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Retrieve a descriptor from the default control pipe.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor.

Parameters:
descTypethe descriptor type, see libusb_descriptor_type
descIndexthe index of the descriptor to retrieve
dataoutput buffer for descriptor
lengthsize of data buffer

Returns number of bytes returned in data or zero.
Sets lasterror to error code on failure

LibUSBDeviceMBS.GetDeviceDescriptor as LibUSBDeviceDescriptorMBS

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Get the USB device descriptor for a given device.

This is a non-blocking function; the device descriptor is cached in memory.

Returns 0 on success or a error code on failure.

Some examples using this method:

LibUSBDeviceMBS.GetMaxISOPacketSize(EndPoint as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Calculate the maximum packet size which a specific endpoint is capable is sending or receiving in the duration of 1 microframe.

Only the active configution is examined. The calculation is based on the wMaxPacketSize field in the endpoint descriptor as described in section 9.6.6 in the USB 2.0 specifications.

If acting on an isochronous or interrupt endpoint, this function will multiply the value found in bits 0:10 by the number of transactions per microframe (determined by bits 11:12). Otherwise, this function just returns the numeric value found in bits 0:10.

This function is useful for setting up isochronous transfers, for example you might pass the return value from this function to libusb_set_iso_packet_lengths() in order to set the length field of every isochronous packet in a transfer.

Since v1.0.3.

Parameters:
endpoint: address of the endpoint in question

Returns the maximum packet size which can be sent/received on this endpoint.

The lasterror is set to:
0 for success.
kErrorNotFound if the endpoint does not exist
kErrorOther on other failure

LibUSBDeviceMBS.GetMaxPacketSize(EndPoint as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Convenience function to retrieve the wMaxPacketSize value for a particular endpoint in the active device configuration.

This function was originally intended to be of assistance when setting up isochronous transfers, but a design mistake resulted in this function instead. It simply returns the wMaxPacketSize value without considering its contents. If you're dealing with isochronous transfers, you probably want libusb_get_max_iso_packet_size() instead.

Parameters:
endpoint: address of the endpoint in question

Returns the Max Packet Size value.

The lasterror is set:
0 for success.
kErrorNotFound if the endpoint does not exist
kErrorOther on other failure

LibUSBDeviceMBS.GetStringDescriptor(descIndex as Integer, LangID as Integer = 0) as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Retrieve a descriptor from a device.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

Parameters:
descIndexthe index of the descriptor to retrieve
LangIDthe language ID for the string descriptor

Returns string.
Lasterror is set to zero or error code on failure.

See also:

Some examples using this method:

LibUSBDeviceMBS.GetStringDescriptor(descIndex as Integer, LangID as Integer = 0, data as Ptr, Length as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Retrieve a descriptor from a device.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

Parameters:
descIndexthe index of the descriptor to retrieve
LangIDthe language ID for the string descriptor
dataoutput buffer for descriptor
lengthsize of data buffer

Returns number of bytes returned in data.
Lasterror is set to zero or error code on failure.

See also:

LibUSBDeviceMBS.GetStringDescriptorAscii(descIndex as Integer) as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Retrieve a string descriptor in ASCII.

Wrapper around GetStringDescriptor(). Uses the first language supported by the device.

Parameters:
descIndexthe index of the descriptor to retrieve

Returns string.
Lasterror is set to error code on failure and zero on success.

See also:

Some examples using this method:

LibUSBDeviceMBS.GetStringDescriptorAscii(descIndex as Integer, data as Ptr, Length as Integer) as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Retrieve a string descriptor in ASCII.

Wrapper around GetStringDescriptor(). Uses the first language supported by the device.

Parameters:
descIndexthe index of the descriptor to retrieve
dataoutput buffer for ASCII string descriptor
lengthsize of data buffer

Returns number of bytes returned in data.
Lasterror is set to error code on failure and zero on success.

See also:

LibUSBDeviceMBS.InterruptTransfer(endpoint as Integer, data as Ptr, Length as Integer, byref ActualLength as Integer, Timeout as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
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.

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

Parameters:
endpointthe address of a valid endpoint to communicate with
dataa suitably-sized data buffer for either input or output (depending on endpoint)
lengthfor 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.
transferredoutput location for the number of bytes actually transferred.
timeouttimeout (in millseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

The lasterror property is set to:
0 on success (and populates transferred)
kErrorTimeout if the transfer timed out
kErrorPipe if the endpoint halted
kErrorOverflow if the device offered more data, see Packets and overflows
kErrorNoDevice if the device has been disconnected
another error code on other error

LibUSBDeviceMBS.KernelDriverActive(interfaceNumber as Integer) as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Determine if a kernel driver is active on an interface.

If a kernel driver is active, you cannot claim the interface, and libusb will be unable to perform I/O.

This functionality is not available on Windows.

Parameters:
interfaceNumber: the interface to check

Lasterror is set:
0 if no kernel driver is active
1 if a kernel driver is active
kErrorNoDevice if the device has been disconnected
kErrorNotSupported on platforms where the functionality is not available
another error code on other failure

LibUSBDeviceMBS.Open as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Open a device and obtain a device handle.

A handle allows you to perform I/O on the device in question.

Internally, this function adds a reference to the device. This reference is removed during Close().

This is a non-blocking function; no requests are sent over the bus.

The last error to:
0 on success
kErrorNoMemory on memory allocation failure
kErrorAccess if the user has insufficient permissions
kErrorNoDevice if the device has been disconnected
another error code on other failure

LibUSBDeviceMBS.ReleaseInterface(interfaceNumber as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Release an interface previously claimed with ClaimInterface.

You should release all claimed interfaces before closing a device handle.

This is a blocking function. A SET_INTERFACE control request will be sent to the device, resetting interface state to the first alternate setting.

Parameters:
interfaceNumber: the bInterfaceNumber of the previously-claimed interface

The lasterror:
0 on success
kErrorNotFound if the interface was not claimed
kErrorNoDevice if the device has been disconnected
another error code on other failure

LibUSBDeviceMBS.Reset

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Perform a USB port reset to reinitialize a device.

The system will attempt to restore the previous configuration and alternate settings after the reset has completed.

If the reset fails, the descriptors change, or the previous state cannot be restored, the device will appear to be disconnected and reconnected. This means that the device handle is no longer valid (you should close it) and rediscover the device. An error code of kErrorNotFound indicates when this is the case.

This is a blocking function which usually incurs a noticeable delay.

Lasterror is set:
0 on success
kErrorNotFound if re-enumeration is required, or if the device has been disconnected
another error code on other failure

LibUSBDeviceMBS.SetConfiguration(configuration as Integer)

Type Topic Plugin Version macOS Windows Linux iOS Targets
method USB MBS USB Plugin 18.1 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Set the active configuration for a device.

The operating system may or may not have already set an active configuration on the device. It is up to your application to ensure the correct configuration is selected before you attempt to claim interfaces and perform other operations.

If you call this function on a device already configured with the selected configuration, then this function will act as a lightweight device reset: it will issue a SET_CONFIGURATION request using the current configuration, causing most USB-related device state to be reset (altsetting reset to zero, endpoint halts cleared, toggles reset).

You cannot change/reset configuration if your application has claimed interfaces - you should free them with libusb_release_interface() first. You cannot change/reset configuration if other applications or drivers have claimed interfaces.

A configuration value of -1 will put the device in unconfigured state. The USB specifications state that a configuration value of 0 does this, however buggy devices exist which actually have a configuration 0.

You should always use this function rather than formulating your own SET_CONFIGURATION control request. This is because the underlying operating system needs to know when such changes happen.

This is a blocking function.

Parameters:
configuration: the bConfigurationValue of the configuration you wish to activate, or -1 if you wish to put the device in unconfigured state

The lasterror is set to:
0 on success
kErrorNotFound if the requested configuration does not exist
kErrorBusy if interfaces are currently claimed
kErrorNoDevice if the device has been disconnected
another error code on other failure

Next items

The items on this page are in the following plugins: MBS USB Plugin.


The biggest plugin in space...