新增 mock_webcam 复合虚拟设备（UVC 摄像头 + UAC 麦克风一体）并修复 Windows 复合枚举

- mock_webcam：UVC/UAC 双功能组 IAD 布局单设备示例；AudioVideoFileSource
  音画同步文件源（--video 选项，主时钟=音频样本，双 demuxer 独立游标）
- 复合设备装配 API：InterfaceHandler 增加 get_interface() 访问器；UAC
  AC/AS 互持 handler（baInterfaceNr 不再猜接口号）、RNDIS 通信/数据
  handler set_data_handler 显式关联；示例 dynamic_pointer_cast 收尾为
  static_pointer_cast
- UAC IAD：UacDeviceHelper 为 AC 接口声明 IAD（CC_AUDIO），修复 0xEF
  复合设备下 usbccgp 拆分 AC/AS 导致 Windows 音频 CM_PROB_FAILED_START
  （实测麦克风/扬声器/复合设备枚举与功能均正常）
- 测试随 example 走：test_webcam 迁入 examples/mock_webcam（同 mock_audio
  约定），其 CMakeLists 注册 test_mock_webcam；e2e test_webcam.sh
- CLAUDE.md 补 Windows usbip.exe 与 Linux usbip -t 用法一致的说明

Author: yunsmall

CLAUDE.md

@@ -4,6 +4,32 @@
 禁止用 std::vector、std::array + 手算字节偏移读写（偏移极易算错、字段增删时无法自动发现错误）。
 多字节字段按网络序存内存，访问时用 bswap/htons 类函数显式转换。
 
+## 测试汇总查看
+
+跑 ctest 必须一条命令看到通过/失败数，禁止跑两遍：输出 tail 至少留 15 行
+（汇总行 `100% tests passed out of N` 在输出最后两行，tail 太短会把汇总
+截掉，还得再跑一次）：
+
+```bash
+ctest --test-dir build --output-on-failure -j12 2>&1 | tail -15
+```
+
+## 注释风格
+
+函数/方法/结构体的文档注释一律用 Doxygen 风格（`/** ... */`，@brief 简述 +
+@param 参数说明 + @return 返回值说明），格式对齐 InterfaceHandler.h 的
+AbstInterfaceHandler::on_new_connection：
+
+```cpp
+    /**
+     * @brief 新的客户端连接时会调这个函数
+     * @param responder 传输应答接口（提交应答/停止传输用）
+     * @param ec 发生的ec
+     */
+```
+
+禁止用 `///` 或 `//` 给函数/方法/结构体写文档（行内注释说明"为什么"不受限）。
+
 ## spdlog 日志级别被编译期裁剪时的调试手法
 
 Release/RelWithDebInfo 构建下 SPDLOG_ACTIVE_LEVEL 编译期定为 INFO，TRACE/DEBUG 日志
@@ -53,6 +79,15 @@ WSL 默认用户非 root 时权限不足会报 `usbip: error: import device`（
 服务器/协议问题）。list 只读不需要 sudo，但为统一可直接
 `sudo usbip -t 53240 ...`。验证导入状态用 `sudo usbip port`。
 
+**Windows 的 usbip.exe 与 Linux usbip 工具命令完全一样**：-t/--tcp-port 是
+两者共同的顶层全局选项（紧跟 usbip 之后、所有子命令之前），Windows 与 Linux
+的 attach/list/port 语法一一对应。Windows 侧连非 3240 端口服务器的命令就是
+`usbip -t 53240 list -r <ip>` / `usbip -t 53240 attach -r <ip> -b 1-1`，
+不要因为 attach 子命令帮助里 -t 显示为 --terse 就以为不支持端口
+（--terse 是 attach 子命令自己的短选项，顶层 -t 才是端口，看 `usbip --help`
+的顶层 OPTIONS）。Linux 中导入 Windows 侧导出的设备（usbipd-win）写法与此
+完全相同：`usbip -t <端口> attach -r <Windows 主机 ip> -b <busid>`。
+
 ## mock 设备本地验证的坑
 
 在 WSL 里起 mock 服务器并 attach 验证时，注意：

