@mcesystems/usb-device-listener 1.0.5 → 1.0.6

package/binding.gyp

@@ -0,0 +1,41 @@
+{
+	"targets": [
+		{
+			"target_name": "usb_device_listener",
+			"sources": [
+				"native/addon.cc",
+				"native/usb_listener.cc"
+			],
+			"include_dirs": [
+				"<!@(node -p \"require('node-addon-api').include\")"
+			],
+			"dependencies": [
+				"<!(node -p \"require('node-addon-api').gyp\")"
+			],
+			"defines": [
+				"NAPI_DISABLE_CPP_EXCEPTIONS",
+				"UNICODE",
+				"_UNICODE"
+			],
+			"conditions": [
+				[
+					"OS=='win'",
+					{
+						"libraries": [
+							"Setupapi.lib",
+							"Cfgmgr32.lib"
+						],
+						"msvs_settings": {
+							"VCCLCompilerTool": {
+								"ExceptionHandling": 1,
+								"AdditionalOptions": [
+									"/std:c++20"
+								]
+							}
+						}
+					}
+				]
+			]
+		}
+	]
+}

package/native/addon.cc

@@ -0,0 +1,118 @@
+#include <napi.h>
+#include "usb_listener.h"
+#include <memory>
+
+static std::unique_ptr<USBListener> g_listener;
+
+Napi::Value StartListening(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	std::string errorMsg;
+	if (!g_listener->StartListening(errorMsg)) {
+		Napi::Error::New(env, errorMsg).ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	return env.Undefined();
+}
+
+Napi::Value StopListening(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (g_listener) {
+		g_listener->StopListening();
+	}
+	
+	return env.Undefined();
+}
+
+Napi::Value OnDeviceAdd(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (info.Length() < 1 || !info[0].IsFunction()) {
+		Napi::TypeError::New(env, "Callback function expected").ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	Napi::Function callback = info[0].As<Napi::Function>();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	Napi::ThreadSafeFunction tsfn = Napi::ThreadSafeFunction::New(
+		env,
+		callback,
+		"DeviceAddCallback",
+		0,
+		1
+	);
+	
+	g_listener->SetAddCallback(tsfn);
+	
+	return env.Undefined();
+}
+
+Napi::Value OnDeviceRemove(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (info.Length() < 1 || !info[0].IsFunction()) {
+		Napi::TypeError::New(env, "Callback function expected").ThrowAsJavaScriptException();
+		return env.Undefined();
+	}
+	
+	Napi::Function callback = info[0].As<Napi::Function>();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	Napi::ThreadSafeFunction tsfn = Napi::ThreadSafeFunction::New(
+		env,
+		callback,
+		"DeviceRemoveCallback",
+		0,
+		1
+	);
+	
+	g_listener->SetRemoveCallback(tsfn);
+	
+	return env.Undefined();
+}
+
+Napi::Value ListDevices(const Napi::CallbackInfo& info) {
+	Napi::Env env = info.Env();
+	
+	if (!g_listener) {
+		g_listener = std::make_unique<USBListener>();
+	}
+	
+	std::vector<DeviceInfo> devices = g_listener->ListAllDevices();
+	
+	Napi::Array result = Napi::Array::New(env, devices.size());
+	for (size_t i = 0; i < devices.size(); i++) {
+		Napi::Object obj = Napi::Object::New(env);
+		obj.Set("deviceId", Napi::String::New(env, devices[i].deviceId));
+		obj.Set("vid", Napi::Number::New(env, devices[i].vid));
+		obj.Set("pid", Napi::Number::New(env, devices[i].pid));
+		obj.Set("locationInfo", Napi::String::New(env, devices[i].locationInfo));
+		result[i] = obj;
+	}
+	
+	return result;
+}
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+	exports.Set("startListening", Napi::Function::New(env, StartListening));
+	exports.Set("stopListening", Napi::Function::New(env, StopListening));
+	exports.Set("onDeviceAdd", Napi::Function::New(env, OnDeviceAdd));
+	exports.Set("onDeviceRemove", Napi::Function::New(env, OnDeviceRemove));
+	exports.Set("listDevices", Napi::Function::New(env, ListDevices));
+	return exports;
+}
+
+NODE_API_MODULE(usb_device_listener, Init)

package/native/usb_listener.cc

@@ -0,0 +1,414 @@
+#include "usb_listener.h"
+#include <devguid.h>
+#include <usbiodef.h>  // For GUID_DEVINTERFACE_USB_DEVICE
+#include <sstream>
+#include <iomanip>
+#include <algorithm>
+
+USBListener::USBListener() = default;
+
+USBListener::~USBListener() {
+	StopListening();
+}
+
+/**
+ * Start the USB device listener
+ * Creates a separate thread that runs a Windows message loop to receive device notifications
+ */
+bool USBListener::StartListening(std::string& errorMsg) {
+	bool expected = false;
+	if (!m_running.compare_exchange_strong(expected, true)) {
+		errorMsg = "Listener already running";
+		return false;
+	}
+	
+	// Create thread with RAII wrapper
+	HANDLE threadHandle = CreateThread(nullptr, 0, ListenerThreadProc, this, 0, nullptr);
+	if (!threadHandle) {
+		m_running = false;
+		errorMsg = "Failed to create listener thread";
+		return false;
+	}
+	m_thread = ThreadHandle(threadHandle);
+	
+	// Brief wait for thread initialization
+	Sleep(100);
+	EnumerateConnectedDevices();
+	
+	return true;
+}
+
+void USBListener::StopListening() {
+	bool expected = true;
+	if (!m_running.compare_exchange_strong(expected, false)) {
+		return;  // Already stopped
+	}
+	
+	// Signal message loop to quit
+	if (m_hwnd) {
+		PostMessage(m_hwnd, WM_QUIT, 0, 0);
+	}
+	
+	// Thread cleanup is automatic via ThreadHandle RAII
+	// Destructor will wait and close handle
+	m_thread = ThreadHandle();  // Reset to trigger cleanup
+	
+	// Release ThreadSafeFunction callbacks
+	if (m_addCallback) {
+		m_addCallback.Release();
+	}
+	if (m_removeCallback) {
+		m_removeCallback.Release();
+	}
+	
+	// Clear device cache
+	std::unique_lock lock(m_cacheMutex);
+	m_deviceCache.clear();
+}
+
+void USBListener::SetAddCallback(Napi::ThreadSafeFunction callback) {
+	m_addCallback = callback;
+}
+
+void USBListener::SetRemoveCallback(Napi::ThreadSafeFunction callback) {
+	m_removeCallback = callback;
+}
+
+DWORD WINAPI USBListener::ListenerThreadProc(LPVOID param) {
+	USBListener* listener = static_cast<USBListener*>(param);
+	listener->MessageLoop();
+	return 0;
+}
+
+void USBListener::MessageLoop() {
+	WNDCLASSEX wc = {0};
+	wc.cbSize = sizeof(WNDCLASSEX);
+	wc.lpfnWndProc = WindowProc;
+	wc.hInstance = GetModuleHandle(nullptr);
+	wc.lpszClassName = L"USBListenerWindow";
+	
+	if (!RegisterClassEx(&wc)) {
+		return;
+	}
+	
+	m_hwnd = CreateWindowEx(0, L"USBListenerWindow", L"USBListener", 0, 0, 0, 0, 0, HWND_MESSAGE, nullptr, GetModuleHandle(nullptr), nullptr);
+	if (!m_hwnd) {
+		return;
+	}
+	
+	SetWindowLongPtr(m_hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(this));
+	
+	DEV_BROADCAST_DEVICEINTERFACE notificationFilter = {0};
+	notificationFilter.dbcc_size = sizeof(DEV_BROADCAST_DEVICEINTERFACE);
+	notificationFilter.dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
+	notificationFilter.dbcc_classguid = GUID_DEVINTERFACE_USB_DEVICE;
+	
+	m_notifyHandle = RegisterDeviceNotification(m_hwnd, &notificationFilter, DEVICE_NOTIFY_WINDOW_HANDLE);
+	
+	MSG msg;
+	while (m_running && GetMessage(&msg, nullptr, 0, 0)) {
+		TranslateMessage(&msg);
+		DispatchMessage(&msg);
+	}
+	
+	if (m_notifyHandle) {
+		UnregisterDeviceNotification(m_notifyHandle);
+		m_notifyHandle = nullptr;
+	}
+	
+	if (m_hwnd) {
+		DestroyWindow(m_hwnd);
+		m_hwnd = nullptr;
+	}
+	
+	UnregisterClass(L"USBListenerWindow", GetModuleHandle(nullptr));
+}
+
+LRESULT CALLBACK USBListener::WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam) {
+	if (msg == WM_DEVICECHANGE) {
+		USBListener* listener = reinterpret_cast<USBListener*>(GetWindowLongPtr(hwnd, GWLP_USERDATA));
+		if (listener) {
+			listener->HandleDeviceChange(wParam, lParam);
+		}
+	}
+	return DefWindowProc(hwnd, msg, wParam, lParam);
+}
+
+/**
+ * Handle WM_DEVICECHANGE messages
+ * For connections: queries Windows API for full device info
+ * For disconnections: retrieves cached info since device is already gone
+ */
+void USBListener::HandleDeviceChange(WPARAM wParam, LPARAM lParam) {
+	// Only handle device arrival and removal events
+	if (wParam != DBT_DEVICEARRIVAL && wParam != DBT_DEVICEREMOVECOMPLETE) {
+		return;
+	}
+	
+	// Extract device interface information
+	DEV_BROADCAST_DEVICEINTERFACE* devInterface = reinterpret_cast<DEV_BROADCAST_DEVICEINTERFACE*>(lParam);
+	if (!devInterface || devInterface->dbcc_devicetype != DBT_DEVTYP_DEVICEINTERFACE) {
+		return;
+	}
+	
+	// Convert device path to string
+	std::wstring devicePathW = devInterface->dbcc_name;
+	std::string devicePath(devicePathW.begin(), devicePathW.end());
+	
+	DeviceInfo info;
+	bool gotInfo = false;
+	
+	if (wParam == DBT_DEVICEARRIVAL) {
+		// For connections, query Windows API for full device details
+		gotInfo = GetDeviceInfo(devicePath, info);
+	} else if (wParam == DBT_DEVICEREMOVECOMPLETE) {
+		// For disconnections, device is gone - retrieve from cache
+		DeviceInfo pathInfo;
+		if (GetDeviceInfoFromPath(devicePath, pathInfo)) {
+			std::unique_lock lock(m_cacheMutex);  // Exclusive lock for write
+			if (auto it = m_deviceCache.find(pathInfo.deviceId); it != m_deviceCache.end()) {
+				info = std::move(it->second);  // Move for efficiency
+				m_deviceCache.erase(it);
+				gotInfo = true;
+			}
+		}
+	}
+	
+	if (!gotInfo) {
+		return;
+	}
+	
+	if (wParam == DBT_DEVICEARRIVAL && m_addCallback) {
+		// Cache device info for disconnect events
+		{
+			std::unique_lock lock(m_cacheMutex);  // Exclusive lock for write
+			m_deviceCache[info.deviceId] = info;
+		}
+		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+			Napi::Object obj = Napi::Object::New(env);
+			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("vid", Napi::Number::New(env, data->vid));
+			obj.Set("pid", Napi::Number::New(env, data->pid));
+			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+			if (data->logicalPort >= 0) {
+				obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+			} else {
+				obj.Set("logicalPort", env.Null());
+			}
+			jsCallback.Call({obj});
+			delete data;
+		};
+		m_addCallback.BlockingCall(new DeviceInfo(info), callback);
+	} else if (wParam == DBT_DEVICEREMOVECOMPLETE && m_removeCallback) {
+		auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+			Napi::Object obj = Napi::Object::New(env);
+			obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+			obj.Set("vid", Napi::Number::New(env, data->vid));
+			obj.Set("pid", Napi::Number::New(env, data->pid));
+			obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+			if (data->logicalPort >= 0) {
+				obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+			} else {
+				obj.Set("logicalPort", env.Null());
+			}
+			jsCallback.Call({obj});
+			delete data;
+		};
+		m_removeCallback.BlockingCall(new DeviceInfo(info), callback);
+	}
+}
+
+bool USBListener::GetDeviceInfoFromPath(const std::string& devicePath, DeviceInfo& info) {
+	size_t hashPos = devicePath.rfind('#');
+	if (hashPos == std::string::npos) {
+		return false;
+	}
+	
+	std::string deviceIdStr = devicePath.substr(4, hashPos - 4);
+	std::replace(deviceIdStr.begin(), deviceIdStr.end(), '#', '\\');
+	
+	info.deviceId = deviceIdStr;
+	
+	if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+		return false;
+	}
+	
+	size_t lastHash = deviceIdStr.rfind('\\');
+	if (lastHash != std::string::npos) {
+		info.locationInfo = deviceIdStr.substr(lastHash + 1);
+	} else {
+		info.locationInfo = "";
+	}
+	
+	return true;
+}
+
+bool USBListener::GetDeviceInfo(const std::string& devicePath, DeviceInfo& info) {
+	size_t hashPos = devicePath.rfind('#');
+	if (hashPos == std::string::npos) {
+		return false;
+	}
+	
+	std::string deviceIdStr = devicePath.substr(4, hashPos - 4);
+	std::replace(deviceIdStr.begin(), deviceIdStr.end(), '#', '\\');
+	
+	std::wstring deviceIdW(deviceIdStr.begin(), deviceIdStr.end());
+	
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return false;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			if (_wcsicmp(instanceId, deviceIdW.c_str()) == 0) {
+				std::wstring idW = instanceId;
+				info.deviceId = std::string(idW.begin(), idW.end());
+				
+				if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+					SetupDiDestroyDeviceInfoList(deviceInfoSet);
+					return false;
+				}
+				
+				DEVINST devInst = devInfoData.DevInst;
+				if (!GetLocationInfo(devInst, info.locationInfo)) {
+					SetupDiDestroyDeviceInfoList(deviceInfoSet);
+					return false;
+				}
+				
+				SetupDiDestroyDeviceInfoList(deviceInfoSet);
+				return true;
+			}
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+	return false;
+}
+
+bool USBListener::GetLocationInfo(DEVINST devInst, std::string& locationInfo) {
+	WCHAR buffer[MAX_PATH];
+	ULONG size = sizeof(buffer);
+	
+	CONFIGRET ret = CM_Get_DevNode_Registry_Property(devInst, CM_DRP_LOCATION_INFORMATION, nullptr, buffer, &size, 0);
+	if (ret != CR_SUCCESS) {
+		return false;
+	}
+	
+	std::wstring locationW = buffer;
+	locationInfo = std::string(locationW.begin(), locationW.end());
+	return true;
+}
+
+bool USBListener::GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid) {
+	size_t vidPos = deviceId.find("VID_");
+	size_t pidPos = deviceId.find("PID_");
+	
+	if (vidPos == std::string::npos || pidPos == std::string::npos) {
+		return false;
+	}
+	
+	try {
+		std::string vidStr = deviceId.substr(vidPos + 4, 4);
+		std::string pidStr = deviceId.substr(pidPos + 4, 4);
+		
+		vid = static_cast<uint16_t>(std::stoul(vidStr, nullptr, 16));
+		pid = static_cast<uint16_t>(std::stoul(pidStr, nullptr, 16));
+		return true;
+	} catch (...) {
+		return false;
+	}
+}
+
+void USBListener::EnumerateConnectedDevices() {
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			DeviceInfo info;
+			std::wstring idW = instanceId;
+			info.deviceId = std::string(idW.begin(), idW.end());
+			
+			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+				continue;
+			}
+			
+			DEVINST devInst = devInfoData.DevInst;
+			if (!GetLocationInfo(devInst, info.locationInfo)) {
+				continue;
+			}
+			
+			// Cache device with exclusive lock
+			{
+				std::unique_lock lock(m_cacheMutex);
+				m_deviceCache[info.deviceId] = info;
+			}
+			
+			if (m_addCallback) {
+				auto callback = [](Napi::Env env, Napi::Function jsCallback, DeviceInfo* data) {
+					Napi::Object obj = Napi::Object::New(env);
+					obj.Set("deviceId", Napi::String::New(env, data->deviceId));
+					obj.Set("vid", Napi::Number::New(env, data->vid));
+					obj.Set("pid", Napi::Number::New(env, data->pid));
+					obj.Set("locationInfo", Napi::String::New(env, data->locationInfo));
+					if (data->logicalPort >= 0) {
+						obj.Set("logicalPort", Napi::Number::New(env, data->logicalPort));
+					} else {
+						obj.Set("logicalPort", env.Null());
+					}
+					jsCallback.Call({obj});
+					delete data;
+				};
+				m_addCallback.BlockingCall(new DeviceInfo(info), callback);
+			}
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+}
+
+std::vector<DeviceInfo> USBListener::ListAllDevices() {
+	std::vector<DeviceInfo> devices;
+	
+	HDEVINFO deviceInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_USB_DEVICE, nullptr, nullptr, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);
+	if (deviceInfoSet == INVALID_HANDLE_VALUE) {
+		return devices;
+	}
+	
+	SP_DEVINFO_DATA devInfoData = {0};
+	devInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
+	
+	for (DWORD i = 0; SetupDiEnumDeviceInfo(deviceInfoSet, i, &devInfoData); i++) {
+		WCHAR instanceId[MAX_PATH];
+		if (SetupDiGetDeviceInstanceId(deviceInfoSet, &devInfoData, instanceId, MAX_PATH, nullptr)) {
+			DeviceInfo info;
+			std::wstring idW = instanceId;
+			info.deviceId = std::string(idW.begin(), idW.end());
+			
+			if (!GetVidPid(info.deviceId, info.vid, info.pid)) {
+				continue;
+			}
+			
+			DEVINST devInst = devInfoData.DevInst;
+			if (!GetLocationInfo(devInst, info.locationInfo)) {
+				continue;
+			}
+			
+			devices.push_back(info);
+		}
+	}
+	
+	SetupDiDestroyDeviceInfoList(deviceInfoSet);
+	return devices;
+}

