noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
DP44/enriched-partialglm/Common/DTS.Common.IConnection/USBConnection/USBFramework.md
noisedestroyers bc3ac1d4c9 init
2026-04-17 14:55:32 -04:00

13 KiB
Raw Permalink Blame History

source_files, generated_at, model, schema_version, sha256
source_files generated_at model schema_version sha256
Common/DTS.Common.IConnection/USBConnection/USBFramework/FileIODeclarations.cs
Common/DTS.Common.IConnection/USBConnection/USBFramework/HIDDeclarations.cs
Common/DTS.Common.IConnection/USBConnection/USBFramework/DeviceManagementDeclarations.cs
Common/DTS.Common.IConnection/USBConnection/USBFramework/DeviceManagement.cs
2026-04-16T11:51:16.904126+00:00 zai-org/GLM-5-FP8 1 8939bee008e13a9a

USB Framework Module Documentation

1. Purpose

This module provides a .NET wrapper around Windows Win32 APIs for USB device communication and management. It enables applications to discover, monitor, and interact with HID-class USB devices through P/Invoke declarations for kernel32.dll, hid.dll, setupapi.dll, user32.dll, and advapi32.dll. The module handles device enumeration by GUID, device arrival/removal notifications, and low-level file I/O operations required for USB device communication.

2. Public Interface

FileIODeclarations Class

Namespace: DTS.Common.USBFramework

A container for Win32 file I/O P/Invoke declarations.

Constants:

  • GENERIC_READ (uint): 0x80000000
  • GENERIC_WRITE (uint): 0x40000000
  • FILE_SHARE_READ (uint): 0x00000001
  • FILE_SHARE_WRITE (uint): 0x00000002
  • FILE_FLAG_OVERLAPPED (uint): 0x40000000
  • INVALID_HANDLE_VALUE (int): -1
  • OPEN_EXISTING (short): 3
  • WAIT_TIMEOUT (int): 0x102
  • WAIT_OBJECT_0 (uint): 0
  • WAIT_FAILED (uint): 0xFFFFFFFF
  • WAIT_ABANDONED (uint): 0x00000080
  • FSCTL_SET_COMPRESSION (int): 0x9C040

Structures:

  • OVERLAPPED - Sequential layout structure with fields: Internal, InternalHigh, Offset, OffsetHigh, hEvent (all int)
  • SECURITY_ATTRIBUTES - Sequential layout structure with fields: nLength, lpSecurityDescriptor, bInheritHandle (all int)

Static Methods (DllImport kernel32.dll):

  • int CancelIo(int hFile)
  • int CloseHandle(int hObject)
  • int CreateEvent(ref SECURITY_ATTRIBUTES SecurityAttributes, int bManualReset, int bInitialState, string lpName)
  • int CreateFile(string lpFileName, uint dwDesiredAccess, uint dwShareMode, ref SECURITY_ATTRIBUTES lpSecurityAttributes, int dwCreationDisposition, uint dwFlagsAndAttributes, int hTemplateFile)
  • int GetLastError()
  • int ReadFile(int hFile, ref byte lpBuffer, int nNumberOfBytesToRead, ref int lpNumberOfBytesRead, int lpOverlapped)
  • uint WaitForSingleObject(int hHandle, int dwMilliseconds)
  • int WriteFile(int hFile, ref byte lpBuffer, int nNumberOfBytesToWrite, ref int lpNumberOfBytesWritten, int lpOverlapped)
  • int DeviceIoControl(IntPtr hDevice, int dwIoControlCode, ref short lpInBuffer, int nInBufferSize, IntPtr lpOutBuffer, int nOutBufferSize, ref int lpBytesReturned, IntPtr lpOverlapped)

FileIO Class

Namespace: DTS.Common.USBFramework

Alternative file I/O declarations using SafeFileHandle.

Constants:

  • FILE_ATTRIBUTE_NORMAL (short): 0x80
  • FILE_FLAG_OVERLAPPED (int): 0x40000000
  • FILE_SHARE_READ (short): 0x1
  • FILE_SHARE_WRITE (short): 0x2
  • GENERIC_READ (uint): 0x80000000
  • GENERIC_WRITE (uint): 0x40000000
  • INVALID_HANDLE_VALUE (int): -1
  • OPEN_EXISTING (short): 3

