Anp.UsbDeviceDescriptors 1.0.1

UsbDeviceDescriptors

Reads USB descriptors on Windows—Device, Configuration, Interface, Endpoint, and String—via the Win32 IOCTL_USB_GET_DESCRIPTOR_FROM_NODE_CONNECTION control code, and exposes them as strongly‑typed C# structures. Targets .NET Framework 4.8, .NET Standard 2.0, .NET 8.0.

Features

• Strongly‑typed descriptors: DeviceDescriptor, ConfigurationDescriptor, InterfaceDescriptor, EndpointDescriptor, StringDescriptor, plus RawDescriptor for unknown blocks. All implement meaningful ToString() for inspection.
• One‑call read: UsbDescriptorReader.GetDescriptorSet(...) returns a hierarchical UsbDescriptorSet (device → configurations → interfaces → endpoints).
• Selectively include configurations and/or string descriptors with ReadOptions.
• Tolerant string descriptor parsing: a non-fatal bLength mismatch in firmware is logged via UsbDiag.Error and parsing continues. StringDescriptor.HasLengthMismatch and DiagnosticNote expose the anomaly to callers.
• Optional diagnostics channel: subscribe to UsbDiag.Error to receive soft errors (e.g. unreachable string descriptors, length mismatches) without catching exceptions.
• Windows‑only; uses CreateFile/DeviceIoControl and the USB hub IOCTL.
• Synchronous I/O; no additional native dependencies.

Install NuGet

Quick start

using System;
using System.Linq;
using Anp.UsbDeviceDescriptors;

class Program
{
    static void Main()
    {
        // Inputs:
        string parentNodeId = @"USB\ROOT_HUB30\4&17AA0D8F&0"; // example (PnP Device Instance ID of a USB hub)
        uint portIndex = 3;                                     // 1-based port number on that hub

        // Read full tree (device + configurations + strings, default langId = 0x0409 English)
        UsbDescriptorSet set = UsbDescriptorReader.GetDescriptorSet(
            parentNodeId, portIndex, ReadOptions.All /*, langId: 0x0409*/);

        Console.WriteLine(set);

        Console.WriteLine($"VID:PID = 0x{set.DeviceDescriptor.IdVendor:X4}:0x{set.DeviceDescriptor.IdProduct:X4}");
        Console.WriteLine($"Product: {set.ProductString}");

        foreach (var ep in set.EndpointDescriptors)
        {
            Console.WriteLine($"EP 0x{ep.EndpointAddress:X2} ({ep.TransferType}), wMaxPacketSize={ep.MaxPacketSize}");
        }
    }
}

Language IDs & string descriptors

Some devices localize their strings.

• UsbDescriptorReader.GetSupportedLanguageIds(parentNodeId, portIndex) — returns supported LANGIDs (lazy enumerable). Devices with no strings often return an empty set. Strings may be unavailable in low‑power states.
• UsbDescriptorReader.GetStringDescriptor(parentNodeId, portIndex, stringIndex, langId) — reads a specific string descriptor. Index 0 is reserved for the LANGID table. On firmware that reports an incorrect bLength, parsing continues and StringDescriptor.HasLengthMismatch is set; the anomaly is also raised via UsbDiag.Error.

Auto‑select the first available language:

using System.Linq;
using Anp.UsbDeviceDescriptors;

ushort lang = UsbDescriptorReader.GetSupportedLanguageIds(parentNodeId, portIndex).FirstOrDefault(); // 0 if none
var set = UsbDescriptorReader.GetDescriptorSet(parentNodeId, portIndex, ReadOptions.All, lang);

Inputs: Parent ID and Port index

This library reads USB descriptors via Windows API that requires parent info:

• Parent ID — the parent node (USB hub) Device Instance ID. A parent node symbolic name (\??\…) or a full device interface path (\\?\…) is also accepted.
• Port index — the 1‑based port number (bus address) on the parent hub where the target device is connected.

Parent info is exposed by the Pnp Device Discovery library or can be obtained by other means.

API overview

Entry points

• UsbDescriptorReader.GetDescriptorSet(string parentNodeId, uint portIndex, ReadOptions options = ReadOptions.All, ushort langId = 0x0409)
• UsbDescriptorReader.GetSupportedLanguageIds(string parentNodeId, uint portIndex)
• UsbDescriptorReader.GetStringDescriptor(string parentNodeId, uint portIndex, byte stringIndex, ushort langId = 0x0409) — returns a StringDescriptor; check HasLengthMismatch / DiagnosticNote for non-fatal firmware anomalies

Options

[Flags]
public enum ReadOptions
{
    None = 0,
    Configurations = 1,
    Strings = 2,
    All = Configurations | Strings
}

Diagnostics

The library surfaces soft errors (unreachable string descriptors, bLength mismatches, I/O warnings during descriptor set reads) through a static event rather than exceptions, so the rest of the descriptor set can still be populated.

using Anp.UsbDeviceDescriptors.Diagnostics;

// Subscribe before reading
UsbDiag.Error += (_, e) => Console.WriteLine($"[{e.Timestamp}] {e.Source}: {e.Message}");

var set = UsbDescriptorReader.GetDescriptorSet(parentNodeId, portIndex);

UsbError properties: Timestamp, Source (class.method), Message, Exception (may be null).

Each subscriber is isolated — a faulting handler does not prevent other subscribers from receiving the event.

StringDescriptor anomaly properties:

var sd = UsbDescriptorReader.GetStringDescriptor(parentNodeId, portIndex, index: 1);
if (sd.HasLengthMismatch)
    Console.WriteLine(sd.DiagnosticNote); // "bLength=18 does not match actual encoded length=16"

HasLengthMismatch returns true when the device-reported bLength differs from the actual UTF‑16 encoded byte count. DiagnosticNote provides a human-readable explanation; it is null when the descriptor is well-formed.

Build & support

• Targets: .NET Framework 4.8, .NET Standard 2.0, .NET 8.0
• Language: C# 7.3
• Interop: Windows‑only (Win32 CreateFile/DeviceIoControl).

License

MIT — see LICENSE.