CMakeLists.txt

@@ -58,6 +58,7 @@ option(USBIPDCPP_BUILD_EXAMPLE_MOCK_PIPE "Build example mock generic pipe applic
 option(USBIPDCPP_BUILD_EXAMPLE_MOCK_PIPE_HID "Build example mock HID keyboard via generic pipe applications" ${IS_TOP_LEVEL})
 option(USBIPDCPP_BUILD_EXAMPLE_MOCK_ECM "Build example mock CDC ECM (virtual ethernet adapter) applications" ${IS_TOP_LEVEL})
 option(USBIPDCPP_BUILD_EXAMPLE_MOCK_RNDIS "Build example mock CDC RNDIS (virtual ethernet adapter, driverless on Windows) applications" ${IS_TOP_LEVEL})
+option(USBIPDCPP_BUILD_EXAMPLE_MOCK_WEBCAM "Build example mock UVC+UAC webcam (virtual camera + microphone) applications" ${IS_TOP_LEVEL})
 
 if (IS_TOP_LEVEL AND WIN32)
     set(USBIPDCPP_BUILD_EXAMPLE_LIBUSB_WINDOWS_SERVICE_DEFAULT ON)

README.md

@@ -6,7 +6,7 @@ A C++ library for creating usbip servers
 
 > ✅ USBIP server: Platform-independent implementation via libusb (works wherever libusb is supported)
 > ✅ All four USB transfer types (control, bulk, interrupt, isochronous) tested and working via libusb backend
-> ✅ Virtual devices: HID (mouse, keyboard, gamepad, digitizer), MSC (USB flash drive), CDC ACM (serial port), CDC ECM/RNDIS (ethernet), UVC (camera), UAC (microphone, speaker) — no libusb dependency
+> ✅ Virtual devices: HID (mouse, keyboard, gamepad, digitizer), MSC (USB flash drive), CDC ACM (serial port), CDC ECM/RNDIS (ethernet), UVC (camera), UAC (microphone, speaker), webcam (UVC camera + UAC microphone composite) — no libusb dependency
 > ✅ Hot-plug support: Automatic device insertion/removal detection (LibusbServer)
 
 Contributions welcome! 🚀
@@ -560,6 +560,16 @@ All `change_string_*` methods delegate to `StringPool::change_string()` and will
    Usage: `mock_rndis --tun usbip%d` then on the host `ip addr add 192.168.53.2/24 dev usbX`
    and `ping 192.168.53.1`.
 
+**22. mock_webcam**
+
+   A composite device combining a virtual **UVC camera + UAC microphone** in a single USB device — the
+   real-world form of an external webcam, **driverless on Windows** (a "USB camera" and a "microphone"
+   enumerate at the same time, like a physical webcam). The UVC group declares an IAD; the camera
+   (ISO IN video frames) and the microphone (ISO IN audio) stream from the server simultaneously.
+
+   Usage: `mock_webcam --width 640 --height 480 --fps 30 --rates 48000` (mock_uvc options
+   `--width/--height/--fps` combined with mock_audio options `--freq/--rates/--channels/--amp/--harmonics/--audio`).
+
 ---
 
 ## Architecture Overview

README.zh.md

@@ -8,7 +8,7 @@
 
 - ✅ **USBIP 服务器**: 基于 libusb 实现，支持所有 libusb 兼容平台
 - ✅ **四种 USB 传输类型**（控制、批量、中断、同步）均通过 libusb 后端测试
-- ✅ **虚拟设备**: HID（鼠标、键盘、手柄、触摸屏）、MSC（U盘）、CDC ACM（串口）、CDC ECM/RNDIS（网卡）、UVC（摄像头）、UAC（麦克风、扬声器）—— 无需 libusb
+- ✅ **虚拟设备**: HID（鼠标、键盘、手柄、触摸屏）、MSC（U盘）、CDC ACM（串口）、CDC ECM/RNDIS（网卡）、UVC（摄像头）、UAC（麦克风、扬声器）、webcam（UVC 摄像头 + UAC 麦克风复合设备）—— 无需 libusb
 - 🔌 **热插拔支持**: 自动检测设备插入/拔出（LibusbServer）
 - 🧩 **可扩展设计**: 提供完善的抽象接口供开发者扩展
 
@@ -544,6 +544,16 @@ interface_handler->change_string_interface(L"我的 HID 接口");
    用法：`mock_rndis --tun usbip%d`，主机侧 `ip addr add 192.168.53.2/24 dev usbX` 后
    `ping 192.168.53.1`。
 
+**22. mock_webcam**
+
+   虚拟 **UVC 摄像头 + UAC 麦克风** 复合设备——单个 USB 设备同时呈现摄像头与麦克风，
+   即外接摄像头的真实形态，**Windows 免驱**（同一时间枚举出"USB 摄像头"和"麦克风"，
+   与物理摄像头一致）。UVC 功能组声明 IAD；摄像头（ISO IN 视频帧）与麦克风（ISO IN
+   音频）同时从服务器推流。
+
+   用法：`mock_webcam --width 640 --height 480 --fps 30 --rates 48000`（mock_uvc 的
+   `--width/--height/--fps` 与 mock_audio 的 `--freq/--rates/--channels/--amp/--harmonics/--audio` 合并）。
+
 ---
 
 ## 架构设计

examples/CMakeLists.txt

@@ -60,6 +60,9 @@ if (cxxopts_FOUND)
     if (USBIPDCPP_BUILD_VIRTUAL_DEVICE AND USBIPDCPP_BUILD_EXAMPLE_MOCK_RNDIS)
         add_subdirectory(mock_rndis)
     endif ()
+    if (USBIPDCPP_BUILD_VIRTUAL_DEVICE AND USBIPDCPP_BUILD_EXAMPLE_MOCK_WEBCAM)
+        add_subdirectory(mock_webcam)
+    endif ()
 
     if (USBIPDCPP_BUILD_LIBUSB_COMPONENTS AND USBIPDCPP_BUILD_EXAMPLE_LIBUSB_SERVER)
         add_subdirectory(libusb_server)
@@ -131,6 +134,9 @@ if(USBIPDCPP_INSTALL_EXAMPLES)
     if(TARGET mock_rndis)
         install(TARGETS mock_rndis RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
     endif()
+    if(TARGET mock_webcam)
+        install(TARGETS mock_webcam RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+    endif()
     if(TARGET libevdev_mouse)
         install(TARGETS libevdev_mouse RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
     endif()

examples/absolute_mouse/absolute_mouse_main.cpp

@@ -52,7 +52,7 @@ int main(int argc, char **argv) {
     mouse_device->interfaces[0].with_handler<AbsoluteMouseHandler>(string_pool);
     mouse_device->with_handler<SimpleVirtualDeviceHandler>(string_pool)->setup_interface_handlers();
 
-    auto mouse = std::dynamic_pointer_cast<AbsoluteMouseHandler>(mouse_device->interfaces[0].handler);
+    auto mouse = std::static_pointer_cast<AbsoluteMouseHandler>(mouse_device->interfaces[0].handler);
 
     Server server;
     server.add_device(std::move(mouse_device));

examples/libevdev_mouse/libevdev_mouse_main.cpp

@@ -82,7 +82,7 @@ int main(int argc, char **argv) {
         device_handler->setup_interface_handlers();
 
         LibevdevMouseInterfaceHandler &mouse_interface_handler =
-                *std::dynamic_pointer_cast<LibevdevMouseInterfaceHandler>(libevdev_mouse->interfaces[0].handler);
+                *std::static_pointer_cast<LibevdevMouseInterfaceHandler>(libevdev_mouse->interfaces[0].handler);
 
         Server server;
 

examples/mock_cdc_acm/mock_cdc_acm_main.cpp

@@ -29,18 +29,14 @@ int main(int argc, char **argv) {
                                         1, 1, static_cast<std::uint8_t>(ClassCode::CDC), "/usbipdcpp/mock_cdc_acm");
     // 接口从 0 连续编号：按下标依次填 interface_number（多接口设备的 bInterfaceNumber 依赖它）
     mock_cdc_acm->assign_interface_numbers();
-    // 设置接口处理器
-    mock_cdc_acm->interfaces[0].with_handler<MockCdcAcmCommunicationInterfaceHandler>(string_pool);
-    mock_cdc_acm->interfaces[1].with_handler<MockCdcAcmDataInterfaceHandler>(string_pool);
+    // 设置接口处理器（with_handler 返回具体类型的 shared_ptr，直接用，无需 cast）
+    auto comm_handler = mock_cdc_acm->interfaces[0].with_handler<MockCdcAcmCommunicationInterfaceHandler>(string_pool);
+    auto data_handler = mock_cdc_acm->interfaces[1].with_handler<MockCdcAcmDataInterfaceHandler>(string_pool);
     mock_cdc_acm->with_handler<SimpleVirtualDeviceHandler>(string_pool)->setup_interface_handlers();
 
-    // 关联通信接口和数据接口处理器
-    auto &comm_handler =
-            *std::dynamic_pointer_cast<MockCdcAcmCommunicationInterfaceHandler>(mock_cdc_acm->interfaces[0].handler);
-    auto &data_handler =
-            *std::dynamic_pointer_cast<MockCdcAcmDataInterfaceHandler>(mock_cdc_acm->interfaces[1].handler);
-    comm_handler.set_data_handler(&data_handler);
-    data_handler.set_comm_handler(&comm_handler);
+    // 关联通信接口和数据接口处理器（描述符引用数据接口号 + 数据面状态查询）
+    comm_handler->set_data_handler(data_handler.get());
+    data_handler->set_comm_handler(comm_handler.get());
 
     Server server;
     server.add_device(std::move(mock_cdc_acm));

examples/mock_cdc_throttle/mock_cdc_throttle_main.cpp

@@ -51,9 +51,9 @@ int main(int argc, char **argv) {
 
     // 关联通信接口和数据接口处理器
     auto &comm_handler =
-            *std::dynamic_pointer_cast<CdcAcmCommunicationInterfaceHandler>(device->interfaces[0].handler);
+            *std::static_pointer_cast<CdcAcmCommunicationInterfaceHandler>(device->interfaces[0].handler);
     auto &data_handler =
-            *std::dynamic_pointer_cast<ThrottleCdcAcmDataInterfaceHandler>(device->interfaces[1].handler);
+            *std::static_pointer_cast<ThrottleCdcAcmDataInterfaceHandler>(device->interfaces[1].handler);
     comm_handler.set_data_handler(&data_handler);
     data_handler.set_comm_handler(&comm_handler);
 

examples/mock_ecm/mock_ecm_main.cpp

@@ -115,8 +115,10 @@ int main(int argc, char **argv) {
                                   1, 1, static_cast<std::uint8_t>(ClassCode::CDC), "/usbipdcpp/mock_ecm");
     // 接口从 0 连续编号：按下标依次填 interface_number（多接口设备的 bInterfaceNumber 依赖它）
     device->assign_interface_numbers();
-    device->interfaces[0].with_handler<EcmCommunicationInterfaceHandler>(string_pool, mac);
-    device->interfaces[1].with_handler<EcmDataInterfaceHandler>(string_pool, backend.get());
+    auto comm = device->interfaces[0].with_handler<EcmCommunicationInterfaceHandler>(string_pool, mac);
+    auto data = device->interfaces[1].with_handler<EcmDataInterfaceHandler>(string_pool, backend.get());
+    // 通信接口描述符的 Union 引用数据接口号（bSlaveInterface0），装配时关联
+    comm->set_data_handler(data.get());
     device->with_handler<SimpleVirtualDeviceHandler>(string_pool)->setup_interface_handlers();
 
     Server server;