WDI TLV 分析器接口概述

被调用方分配模型

驱动程序中的入口点会收到包含 TLV 的消息或指示。 在代码提取消息 ID 并确定它是否是它想要处理的 ID 之后，它会调用泛型分析例程，并在通过 WDI_MESSAGE_HEADER) 传递 TLV blob (，以将 TLV 分析为 C 结构。

ndisStatus = Parse(
    cbBufferLength,
    pvBuffer,
    messageId,
    &Context,
    &pParsed);

检查错误返回后，代码可以将输出缓冲区 (pParsed) 强制转换为具体类型，如以下示例所示。

((WDI_INDICATION_BSS_ENTRY_LIST_PARAMETERS*)pParsed)

调用方使用分析的数据完成后，调用方必须将内存返回给分析程序。 分析程序需要知道用于分配的原始消息 ID，以便释放正确的数据。

FreeParsed(messageId, pParsed);
pParsed = NULL;

调用方分配模型

在此模型中，调用方已确定要分析的正确特定 TLV，并且可能使用本地堆栈来避免在堆上进行分配。 调用方创建本地并调用特定的分析例程。 API 不需要消息 ID，并且 参数是强类型化，间接级别较低。

WDI_GET_ADAPTER_CAPABILITIES_PARAMETERS adapterCapabilitiesParsed;

ndisStatus = ParseWdiGetAdapterCapabilities(
    cbBufferLength,
    pvBuffer,
    &Context
    &adapterCapabilitiesParsed);

调用方使用完结构后，调用方应让分析程序有机会清理它在分析期间所做的任何分配，并擦除结构，以便可以重复使用。 参数是强类型，因此被调用方不需要任何其他参数。

CleanupParsedWdiGetAdapterCapabilities(&adapterCapabilitiesParsed);

调用 CleanupParse API 后，结构中的所有数据都无效。

某些消息没有任何关联数据。 为使 API 完整，提供了适当命名的分析方法。 这些方法验证字节流是否为空。 Typedefs 是为参数类型提供的，但如果调用方使用调用方分配模型，也可以为 out 参数传递 NULL。 在所有情况下，分析器都通过返回常量空分析结构来避免任何分配。 调用方绝不应写入此返回的空结构 (因此唯一字段名为 _Reserved) 。 这些消息记录为“没有其他数据。 标头中的数据就足够了”。

消息方向

大多数消息的 M1 格式与 M0、M3 或 M4 的格式不同。 为了适应这种情况，此类消息具有不同的分析和生成 API。 对于 M1 消息，API 遵循 Parse<MessageName>ToIhv 或 Generate<MessageName>ToIhv 的命名约定。 对于 M0、M3 或 M4 消息，API 遵循 Parse<MessageName>FromIhv 或 Generate<MessageName>FromIhv 的命名约定。 但是，为了简化 IHV 微型端口中的代码，定义添加到别名 Parse<MessageName> 到 Parse<MessageName>ToIhv 和 Generate<MessageName> 以从Ihv 生成<MessageName>。 IHV 代码仅当需要分析自己的 M3 或生成 M1 时，才需要注意此别名。

错误代码

TLV 分析器生成器可以返回多个不同的NDIS_STATUS代码。 有关详细信息，请参阅 WPP 跟踪日志。 日志应始终指示根本原因。 下面是最常见的错误代码及其含义的列表。

NDIS_STATUS_INVALID_DATA	分析时，这表示固定大小的 TLV 大小不正确。 对于列表，这意味着整体大小不是单个元素大小的偶数倍，或者元素数超出了应具有的数量。 当需要 1 个或更多个元素时，这也意味着包含 0 个元素的列表。 如果需要 0 个元素，则应 将Optional_IsPresent 设置为 false， (TLV 标头不应位于字节流) 中。
NDIS_STATUS_BUFFER_OVERFLOW	生成时，这表示由于数组中的元素数 (列表) ，它会溢出 TLV 标头中的 2 字节 Length 字段。 应减少元素数。 当外部 TLV 具有过多 (或内部 TLV) 过大，再次溢出标头的 2 字节 Length 字段时，也会发生这种情况。 分析时，这表示 TLV 标头的 Length 字段大于外部 TLV 或字节流。
NDIS_STATUS_FILE_NOT_FOUND	分析时，这表示字节流中不存在所需的 TLV。 它通常是包含字节流的生成器的 bug。
NDIS_STATUS_RESOURCES	生成时，这表示分配器失败。
NDIS_STATUS_UNSUPPORTED_REVISION	分析或生成时， Context 参数为 NULL，或者 PeerVersion 小于 WDI_VERSION_MIN_SUPPORTED。