Xojo Conferences
MBSOct2019CologneDE

Platforms to show: All Mac Windows Linux Cross-Platform

WinUSBMBS.AbortPipe(PipeID as Integer)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Aborts all of the pending transfers for a pipe. This is a synchronous operation.
Notes:
To reset a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists in a 7-bit address and a direction bit. This parameter corresponds to the EndpointAddress field in the endpoint descriptor.

Lasterror is zero on success and false on failure.

Feedback, Comments & Corrections

WinUSBMBS.Constructor(path as string)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Creates a WinUSB object for the device specified by a device path.
Notes:
Use WindowsDeviceMBS class to find USB devices and their device paths.
Lasterror is set.
On success DeviceHandle and Handle properties are not nil.

When Constructor is called, the policy settings of the interface are reset to the default values.
The Constructor call queries the underlying USB stack for various descriptors and allocates enough memory to store the retrieved descriptor data.
Constructor first retrieves the device descriptor and then gets the associated configuration descriptor. From the configuration descriptor, the call derives the associated interface descriptors and stores them in an array. The interfaces in the array are identified by zero-based indexes. An index value of 0 indicates the first interface (the default interface), a value of 1 indicates the second associated interface, and so on. Constructor parses the default interface descriptor for the endpoint descriptors and caches information such as the associated pipes or state specific data. The handle received in the InterfaceHandle parameter is a pointer to the memory block allocated for the first interface in the array.

If an application wants to use another interface on the device, it must call GetAssociatedInterface, specify the index of the interface, and retrieve a handle to the memory block allocated for the specified interface.

Feedback, Comments & Corrections

WinUSBMBS.ControlTransfer(SetupPacket as WinUSBSetupPacketMBS, Buffer as MemoryBlock) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Transmits control data over a default control endpoint.
Notes:
To send a control request to the entire device or the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

SetupPacket: The 8-byte setup packet of type WinUSBSetupPacketMBS.
Buffer: A buffer that contains the data to transfer. Can be empty.

Returns the actual number of transferred bytes.
Lasterror property is set.

See also:

Feedback, Comments & Corrections

WinUSBMBS.ControlTransfer(SetupPacket as WinUSBSetupPacketMBS, Buffer as String) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Transmits control data over a default control endpoint.
Notes:
To send a control request to the entire device or the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

SetupPacket: The 8-byte setup packet of type WinUSBSetupPacketMBS.
Buffer: A buffer that contains the data to transfer. Can be empty.

Returns the actual number of transferred bytes.
Lasterror property is set.

See also:

Feedback, Comments & Corrections

WinUSBMBS.CurrentAlternateSetting as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: The current alternate interface setting for an interface.
Notes:
To get the current alternate setting in the first (default) interface on the device, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

Lasterror is set. You can set and get the value.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.DeviceSpeed as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Queries device speed.
Notes:
Lasteror is set.
Use constants LowSpeed, HighSpeed and FullSpeed.

Feedback, Comments & Corrections

WinUSBMBS.FlushPipe(PipeID as Integer)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Discards any data that is cached in a pipe. This is a synchronous operation.
Notes:
To reset a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists in a 7-bit address and a direction bit. This parameter corresponds to the EndpointAddress field in the endpoint descriptor.

Lasterror is zero on success and false on failure.

Feedback, Comments & Corrections

WinUSBMBS.GetAssociatedInterface(index as Integer) as WinUSBMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Retrieves a WinUSBMBS object for an associated interface.
Notes:
This is a synchronous operation.

AssociatedInterfaceIndex: An index that specifies the associated interface to retrieve. A value of 0 indicates the first associated interface, a value of 1 indicates the second associated interface, and so on.

Returns new WinUBSMBS object.
The first associated interface is the interface that immediately follows the interface whose handle the WinUsb_Initialize routine retrieves.

