CommModifyKit/driver/ClientConnection.h

// ClientConnection.h - 用户态连接管理
// 职责：维护 DLL 与驱动之间的控制设备 + 端口监控启用列表
// 当 DLL 通过 ATTACH_PORT IOCTL 启用某端口时，标记该端口为监控状态
// 当 DLL 通过 READ_EVENTS IOCTL 读取事件时，遍历所有启用端口的环形缓冲
#pragma once

#include <ntddk.h>
#include <wdf.h>
#include "DeviceContext.h"
#include "EventRingBuffer.h"

namespace commkit_driver {

class ClientConnection {
public:
    // 初始化（构造不分配资源）
    void Initialize();

    // 清理资源（驱动卸载时调用）
    void Cleanup();

    // ====== IOCTL 处理接口（由 QueueCallback 调用）======

    // REGISTER_CALLBACK：标记 DLL 已连接
    NTSTATUS HandleRegisterCallback();

    // ATTACH_PORT：启用某端口监控
    NTSTATUS HandleAttachPort(ULONG com_number);

    // DETACH_PORT：停止某端口监控
    NTSTATUS HandleDetachPort(ULONG com_number);

    // WRITE_PORT：向指定串口发数据
    // bytes_written 输出实际写入字节数
    NTSTATUS HandleWritePort(ULONG com_number, PVOID data, ULONG len,
                              PULONG bytes_written);

    // READ_PORT：从指定串口读数据
    // bytes_read 输出实际读取字节数
    NTSTATUS HandleReadPort(ULONG com_number, PVOID data, ULONG len,
                             PULONG bytes_read);

    // READ_EVENTS：批量读取所有启用端口的事件
    // out_buf：用户缓冲；out_size：缓冲字节大小
    // returned：实际返回字节数
    NTSTATUS HandleReadEvents(PVOID out_buf, ULONG out_size, PULONG returned);

    // FREE_ALL：停止所有监控
    NTSTATUS HandleFreeAll();

    // 注册一个过滤设备（当 EvtDeviceAdd 创建时调用）
    // com_number 暂为 0，由 UpdatePortComNumber 更新
    void RegisterFilterDevice(WDFDEVICE device);

    // 更新端口表中设备的 COM 编号（EvtDevicePrepareHardware 解析后调用）
    void UpdatePortComNumber(WDFDEVICE device, ULONG com_number);

    // 注销一个过滤设备
    void UnregisterFilterDevice(ULONG com_number);

private:
    // 查找指定 COM 编号对应的过滤设备上下文
    PDEVICE_CONTEXT FindPortContext(ULONG com_number);

    // 全局端口表锁
    KSPIN_LOCK          ports_lock_;

    // 端口→设备上下文映射（最多支持 256 个 COM 端口）
    typedef struct {
        ULONG           ComNumber;
        PDEVICE_CONTEXT Context;
    } PORT_ENTRY;
    PORT_ENTRY          ports_table_[256];
    ULONG               ports_count_;

    // 控制设备对象
    WDFDEVICE           control_device_;

    // DLL 是否已注册回调
    BOOLEAN             callback_registered_;
};

// 全局实例（手动管理生命周期）
extern ClientConnection g_ClientConnection;

// 访问全局实例
inline ClientConnection& GetClientConnection() {
    return g_ClientConnection;
}

} // namespace commkit_driver

// 诊断计数器（全局命名空间，不依赖 DbgPrint，可在 HandleAttachPort 中输出）
extern volatile LONG g_diag_evt_device_add_count;
extern volatile LONG g_diag_prepare_hardware_count;
extern volatile LONG g_diag_register_filter_count;
extern volatile LONG g_diag_irp_preprocess_ok;    // 所有 IRP preprocess 注册成功次数
extern volatile LONG g_diag_device_create_ok;       // WdfDeviceCreate 成功次数
extern volatile LONG g_diag_last_failure_status;   // 最后一次失败的 NTSTATUS