Structure:

  • SECURITY_ATTRIBUTES - Sequential layout with nLength (int), lpSecurityDescriptor (IntPtr), bInheritHandle (int)

Static Methods (DllImport kernel32.dll):

  • bool CloseHandle(SafeFileHandle hObject)
  • SafeFileHandle CreateFile(string lpFileName, uint dwDesiredAccess, int dwShareMode, ref SECURITY_ATTRIBUTES lpSecurityAttributes, int dwCreationDisposition, int dwFlagsAndAttributes, int hTemplateFile)

HIDDeclarations Class

Namespace: DTS.DASLib.Connection.USBFramework (Note: different namespace)

A container for HID device P/Invoke declarations.

Constants:

  • HidP_Input (short): 0
  • HidP_Output (short): 1
  • HidP_Feature (short): 2

Structures:

  • HIDD_ATTRIBUTES - Fields: Size (int), VendorID (short), ProductID (short), VersionNumber (short)
  • HIDP_CAPS - Fields: Usage, UsagePage, InputReportByteLength, OutputReportByteLength, FeatureReportByteLength, Reserved[17], NumberLinkCollectionNodes, NumberInputButtonCaps, NumberInputValueCaps, NumberInputDataIndices, NumberOutputButtonCaps, NumberOutputValueCaps, NumberOutputDataIndices, NumberFeatureButtonCaps, NumberFeatureValueCaps, NumberFeatureDataIndices
  • HidP_Value_Caps - Extensive structure with fields for usage page, report ID, bit field, link collection, logical/physical min/max, usage min/max, string min/max, designator min/max, data index min/max, and multiple reserved fields

Static Methods (DllImport hid.dll):

  • bool HidD_FlushQueue(int HidDeviceObject)
  • bool HidD_FreePreparsedData(ref IntPtr PreparsedData)
  • int HidD_GetAttributes(int HidDeviceObject, ref HIDD_ATTRIBUTES Attributes)
  • bool HidD_GetFeature(int HidDeviceObject, ref byte lpReportBuffer, int ReportBufferLength)
  • bool HidD_GetInputReport(int HidDeviceObject, ref byte lpReportBuffer, int ReportBufferLength)
  • void HidD_GetHidGuid(ref System.Guid HidGuid)
  • bool HidD_GetNumInputBuffers(int HidDeviceObject, ref int NumberBuffers)
  • bool HidD_GetPreparsedData(int HidDeviceObject, ref IntPtr PreparsedData)
  • bool HidD_SetFeature(int HidDeviceObject, ref byte lpReportBuffer, int ReportBufferLength)
  • bool HidD_SetNumInputBuffers(int HidDeviceObject, int NumberBuffers)
  • bool HidD_SetOutputReport(int HidDeviceObject, ref byte lpReportBuffer, int ReportBufferLength)
  • int HidP_GetCaps(IntPtr PreparsedData, ref HIDP_CAPS Capabilities)
  • int HidP_GetValueCaps(short ReportType, ref byte ValueCaps, ref short ValueCapsLength, IntPtr PreparsedData)

DeviceManagementDeclarations Class

Namespace: DTS.Common.USBFramework

A container for device management P/Invoke declarations.

Constants:

  • Device event constants: DBT_DEVICEARRIVAL (0x8000), DBT_DEVICEREMOVECOMPLETE (0x8004), DBT_DEVTYP_DEVICEINTERFACE (5), DBT_DEVTYP_HANDLE (6)
  • Notification constants: DEVICE_NOTIFY_ALL_INTERFACE_CLASSES (4), DEVICE_NOTIFY_SERVICE_HANDLE (1), DEVICE_NOTIFY_WINDOW_HANDLE (0), WM_DEVICECHANGE (0x219)
  • Error constants: ERROR_INSUFFICIENT_BUFFER (122), NO_ERROR (0), ERROR_NO_MORE_ITEMS (259)
  • SetupAPI flags: DIGCF_PRESENT (0x00000002), DIGCF_DEVICEINTERFACE (0x00000010), DIGCF_ALLCLASSES (0x00000004)
  • Registry property constants: SPDRP_FRIENDLYNAME, SPDRP_DEVICEDESC, SPDRP_DRIVER