Callers of GetAssociatedInterfacecan retrieve only one handle for each interface. If a caller attempts to retrieve more than one handle for the same interface, the routine will fail with an error of ERROR_ALREADY_EXISTS.

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyAllowPartialReads(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether to allow partial reads.
Notes:
The default value is true. To disable set to false.
Disabling AllowPartialReads causes the read requests to fail whenever the device returns more data (on bulk and interrupt IN endpoints) than the caller requested.
Enabling AllowPartialReads causes WinUSB to save or discard the extra data when the device returns more data (on bulk and interrupt IN endpoints) than the caller requested. This behavior is defined by setting the auto flush value.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyAutoClearStall(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether WinUSB resets the pipe in order to automatically clear the stall condition.
Notes:
Data continues to flow on the bulk and interrupt IN endpoints again as soon as a new or a queued transfer arrives on the endpoint. This policy parameter does not affect control pipes.
Disabling AutoClearStall causes all transfers (that arrive to the endpoint after the stalled transfer) to fail until the caller manually resets the endpoint's pipe by calling ResetPipe.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyAutoFlush(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether to use auto flush.
Notes:
The default value is false (zero). To enable auto flush set to true.
auto flush must be used with AllowPartialReads enabled. If AllowPartialReads is TRUE, the value of auto flush determines the action taken by WinUSB when the device returns more data than the caller requested.
Disabling AllowPartialReads causes WinUSB to ignore the auto flush value.
Disabling auto flush with AllowPartialReads enabled causes WinUSB to save the extra data, add the data to the beginning of the caller's next read request, and send it to the caller in the next read operation.
Enabling auto flush with AllowPartialReads enabled causes WinUSB to discard the extra data remaining from the read request.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyIgnoreShortPackets(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Enabling IgnoreShortPackets causes the host controller to not complete a read operation after it receives a short packet.
Notes:
Instead, the host controller completes the operation only after the host has read the specified number of bytes.
Disabling IgnoreShortPackets causes the host controller to complete a read operation when either the host has read the specified number of bytes or the host has received a short packet.
The default value is false. To enable set to true.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyMaximumTransferSize(PipeID as Integer) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Gets the maximum size of a USB transfer supported by WinUSB.
Notes:
This is a read-only policy.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyPipeTransferTimeout(PipeID as Integer) as UInt32
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Specifies the time-out interval.
Notes:
The default value is zero.
The PipeTransferTimeout value specifies the time-out interval, in milliseconds. The host controller cancels transfers that do not complete within the specified time-out interval.
A value of zero (default) indicates that transfers do not time out because the host controller never cancels the transfer.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyRawIO(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether to use Raw IO.
Notes:
The default value is false.
Enabling raw IO causes WinUSB to send data directly to the USB driver stack, bypassing WinUSB's queuing and error handling mechanism.
The buffers that are passed to ReadPipe must be configured by the caller as follows:
  • The buffer length must be a multiple of the maximum endpoint packet size.
  • The length must be less than or equal to the value of PipePolicyMaximumTransferSize.
Disabling raw IO (false) does not impose any restriction on the buffers that are passed to ReadPipe.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyResetPipeOnResume(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether to reset pipe on resume.
Notes:
True indicates that on resume from suspend, WinUSB resets the endpoint before it allows the caller to send new requests to the endpoint.
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.PipePolicyShortPacketTerminate(PipeID as Integer) as boolean
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
property USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Whether the driver sends a zero-length packet at the end of every write request to the host controller.
Notes:
Lasterror is set.
(Read and Write computed property)

Feedback, Comments & Corrections

WinUSBMBS.QueryInterfaceSettings(index as Integer) as WinUSBInterfaceDescriptionMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Retrieves the interface descriptor for the specified alternate interface settings for a particular interface handle.
Notes:
To retrieve the settings of the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

AlternateSettingNumber: A value that indicates which alternate settings to return. A value of 0 indicates the first alternate setting, a value of 1 indicates the second alternate setting, and so on.

Returns WinUSBInterfaceDescriptionMBS object on success or nil on any error.

Feedback, Comments & Corrections

WinUSBMBS.QueryPipe(AlternateInterfaceNumber as Integer, PipeIndex as Integer) as WinUSBPipeInformationMBS
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Retrieves information about the specified endpoint and the associated pipe for an interface.
Notes:
To query a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

AlternateInterfaceNumber: A value that specifies the alternate interface to return the information for.
PipeIndex: A value that specifies the pipe to return information about. This value is not the same as the bEndpointAddress field in the endpoint descriptor. A PipeIndex value of 0 signifies the first endpoint that is associated with the interface, a value of 1 signifies the second endpoint, and so on. PipeIndex must be less than the value in the NumEndpoints field of the interface descriptor.

Returns pipe information or nil on error. Also sets Lasterror property.

The QueryPipe function does not retrieve information about the control pipe.

Each interface on the USB device can have multiple endpoints. To communicate with each of these endpoints, the bus driver creates pipes for each endpoint on the interface. The pipe indices are zero-based. Therefore for n number of endpoints, the pipes' indices are set from n-1. WinUsb_QueryPipe parses the configuration descriptor to get the interface specified by the caller. It searches the interface descriptor for the endpoint descriptor associated with the caller-specified pipe. If the endpoint is found, the function populates a WinUSBPipeInformationMBS object with information from the endpoint descriptor.

Feedback, Comments & Corrections

WinUSBMBS.ReadPipeMemory(PipeID as Integer, BufferLength as Integer) as Memoryblock
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Reads data from the specified pipe.
Notes:
To read a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: PipeID corresponds to the EndpointAddress field in the endpoint descriptor. For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. In the EndpointAddress field, Bit 7 indicates the direction of the endpoint: 0 for OUT; 1 for IN.
BufferLength: The maximum number of bytes to read.

Returns memoryblock with the data read. This may be shorter than BufferLength.
Lasterror is set.

Lasterror is 0 if the operation succeeds. Otherwise, lasterror has the Windows error code.

If the data returned by the device is greater than a maximum transfer length, WinUSB divides the request into smaller requests of maximum transfer length and submits them serially. If the transfer length is not a multiple of the endpoint's maximum packet size (retrievable through the WinUSBPipeInformationMBS class's MaximumPacketSize member), WinUSB increases the size of the transfer to the next multiple of MaximumPacketSize.
USB packet size does not factor into the transfer for a read request. If the device responds with a packet that is too large for the client buffer, the behavior of the read request corresponds to the type of policy set on the pipe. If policy type for the pipe is ALLOW_PARTIAL_READS, WinUSB adds the remaining data to the beginning of the next transfer. If ALLOW_PARTIAL_READS is not set, the read request fails. For more information about policy types, see WinUSB Functions for Pipe Policy Modification.

When no data is available in the endpoint (pipe is empty), ReadPipe does not return until there is data in the pipe. If an error condition occurs or the application-specified timeout expires, ReadPipe always returns false. To determine the actual reason for that return value, always check LastError. For example, in these cases the GetLastError error value indicates the actual reason:
If the application specified a timeout value in the pipe policy and that timeout expires, ReadPipe returns false and LastError is ERROR_SEM_TIMEOUT.
If an error condition occurs while reading data from the pipe, ReadPipe returns false and LastError is ERROR_GEN_FAILURE.

Feedback, Comments & Corrections

WinUSBMBS.ReadPipePacket(PipeID as Integer, MaxSize as Integer = 1024) as Memoryblock
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.5 No Yes No Yes, Windows only No
Function: Reads a data packet.
Notes: We developed this function for a client, so it's probably useless for everyone else.

Feedback, Comments & Corrections

WinUSBMBS.ReadPipeString(PipeID as Integer, BufferLength as Integer) as string
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Reads data from the specified pipe.
Notes:
To read a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: PipeID corresponds to the EndpointAddress field in the endpoint descriptor. For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. In the EndpointAddress field, Bit 7 indicates the direction of the endpoint: 0 for OUT; 1 for IN.
BufferLength: The maximum number of bytes to read.

Returns string with the data read. This may be shorter than BufferLength.
Lasterror is set.

Lasterror is 0 if the operation succeeds. Otherwise, lasterror has the Windows error code.

If the data returned by the device is greater than a maximum transfer length, WinUSB divides the request into smaller requests of maximum transfer length and submits them serially. If the transfer length is not a multiple of the endpoint's maximum packet size (retrievable through the WinUSBPipeInformationMBS class's MaximumPacketSize member), WinUSB increases the size of the transfer to the next multiple of MaximumPacketSize.
USB packet size does not factor into the transfer for a read request. If the device responds with a packet that is too large for the client buffer, the behavior of the read request corresponds to the type of policy set on the pipe. If policy type for the pipe is ALLOW_PARTIAL_READS, WinUSB adds the remaining data to the beginning of the next transfer. If ALLOW_PARTIAL_READS is not set, the read request fails. For more information about policy types, see WinUSB Functions for Pipe Policy Modification.

When no data is available in the endpoint (pipe is empty), ReadPipe does not return until there is data in the pipe. If an error condition occurs or the application-specified timeout expires, ReadPipe always returns false. To determine the actual reason for that return value, always check LastError. For example, in these cases the GetLastError error value indicates the actual reason:
If the application specified a timeout value in the pipe policy and that timeout expires, ReadPipe returns false and LastError is ERROR_SEM_TIMEOUT.
If an error condition occurs while reading data from the pipe, ReadPipe returns false and LastError is ERROR_GEN_FAILURE.

Feedback, Comments & Corrections

WinUSBMBS.ResetPipe(PipeID as Integer)
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Resets the data toggle and clears the stall condition on a pipe.
Notes:
To reset a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists in a 7-bit address and a direction bit. This parameter corresponds to the EndpointAddress field in the endpoint descriptor.

Lasterror is zero on success and false on failure.

Feedback, Comments & Corrections

WinUSBMBS.WritePipe(PipeID as Integer, Buffer as MemoryBlock) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Writes data to a pipe.
Notes:
To write to a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: PipeID corresponds to the EndpointAddress field in the endpoint descriptor. For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. In the bEndpointAddress field, Bit 7 indicates the direction of the endpoint: 0 for OUT; 1 for IN.
Buffer: A buffer that contains the data to write.

Returns the actual number of bytes that were written to the pipe.
Lasterror is set. Zero for success.

To create a write request, your the application must allocate a buffer, fill it with the data that you want to write to the device, and send the buffer to the host controller by calling WritePipe.
The following restrictions apply to the size of the buffer if RAW_IO is set:
  • The buffer length must be a multiple of the maximum endpoint packet size.
  • The length must be less than or equal to the value of MAXIMUM_TRANSFER_SIZE retrieved by GetPipePolicy.

There are no restrictions on the size of the buffer if RAW_IO is not set as the pipe's policy type. If the size of the buffer is greater than the maximum transfer length reported by MAXIMUM_TRANSFER_SIZE, WinUSB divides the request into smaller requests and submits them serially to the host controller.
A write request that contains zero-length data is forwarded down the USB stack.

See also:

Feedback, Comments & Corrections

WinUSBMBS.WritePipe(PipeID as Integer, Buffer as String) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.2 No Yes No Yes, Windows only No
Function: Writes data to a pipe.
Notes:
To write to a pipe associated with an endpoint in the first interface, use the WinUSBMBS object created with constructor. For all other interfaces, use the WinUSBMBS objects to the target interface, retrieved by GetAssociatedInterface.

PipeID: PipeID corresponds to the EndpointAddress field in the endpoint descriptor. For information about the layout of this field, see Table 9-13 in "Universal Serial Bus Specification Revision 2.0" at USB Technology. In the bEndpointAddress field, Bit 7 indicates the direction of the endpoint: 0 for OUT; 1 for IN.
Buffer: A buffer that contains the data to write.

Returns the actual number of bytes that were written to the pipe.
Lasterror is set. Zero for success.

To create a write request, your the application must allocate a buffer, fill it with the data that you want to write to the device, and send the buffer to the host controller by calling WritePipe.
The following restrictions apply to the size of the buffer if RAW_IO is set:
  • The buffer length must be a multiple of the maximum endpoint packet size.
  • The length must be less than or equal to the value of MAXIMUM_TRANSFER_SIZE retrieved by GetPipePolicy.

There are no restrictions on the size of the buffer if RAW_IO is not set as the pipe's policy type. If the size of the buffer is greater than the maximum transfer length reported by MAXIMUM_TRANSFER_SIZE, WinUSB divides the request into smaller requests and submits them serially to the host controller.
A write request that contains zero-length data is forwarded down the USB stack.

See also:

Feedback, Comments & Corrections

WinUSBMBS.WritePipePacket(PipeID as Integer, Buffer as MemoryBlock) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.5 Yes Yes Yes Yes No
Function: Sends data packet.
Notes: We developed this function for a client, so it's probably useless for everyone else.

See also:

Feedback, Comments & Corrections

WinUSBMBS.WritePipePacket(PipeID as Integer, Buffer as String) as Integer
Type Topic Plugin Version macOS Windows Linux Console & Web iOS
method USB MBS USB Plugin 12.5 Yes Yes Yes Yes No
Function: Sends data packet.
Notes: We developed this function for a client, so it's probably useless for everyone else.

See also:

Feedback, Comments & Corrections

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

The biggest plugin in space...




Links
MBS Xojo blog