package/native/usb_listener.h

@@ -0,0 +1,113 @@
+#ifndef USB_LISTENER_H
+#define USB_LISTENER_H
+
+#include <napi.h>
+#include <windows.h>
+#include <initguid.h>
+#include <setupapi.h>
+#include <cfgmgr32.h>
+#include <dbt.h>
+#include <string>
+#include <vector>
+#include <unordered_map>
+#include <memory>
+#include <atomic>
+#include <shared_mutex>
+
+/**
+ * Device information structure
+ * Contains all relevant USB device identification and location data
+ */
+struct DeviceInfo {
+	std::string deviceId;       // Windows device instance ID
+	uint16_t vid{0};            // Vendor ID
+	uint16_t pid{0};            // Product ID
+	std::string locationInfo;   // Physical port location
+	int logicalPort{-1};        // User-defined logical port number (-1 if not mapped)
+};
+
+/**
+ * RAII wrapper for Windows thread handle
+ */
+class ThreadHandle {
+public:
+	ThreadHandle() noexcept = default;
+	explicit ThreadHandle(HANDLE h) noexcept : handle(h) {}
+	~ThreadHandle() { if (handle) { WaitForSingleObject(handle, 5000); CloseHandle(handle); } }
+	
+	ThreadHandle(const ThreadHandle&) = delete;
+	ThreadHandle& operator=(const ThreadHandle&) = delete;
+	ThreadHandle(ThreadHandle&& other) noexcept : handle(std::exchange(other.handle, nullptr)) {}
+	ThreadHandle& operator=(ThreadHandle&& other) noexcept {
+		if (this != &other) {
+			if (handle) { WaitForSingleObject(handle, 5000); CloseHandle(handle); }
+			handle = std::exchange(other.handle, nullptr);
+		}
+		return *this;
+	}
+	
+	HANDLE get() const noexcept { return handle; }
+	explicit operator bool() const noexcept { return handle != nullptr; }
+	
+private:
+	HANDLE handle{nullptr};
+};
+
+/**
+ * USB Device Listener - Windows native implementation
+ * 
+ * Monitors USB device connection/disconnection events using Windows WM_DEVICECHANGE messages.
+ * Runs a hidden message-only window in a separate thread to receive device notifications.
+ * Thread-safe: callbacks are invoked on the Node.js thread using Napi::ThreadSafeFunction.
+ */
+class USBListener {
+public:
+	USBListener();
+	~USBListener();
+	
+	// Start monitoring USB device events
+	bool StartListening(std::string& errorMsg);
+	
+	// Stop monitoring and clean up resources
+	void StopListening();
+	
+	// Set callback for device connection events
+	void SetAddCallback(Napi::ThreadSafeFunction callback);
+	
+	// Set callback for device disconnection events
+	void SetRemoveCallback(Napi::ThreadSafeFunction callback);
+	
+	// Get list of all currently connected USB devices
+	std::vector<DeviceInfo> ListAllDevices();
+	
+private:
+	// Windows message handling
+	static LRESULT CALLBACK WindowProc(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam);
+	static DWORD WINAPI ListenerThreadProc(LPVOID param);
+	
+	// Core functionality
+	void MessageLoop();                                                         // Main message loop in listener thread
+	void HandleDeviceChange(WPARAM wParam, LPARAM lParam);                     // Process WM_DEVICECHANGE messages
+	bool GetDeviceInfo(const std::string& devicePath, DeviceInfo& info);       // Get device info from Windows API (for connections)
+	bool GetDeviceInfoFromPath(const std::string& devicePath, DeviceInfo& info); // Parse device info from path (for disconnections)
+	bool GetLocationInfo(DEVINST devInst, std::string& locationInfo);          // Get physical port location
+	bool GetVidPid(const std::string& deviceId, uint16_t& vid, uint16_t& pid); // Parse VID/PID from device ID string
+	void EnumerateConnectedDevices();                                          // Enumerate devices on startup
+	
+	// Windows handles (managed resources)
+	HWND m_hwnd{nullptr};                           // Hidden message-only window
+	HDEVNOTIFY m_notifyHandle{nullptr};             // Device notification handle
+	ThreadHandle m_thread;                          // Listener thread handle (RAII)
+	std::atomic<bool> m_running{false};             // Thread control flag
+	
+	// Device cache with shared_mutex for reader-writer lock pattern
+	// Multiple readers (enumerate) or single writer (add/remove)
+	mutable std::shared_mutex m_cacheMutex;         // C++17 shared_mutex for better concurrency
+	std::unordered_map<std::string, DeviceInfo> m_deviceCache;  // Fast lookup with hash
+	
+	// Callbacks
+	Napi::ThreadSafeFunction m_addCallback;         // Device add callback
+	Napi::ThreadSafeFunction m_removeCallback;      // Device remove callback
+};
+
+#endif // USB_LISTENER_H