---
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-16T11:50:38.580755+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "2043cd8e3c0f04ef"
---

# Documentation: DTS.Common.WINUSBConnection

## 1. Purpose

This module provides USB connectivity abstractions within the `DTS.Common.WINUSBConnection` namespace. It contains two concrete implementations of the `IConnection` interface: `CDCUSBConnection`, which wraps a standard `System.IO.Ports.SerialPort` for CDC (Communications Device Class) USB devices, and `WINUSBConnection`, which provides low-level communication via the native `winusb.dll` API for custom WinUSB devices. Additionally, it defines the internal P/Invoke signatures and data structures required to interact with the Windows WinUSB driver stack.

## 2. Public Interface

### Class: `CDCUSBConnection`
Implements `IConnection`. Represents a USB device connection via a virtual COM port (CDC).

*   **`void Create(string connectString, string hostIPAddress)`**
    *   Parses the `connectString` to match against registry keys in `RegKeys`. If a match is found, it retrieves the `PortName` from the registry (`Device Parameters` subkey) and configures the internal `SerialPort` instance.
*   **`IAsyncResult BeginConnect(AsyncCallback cb, object state)`**
    *   Initiates an asynchronous connection. Queues the connection logic to the thread pool.
*   **`void EndConnect(IAsyncResult ar)`**
    *   Completes the asynchronous connection. Configures the serial port (BaudRate, DataBits, etc.) and calls `_comPort.Open()`. Sets `Connected` to `true`.
*   **`IAsyncResult BeginSend(byte[] buffer, int offset, int size, AsyncCallback cb, object state)`**
    *   Initiates an asynchronous send operation.
*   **`int EndSend(IAsyncResult ar)`**
    *   Completes the send operation. Writes data to the internal `_comPort` using `_comPort.Write`.
*   **`Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)`**
    *   Task-based asynchronous wrapper for `BeginSend`/`EndSend`.
*   **`IAsyncResult BeginReceive(byte[] buffer, int offset, int size, AsyncCallback cb, object state)`**
    *   Initiates an asynchronous receive operation.
*   **`int EndReceive(IAsyncResult ar)`**
    *   Completes the receive operation. Reads data from `_comPort`. **Note:** This method blocks in a loop (`Thread.Sleep(1)`) until at least one byte is read.
*   **`IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback cb, Object state)`**
    *   Initiates an asynchronous disconnect.
*   **`void EndDisconnect(IAsyncResult ar)`**
    *   Completes the disconnect. Closes and disposes the internal `_comPort`.
