// DeviceContext.h - WDFDEVICE 设备上下文
// 每个被过滤的串口设备都关联一个上下文，存储：
// - 该端口的环形缓冲区指针（捕获的事件）
// - 是否已通过 IOCTL_COMMKIT_ATTACH_PORT 启用监控
// - 该端口的 COM 编号（从硬件 ID 解析或注册时填入）
#pragma once

#include <ntddk.h>
#include <wdf.h>
#include "../common/CommKitIoctl.h"

// 前向声明
struct COMMKIT_RING_ENTRY;

// 每个串口过滤设备的上下文
typedef struct _DEVICE_CONTEXT {
    // 该端口对应的 COM 编号（COM n 的 n），0 表示未知
    ULONG               ComNumber;

    // 是否已通过 ATTACH_PORT IOCTL 启用监控
    // 未启用的端口只做 IRP 透传，不捕获数据
    BOOLEAN             MonitoringEnabled;

    // 该端口的事件环形缓冲（指针避免结构体过大）
    // 实际为 EventRingBuffer 实例指针，定义见 EventRingBuffer.h
    PVOID               RingBuffer;

    // 下层真实串口设备对象（attach 目标）
    PDEVICE_OBJECT      LowerDevice;

    // WDF 设备句柄（包装下层）
    WDFDEVICE            WdfDevice;

    // ====== 注入 I/O 用的 FileObject ======
    // 串口驱动（尤其是虚拟串口如 ELTIMA）需要有效的 FileObject 才能正确处理
    // HandleWritePort/HandleReadPort 构造的 IRP。没有 FileObject 时，写 IRP
    // 可能返回 STATUS_SUCCESS 但数据不会路由到配对端口的读缓冲。
    // 这里保存最近一次用户态打开该串口时的 WDM FILE_OBJECT（已 ObReference），
    // 在 EvtDeviceFileCreate 中捕获，EvtFileClose 中释放。
    PFILE_OBJECT        SavedFileObject;
    KSPIN_LOCK          FileObjectLock;

} DEVICE_CONTEXT, *PDEVICE_CONTEXT;

// WDF_DECLARE_CONTEXT_TYPE_WITH_NAME 必须在全局作用域
WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, DeviceGetContext)