Platforms to show: All Mac Windows Linux Cross-Platform
Back to LibUSBDeviceMBS class.
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 |
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 |
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:
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. |
timeout | timeout (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 |
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 |
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
Type | Topic | Plugin | Version | macOS | Windows | Linux | iOS | Targets |
method | USB | MBS USB Plugin | 18.1 | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | Desktop, Console & Web |
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 |
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:
RequestType | the request type field for the setup packet |
Request | the request field for the setup packet |
Value | the value field for the setup packet |
Index | the index field for the setup packet |
data | a suitably-sized data buffer for either input or output (depending on direction bits within bmRequestType) |
Length | the length field for the setup packet. The data buffer should be at least this size. |
timeout | timeout (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 |
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 |
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 |
This is a non-blocking function which does not involve any requests being sent to the device.
Parameters:
Index | the 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 |
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 |
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 |
This is a convenience function which formulates the appropriate control message to retrieve the descriptor.
Parameters:
descType | the descriptor type, see libusb_descriptor_type |
descIndex | the index of the descriptor to retrieve |
data | output buffer for descriptor |
length | size 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 |
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 |
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 |
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 |
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:
descIndex | the index of the descriptor to retrieve |
LangID | the 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 |
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:
descIndex | the index of the descriptor to retrieve |
LangID | the language ID for the string descriptor |
data | output buffer for descriptor |
length | size 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 |
Wrapper around GetStringDescriptor(). Uses the first language supported by the device.
Parameters:
descIndex | the 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 |
Wrapper around GetStringDescriptor(). Uses the first language supported by the device.
Parameters:
descIndex | the index of the descriptor to retrieve |
data | output buffer for ASCII string descriptor |
length | size 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 |
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:
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. |
timeout | timeout (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 |
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 |
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 |
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
Type | Topic | Plugin | Version | macOS | Windows | Linux | iOS | Targets |
method | USB | MBS USB Plugin | 18.1 | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | Desktop, Console & Web |
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 |
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
The items on this page are in the following plugins: MBS USB Plugin.