windows网络适配器驱动开发-调用 WDF 函数的注意事项

NetAdapterCx 是网络适配器的 WDF 类扩展它使驱动程序能够访问完整的 WDF 功能同时通过 NetAdapter 类扩展获得网络特定的 API 和 I/O 支持。在 NetAdapterCx 客户端驱动程序中某些 WDF 函数的使用受到限制或被 NetDeviceInitConfig 代为调用客户端驱动程序需要特别注意这些限制以避免未定义的行为或功能异常。一、WdfDeviceInitAssignSDDLString函数说明WdfDeviceInitAssignSDDLString 用于为设备对象分配安全设置驱动程序可以使用安全描述符定义语言SDDL的子集来指定安全设置。NetAdapterCx 中的注意事项默认情况下NetDeviceInitConfig 会分配 SDDL_DEVOBJ_SYS_ALL_ADM_RWX_WORLD_RW_RES_R 作为默认 SDDL。重要限制如果客户端驱动程序指定了比默认值更严格的 SDDL应用程序可能无法将查询 OID 发送到适配器。建议除非有特殊安全需求且充分理解其对应用程序通信的影响否则应使用 NetDeviceInitConfig 分配的默认 SDDL 设置不要自行调用 WdfDeviceInitAssignSDDLString 覆盖安全描述符。二、WdfDeviceInitSetFileObjectConfig函数说明WdfDeviceInitSetFileObjectConfig 用于注册事件回调函数并设置驱动程序框架文件对象的配置信息。驱动程序必须在其 EvtDriverDeviceAdd 回调函数中调用此函数。NetAdapterCx 中的注意事项重要限制客户端驱动程序不得在 WDF_FILEOBJECT_CONFIG 的 FileObjectClass 成员中设置 WdfFileObjectWdfCanUseFsContext。原因WdfFileObjectWdfCanUseFsContext 允许框架将文件对象的句柄存储在 WDM FILE_OBJECT 结构的 FsContext 成员中。在 NetAdapterCx 环境下此设置可能与网络适配器类扩展的内部机制产生冲突因此被明确禁止。建议使用 WdfFileObjectWdfCannotUseFsContexts默认值或其他允许的值。三、由 NetDeviceInitConfig 代为调用的函数涉及函数列表- WdfDeviceInitAssignName- WdfDeviceInitSetReleaseHardwareOrderOnFailure- WdfDeviceInitSetDeviceType- WdfDeviceInitSetCharacteristics- WdfDeviceInitSetIoType- WdfDeviceInitSetPowerPageable注意事项当客户端驱动程序调用 NetDeviceInitConfig 时系统提供的 NetAdapterCx.sys 驱动程序会代表客户端调用上述函数。客户端驱动程序不应该直接调用这些函数。风险直接调用这些函数可能会导致未定义的行为。建议在 EvtDriverDeviceAdd 回调中调用 NetDeviceInitConfig 后直接调用 WdfDeviceCreate 创建设备对象无需手动调用上述任何初始化函数。四、WdfDeviceCreateDeviceInterface函数说明WdfDeviceCreateDeviceInterface 用于注册设备接口类的实例。驱动程序可以使用 ReferenceString 参数来区分同一接口的不同实例。NetAdapterCx 中的注意事项重要限制如果客户端驱动程序使用 ReferenceString 参数等于 NULL 调用 WdfDeviceCreateDeviceInterface则 NDIS 将截获发送到设备接口的 I/O 请求。原因在 NetAdapterCx 环境中当 ReferenceString 为 NULL 时NDIS 会拦截发往该设备接口的所有 I/O 请求这可能导致驱动程序无法正常接收和处理预期的 I/O 通信。建议始终指定一个非 NULL 的引用字符串。任何有效的引用字符串都可以避免此问题。例如UNICODE_STRING referenceString;RtlInitUnicodeString(referenceString, LMyInterface);WdfDeviceCreateDeviceInterface(device, GUID_DEVINTERFACE_MY, referenceString);注意引用字符串不得包含任何路径分隔符/或\。总结下面汇总了 NetAdapterCx 客户端驱动程序中各 WDF 函数的调用限制- WdfDeviceInitAssignSDDLString限制更严格的 SDDL 可能阻止应用程序发送查询 OID建议使用默认 SDDL- WdfDeviceInitSetFileObjectConfig限制禁止设置 WdfFileObjectWdfCanUseFsContext建议使用 WdfFileObjectWdfCannotUseFsContexts- WdfDeviceInitAssignName、WdfDeviceInitSetReleaseHardwareOrderOnFailure、WdfDeviceInitSetDeviceType、WdfDeviceInitSetCharacteristics、WdfDeviceInitSetIoType、WdfDeviceInitSetPowerPageable限制由 NetDeviceInitConfig 代为调用不应直接调用建议不要直接调用这些函数- WdfDeviceCreateDeviceInterface限制ReferenceString NULL 时 NDIS 截获 I/O建议始终指定非 NULL 引用字符串