*   **Properties**
    *   `bool Connected`: Gets the current connection state.
    *   `string ConnectString`: Returns the device pathname.
    *   `IList<string> RegKeys`: Static property that lazily loads registry keys for the device from `SYSTEM\CurrentControlSet\Enum\USB\`.

### Class: `WINUSBConnection`
Implements `IConnection`. Represents a USB device connection using the native WinUSB driver.

*   **`void Create(string connectString, string hostIPAddress)`**
    *   Stores the `connectString` in the `ConnectString` property.
*   **`IAsyncResult BeginConnect(AsyncCallback cb, object state)`**
    *   Initiates an asynchronous connection. Throws `NotConnectedException` if already connected.
*   **`void EndConnect(IAsyncResult ar)`**
    *   Completes the connection. Instantiates a new `WinUsbDevice`, retrieves a device handle via `GetDeviceHandle`, and initializes the device via `InitializeDevice`. Uses a mutex (`_usbConnectionMutex`) to synchronize access.
*   **`IAsyncResult BeginSend(byte[] buffer, int offset, int size, AsyncCallback cb, object state)`**
    *   Initiates an asynchronous send. Validates buffer parameters.
*   **`int EndSend(IAsyncResult ar)`**
    *   Completes the send. Checks `MyDevInfo.UseHybridBulkIntMode`. If true, calls `SendViaInterruptTransfer`; otherwise, calls `SendViaBulkTransfer`.
*   **`Task<int> SendAsync(byte[] sendBuffer, int bufferStartOffset, int bufferSizeToSend)`**
    *   Task-based asynchronous wrapper for `BeginSend`/`EndSend`.
*   **`IAsyncResult BeginReceive(byte[] buffer, int offset, int size, AsyncCallback cb, object state)`**
    *   Initiates an asynchronous receive.
*   **`int EndReceive(IAsyncResult ar)`**
    *   Completes the receive. Reads data via `ReadViaBulkTransfer`. Blocks in a loop (`Thread.Sleep(1)`) until bytes are read. Returns 0 if the connection fails or closes.
*   **`IAsyncResult BeginDisconnect(bool reuseSocket, AsyncCallback cb, Object state)`**
    *   Initiates an asynchronous disconnect.
*   **`void EndDisconnect(IAsyncResult ar)`**
    *   Completes the disconnect. Calls `DisposeSliceDev` to release the WinUSB handle.
*   **Properties**
    *   `bool Connected`: Gets the current connection state.
    *   `string ConnectString`: Gets the device pathname.

### Internal Class: `WinUsbDevice` (Partial)
Defines P/Invoke signatures and structures for `winusb.dll`.

*   **Structs**: `USBConfigurationDescriptor`, `USBInterfaceDescriptor`, `WinUSBPipeInformation`, `WinUSBSetupPacket`.
*   **Enums**: `PolicyType`, `USBDPipeTypes`, `USBDeviceSpeeds`.
*   **Methods**: `WinUsb_Initialize`, `WinUsb_Free`, `WinUsb_ControlTransfer`, `WinUsb_ReadPipe`, `WinUsb_WritePipe`, `WinUsb_QueryPipe`, `WinUsb_SetPipePolicy`, etc.

## 3. Invariants

*   **Registry Dependency (CDCUSBConnection)**: The `CDCUSBConnection` requires the device to be registered under `SYSTEM\CurrentControlSet\Enum\USB\` with a Vendor ID of `VID_1CB9` and Product ID of `PID_001A`. The `Create` method cannot resolve the port name if these registry keys are missing.
*   **Thread Safety (WINUSBConnection)**: The `WINUSBConnection.EndConnect` and `DisposeSliceDev` methods rely on a named Mutex (`"USBConnection"`) to prevent race conditions during device initialization and disposal.
*   **Disposal State**: Both connection classes track `Disposed` and `Disposing` flags. Methods generally do not proceed if `Disposed` is true.
*   **APM Pattern**: Both classes implement the Asynchronous Programming Model (APM) using internal `IAsyncResult` implementations (`UsbRecAsyncResult` and `WinUSBRecAsyncResult`). Callbacks are invoked via `ThreadPool.QueueUserWorkItem`.

## 4. Dependencies

### Internal Dependencies
*   `DTS.Common.Interface.Connection`: Implements `IConnection`.
*   `DTS.Common.DASResource`: Uses localized strings for exception messages (e.g., `Strings.CDCUSBConnection_BeginConnect_Err1`).
*   `DTS.Common.Utilities.Logging`: Uses `APILogger` for logging exceptions and status messages.
*   `DTS.Common.USBFramework`: Uses `DeviceManagement` class (in `WINUSBConnection`).
*   `DTS.Common.Classes.Connection`: Uses `NotConnectedException`.

### External Dependencies
*   `System.IO.Ports`: Used by `CDCUSBConnection` for `SerialPort`.
*   `System.Runtime.InteropServices`: Used for P/Invoke attributes.
*   `Microsoft.Win32`: Used for registry access (`RegistryKey`, `SafeFileHandle`).
*   `winusb.dll`: Native Windows DLL imported by `WinUsbDevice`.

## 5. Gotchas

*   **Blocking Async Reads**: The `EndReceive` methods in both `CDCUSBConnection` and `WINUSBConnection` contain `while` loops that sleep (`Thread.Sleep(1)`) if zero bytes are read. This effectively makes the "asynchronous" operation blocking and consumes a thread pool thread while waiting for data.
*   **Recursive Comment**: The `Create(string connectString)` method in both connection classes contains a commented-out line `//Create(connectString);` with a note "this is recursive!". This suggests a historical bug or confusion regarding method overloads.
*   **Empty Soft Disconnect**: `SoftConnect` and `SoftDisconnect` methods are implemented but empty. The comments explicitly state they do nothing because there is no soft disconnect option implemented.
*   **Hardcoded Device IDs**: `CDCUSBConnection` hardcodes `DTS_VENDOR_ID` (0x1CB9) and `DTS_TSR2_CDCUSB_PRODUCT_ID_STR` ("PID_001A"). It will not work with other USB devices.
*   **Partial Class Source**: `WinUsbDevice` is defined as `internal sealed partial class`. The logic for `GetDeviceHandle`, `InitializeDevice`, `SendViaBulkTransfer`, etc., is referenced in `WINUSBConnection` but is **not present in the provided source files** (likely in another file part of the partial class definition).
*   **Hybrid Mode Logic**: `WINUSBConnection.EndSend` switches between interrupt and bulk transfers based on a boolean `UseHybridBulkIntMode` located on a `MyDevInfo` object. The definition of `MyDevInfo` is not visible in the provided source.