Structures:

  • DEV_BROADCAST_DEVICEINTERFACE - Fields: dbcc_size, dbcc_devicetype, dbcc_reserved, dbcc_classguid (Guid), dbcc_name (string, SizeConst=400)
  • DEV_BROADCAST_DEVICEINTERFACE_1 - Class variant with dbcc_classguid as byte[16] and dbcc_name as char[255]
  • DEV_BROADCAST_HANDLE - Fields: dbch_size, dbch_devicetype, dbch_reserved, dbch_handle, dbch_hdevnotify
  • DEV_BROADCAST_HDR - Fields: dbch_size, dbch_devicetype, dbch_reserved
  • SP_DEVICE_INTERFACE_DATA - Fields: cbSize, InterfaceClassGuid (Guid), Flags, Reserved (IntPtr)
  • SP_DEVICE_INTERFACE_DETAIL_DATA - Fields: cbSize, DevicePath (string)
  • SP_DEVINFO_DATA - Fields: cbSize, ClassGuid (Guid), DevInst, Reserved

Enum:

  • RegSAM - Flags enum with values: QueryValue, SetValue, CreateSubKey, EnumerateSubKeys, Notify, CreateLink, WOW64_32Key, WOW64_64Key, WOW64_Res, Read, Write, Execute, AllAccess

Static Methods:

  • IntPtr RegisterDeviceNotification(IntPtr hRecipient, IntPtr NotificationFilter, int Flags) - user32.dll
  • int SetupDiCreateDeviceInfoList(ref System.Guid ClassGuid, int hwndParent) - setupapi.dll
  • int SetupDiDestroyDeviceInfoList(IntPtr DeviceInfoSet) - setupapi.dll
  • int SetupDiEnumDeviceInterfaces(IntPtr DeviceInfoSet, IntPtr DeviceInfoData, ref System.Guid InterfaceClassGuid, int MemberIndex, ref SP_DEVICE_INTERFACE_DATA DeviceInterfaceData) - setupapi.dll
  • IntPtr SetupDiGetClassDevs(ref System.Guid ClassGuid, string Enumerator, int hwndParent, uint Flags) - setupapi.dll
  • bool SetupDiGetDeviceInterfaceDetail(IntPtr DeviceInfoSet, ref SP_DEVICE_INTERFACE_DATA DeviceInterfaceData, IntPtr DeviceInterfaceDetailData, int DeviceInterfaceDetailDataSize, ref int RequiredSize, IntPtr DeviceInfoData) - setupapi.dll
  • bool SetupDiEnumDeviceInfo(IntPtr DeviceInfoSet, uint MemberIndex, out SP_DEVINFO_DATA DeviceInfoData) - setupapi.dll
  • IntPtr SetupDiGetClassDevsA(ref Guid ClassGuid, uint Enumerator, IntPtr hwndParent, uint Flags) - setupapi.dll
  • bool SetupDiGetDeviceRegistryPropertyA(IntPtr DeviceInfoSet, SP_DEVINFO_DATA DeviceInfoData, uint Property, uint PropertyRegDataType, StringBuilder PropertyBuffer, uint PropertyBufferSize, IntPtr RequiredSize) - setupapi.dll
  • int SetupDiOpenDevRegKey(IntPtr DeviceInfoSet, ref SP_DEVINFO_DATA DeviceInfoData, uint Scope, uint HwProfile, uint KeyType, RegSAM samDesired) - setupapi.dll
  • uint RegQueryValueEx(int hKey, string lpValueName, uint lpReserved, out uint lpType, ref byte[] lpData, ref uint lpcbData) - Advapi32.dll
  • bool UnregisterDeviceNotification(IntPtr Handle) - user32.dll
  • int GetLastError() - kernel32.dll

DeviceManagement Class

Namespace: DTS.Common.USBFramework

