DP44/docs/ai/Common/DTS.Common.IConnection/USBConnection/WINUSBConnection.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/WINUSBDeviceApi.cs Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/CDCUSBConnection.cs Common/DTS.Common.IConnection/USBConnection/WINUSBConnection/WINUSBConnection.cs	2026-04-17T15:37:40.541814+00:00	zai-org/GLM-5-FP8	1	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<string> 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<int> 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<int> 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