--- source_files: - Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/WINUSBDeviceApi.cs - Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/CDCUSBConnection.cs - Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/WINUSBConnection.cs generated_at: "2026-04-17T15:37:40.541814+00:00" model: "zai-org/GLM-5-FP8" schema_version: 1 sha256: "ead3f24c8ac15de2" --- # USB Connection Module Documentation ## 1. Purpose This module provides USB connectivity for DTS hardware devices through two distinct implementations: `CDCUSBConnection` for CDC (Communications Device Class) USB devices that present as virtual serial ports, and `WINUSBConnection` for devices using the WinUSB driver for direct bulk/interrupt transfers. Both classes implement the `IConnection` interface, providing a unified async communication pattern (Begin/End and Task-based async) for sending and receiving data. The module also includes `WinUsbDevice` (partial class in `WINUSBDeviceApi.cs`) which provides low-level P/Invoke bindings to the Windows WinUSB API. --- ## 2. Public Interface ### CDCUSBConnection (CDCUSBConnection.cs) A connection class for CDC USB devices that uses `System.IO.Ports.SerialPort` for communication. **Properties:** - `bool IsSoftDisconnected { get; }` - Returns whether the device is soft-disconnected (always `false` for this implementation). - `bool Connected { get; }` - Returns the current connection state. - `string ConnectString { get; }` - Returns the device pathname. - `string PortName { get; set; }` - The serial port name (e.g., "COM3"). - `System.Net.Sockets.SocketFlags Flags { get; set; }` - Socket flags (purpose unclear from source). - `static IList RegKeys { get; }` - Registry keys for device discovery. **Constants:** - `const int DTS_VENDOR_ID = 0x1CB9` - `const string DTS_VENDOR_ID_STR = "VID_1CB9"` - `const string DTS_TSR2_CDCUSB_PRODUCT_ID_STR = "PID_001A"` **Methods:** - `void Create(string connectString, string hostIPAddress)` - Parses the connect string to extract the port name from registry. - `IAsyncResult BeginConnect(AsyncCallback cb, object state)` - Begins an async connection attempt. - `void EndConnect(IAsyncResult ar)` - Completes the connection; configures and opens the serial port with default settings (9600 baud, 8 data bits, no parity, one stop bit). - `IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback cb, Object state)` - Begins an async disconnect. - `void EndDisconnect(IAsyncResult ar)` - Closes and disposes the serial port. - `IAsyncResult BeginSend(byte[] buffer, int offset, int size, AsyncCallback cb, object state)` - Begins an async send operation. - `int EndSend(IAsyncResult ar)` - Completes the send; writes data to the serial port. - `Task SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)` - Task-based async send wrapper. - `IAsyncResult BeginReceive(byte[] buffer, int offset, int size, AsyncCallback cb, object state)` - Begins an async receive operation. - `int EndReceive(IAsyncResult ar)` - Completes the receive; blocks until data is available. - `void Dispose()` - Disposes the connection. - `void SoftConnect()` - No-op (empty body). - `void SoftDisconnect()` - No-op (empty body). - `double GetCurrentUploadRate()` - Returns `0D`. - `double GetCurrentDownloadRate()` - Returns `0D`. - `string GetConnectionData()` - Returns empty string. **Events:** - `event EventHandler OnDisconnected` - Event for disconnection notification (never raised in source). **Not Supported:** - `BeginAccept`, `EndAccept`, `Listen`, `Bind` - Throw `NotSupportedException`. --- ### WINUSBConnection (WINUSBConnection.cs) A connection class for WinUSB devices using direct USB transfers via the WinUSB API. **Properties:** - `bool IsSoftDisconnected { get; }` - Returns whether the device is soft-disconnected (always `false` for this implementation). - `bool Connected { get; }` - Returns the current connection state. - `string ConnectString { get; }` - Returns the device connection string. - `System.Net.Sockets.SocketFlags Flags { get; set; }` - Socket flags (purpose unclear from source). **Methods:** - `void Create(string connectString, string hostIPAddress)` - Stores the connect string. - `IAsyncResult BeginConnect(AsyncCallback cb, object state)` - Begins an async connection; validates not already connected. - `void EndConnect(IAsyncResult ar)` - Completes the connection; creates `WinUsbDevice` instance, gets device handle, and initializes device. - `IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback cb, Object state)` - Begins an async disconnect. - `void EndDisconnect(IAsyncResult ar)` - Disposes the `WinUsbDevice` via `DisposeSliceDev()`. - `IAsyncResult BeginSend(byte[] buffer, int offset, int size, AsyncCallback cb, object state)` - Begins an async send; validates connection and parameters. - `int EndSend(IAsyncResult ar)` - Completes the send; uses `SendViaInterruptTransfer` or `SendViaBulkTransfer` based on `MyDevInfo.UseHybridBulkIntMode`. - `Task SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)` - Task-based async send wrapper. - `IAsyncResult BeginReceive(byte[] buffer, int offset, int size, AsyncCallback cb, object state)` - Begins an async receive. - `int EndReceive(IAsyncResult ar)` - Completes the receive; uses `ReadViaBulkTransfer` with a polling loop. - `void Dispose()` - Disposes the connection and device management resources. - `void SoftConnect()` - No-op (empty body). - `void SoftDisconnect()` - No-op (empty body). - `double GetCurrentUploadRate()` - Returns `0D`. - `double GetCurrentDownloadRate()` - Returns `0D`. - `string GetConnectionData()` - Returns empty string. **Events:** - `event EventHandler OnDisconnected` - Event for disconnection notification (never raised in source). **Not Supported:** - `BeginAccept`, `EndAccept`, `Listen`, `Bind` - Throw `NotSupportedException`. **Nested Classes:** - `WinUSBRecAsyncResult` - Implements `IAsyncResult` with additional `Buffer`, `Offset`, `Size` properties. --- ### WinUsbDevice (WINUSBDeviceApi.cs) - Internal Partial Class Low-level P/Invoke bindings to `winusb.dll`. **Constants:** - `const uint DEVICE_SPEED = 1` - `const byte USB_ENDPOINT_DIRECTION_MASK = 0x80` **Enums:** - `PolicyType` - Pipe policy types: `ShortPacketTerminate`, `AutoClearStall`, `PipeTransferTimeout`, `IgnoreShortPackets`, `AllowPartialReads`, `AutoFlush`, `RawIO`. - `USBDPipeTypes` - Pipe types: `UsbdPipeTypeControl`, `UsbdPipeTypeIsochronous`, `UsbdPipeTypeBulk`, `UsbdPipeTypeInterrupt`. - `USBDeviceSpeeds` - Device speeds: `UsbLowSpeed = 1`, `UsbFullSpeed`, `UsbHighSpeed`. **Structs:** - `USBConfigurationDescriptor` - USB configuration descriptor with fields: `bLength`, `bDescriptorType`, `wTotalLength`, `bNumInterfaces`, `bConfigurationValue`, `iConfiguration`, `bmAttributes`, `MaxPower`. - `USBInterfaceDescriptor` - USB interface descriptor with fields: `bLength`, `bDescriptorType`, `bInterfaceNumber`, `bAlternateSetting`, `bNumEndpoints`, `bInterfaceClass`, `bInterfaceSubClass`, `bInterfaceProtocol`, `iInterface`. - `WinUSBPipeInformation` - Pipe information with fields: `PipeTypes`, `PipeId`, `MaximumPacketSize`, `Interval`. - `WinUSBSetupPacket` - Setup packet for control transfers with fields: `RequestType`, `Request`, `Value`, `Index`, `Length`. **P/Invoke Functions (all from `winusb.dll`):** - `WinUsb_ControlTransfer(IntPtr interfaceHandle, WinUSBSetupPacket setupPacket, byte[] buffer, uint bufferLength, ref uint lengthTransferred, IntPtr overlapped)` - `WinUsb_Free(IntPtr interfaceHandle)` - `WinUsb_Initialize(SafeFileHandle deviceHandle, ref IntPtr interfaceHandle)` - `WinUsb_QueryDeviceInformation(IntPtr interfaceHandle, uint informationType, ref uint bufferLength, ref byte buffer)` - `WinUsb_QueryInterfaceSettings(IntPtr interfaceHandle, byte alternateInterfaceNumber, ref USBInterfaceDescriptor usbAltInterfaceDescriptor)` - `WinUsb_QueryPipe(IntPtr interfaceHandle, byte alternateInterfaceNumber, byte pipeIndex, ref WinUSBPipeInformation pipeInformation)` - `WinUsb_ReadPipe(IntPtr interfaceHandle, byte pipeId, byte[] buffer, uint bufferLength, ref uint lengthTransferred, IntPtr overlapped)` - `WinUsb_SetPipePolicy(IntPtr interfaceHandle, byte pipeId, uint policyType, uint valueLength, ref byte Value)` - For byte policy values. - `WinUsb_SetPipePolicy1(IntPtr interfaceHandle, byte pipeId, uint policyType, uint valueLength, ref uint Value)` - For `uint` policy values (alias for `WinUsb_SetPipePolicy`). - `WinUsb_WritePipe(IntPtr interfaceHandle, Byte pipeId, byte[] buffer, uint bufferLength, ref uint lengthTransferred, IntPtr overlapped)` --- ### UsbRecAsyncResult (CDCUSBConnection.cs) Helper class implementing `IAsyncResult` for async operations. **Properties:** - `object AsyncState { get; set; }` - `WaitHandle AsyncWaitHandle { get; set; }` - `bool CompletedSynchronously { get; set; }` - `bool IsCompleted { get; set; }` - `byte[] buffer { get; set; }` - `int Offset { get; set; }` - `int Size { get; set; }` --- ## 3. Invariants 1. **Connection State Consistency**: `_Connected`/`Connected` must be `false` when `_sliceDev`/`_comPort` is `null` or disposed. 2. **Single Connection**: `WINUSBConnection.BeginConnect` throws `NotConnectedException` if already connected (`_sliceDev != null || Connected`). 3. **Thread Safety**: `WINUSBConnection` uses a `Mutex` named `"USBConnection"` to protect device initialization and disposal operations. 4. **Dispose Guard**: Both connection classes use `Disposed` and `Disposing` flags to prevent double-disposal. 5. **Parameter Validation**: `BeginSend` and `BeginReceive` validate that `buffer` is not null/empty