Implements IDisposable. Provides high-level device management operations.

Public Methods:

  • void Dispose() - Empty implementation; does not release resources.

  • bool DeviceNameMatch(Message m, string mydevicePathName) - Compares the device path name from a WM_DEVICECHANGE message against a specified device path name. Returns true if names match (case-insensitive), false otherwise. Only processes messages where dbch_devicetype == DBT_DEVTYP_DEVICEINTERFACE.

  • bool FindDeviceFromGuid(System.Guid myGuid, ref string[] devicePathName) - Enumerates all present devices matching the specified interface class GUID. Populates devicePathName array with device path names. Returns true if at least one device is found. Caller must pre-allocate the devicePathName array with sufficient size.

  • bool RegisterForDeviceNotifications(IntPtr formHandle, Guid classGuid, ref IntPtr deviceNotificationHandle) - Registers a window to receive device arrival/removal notifications for a specific device interface class. Returns true on success. The deviceNotificationHandle is set to the registration handle on success.

  • void StopReceivingDeviceNotifications(IntPtr deviceNotificationHandle) - Unregisters device notifications. Failures are silently ignored.

  • bool GetDeviceRegistryProperty(Guid myGuid) - Enumerates devices and logs driver names via APILogger.Log(). Returns true on success, false on error or if no matching device found.

Static Fields:

  • IS64_BIT_PROCESS (bool, readonly) - Computed as (IntPtr.Size == 8)

3. Invariants

  • Handle Validity: All Win32 handles (int or IntPtr types) must be valid when passed to API functions. INVALID_HANDLE_VALUE (-1) indicates failure from CreateFile operations.
  • Structure Size Initialization: Structures with cbSize fields (SP_DEVICE_INTERFACE_DATA, SP_DEVICE_INTERFACE_DETAIL_DATA, SP_DEVINFO_DATA) must have cbSize set to Marshal.SizeOf() before passing to API functions.
  • Memory Management: Memory allocated via Marshal.AllocHGlobal() must be freed via Marshal.FreeHGlobal(). The FindDeviceFromGuid method allocates and frees detailDataBuffer within its scope.
  • Device Path Array Pre-allocation: FindDeviceFromGuid requires the caller to pre-allocate the devicePathName string array; the method does not resize it.
  • 32/64-bit Compatibility: The code conditionally handles pointer arithmetic based on IS64_BIT_PROCESS for correct memory offset calculations.
  • Namespace Inconsistency: HIDDeclarations resides in DTS.DASLib.Connection.USBFramework while all other classes are in DTS.Common.USBFramework.

4. Dependencies

External Dependencies (DLL Imports):

  • kernel32.dll - File I/O, handles, synchronization
  • hid.dll - HID device communication
  • setupapi.dll - Device enumeration and management
  • user32.dll - Device notification registration
  • Advapi32.dll - Registry operations

Internal Dependencies:

  • Microsoft.Win32.SafeHandles - Used by FileIO class for SafeFileHandle
  • System.Runtime.InteropServices - P/Invoke and marshaling
  • System.Windows.Forms - Message struct used in DeviceNameMatch
  • DTS.Common.Utilities.Logging - APILogger used in DeviceManagement.GetDeviceRegistryProperty

Consumers:

  • Not determinable from source alone; this module appears to be a low-level infrastructure layer for USB communication.

5. Gotchas

  1. Empty Dispose Implementation: DeviceManagement.Dispose() is empty and does not release the deviceNotificationHandle or clean up any resources. Callers must explicitly call StopReceivingDeviceNotifications() before disposal.

  2. Namespace Mismatch: HIDDeclarations is in DTS.DASLib.Connection.USBFramework namespace, while all other classes are in DTS.Common.USBFramework. This may cause compilation issues or require multiple using directives.

  3. Duplicate Constants: FileIODeclarations and FileIO both define identical constants (GENERIC_READ, GENERIC_WRITE, FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_FLAG_OVERLAPPED, INVALID_HANDLE_VALUE, OPEN_EXISTING) with slightly different

Reference in New Issue View Git Blame Copy Permalink