vDbgPrintExWithPrefix 函数 (wdm.h)

如果满足指定的某些条件， vDbgPrintExWithPrefix 例程会将字符串发送到内核调试器。 此例程可以将前缀追加到调试器输出，以帮助组织调试结果。

语法

NTSYSAPI ULONG vDbgPrintExWithPrefix(
  [in] PCCH    Prefix,
  [in] ULONG   ComponentId,
  [in] ULONG   Level,
  [in] PCCH    Format,
  [in] va_list arglist
);

参数

[in] Prefix

在调试器输出的开头追加的字符串。 可以使用此字符串通过添加唯一标识符来组织调试器输出。

例如，特定于组件的例程可以在调用 vDbgPrintExWithPrefix 时指定组件的名称。 此例程会自动将组件名称添加到传递到组件调试打印例程的所有调试输出的开头。

[in] ComponentId

调用此例程的组件。 此参数必须是 Dpfilter.h 中定义的组件名称筛选器 ID 之一。 若要避免将驱动程序的输出与 Windows 组件的输出混合，应仅对 ComponentId 使用以下值：

• DPFLTR_IHVVIDEO_ID
• DPFLTR_IHVAUDIO_ID
• DPFLTR_IHVNETWORK_ID
• DPFLTR_IHVSTREAMING_ID
• DPFLTR_IHVBUS_ID
• DPFLTR_IHVDRIVER_ID

[in] Level

正在发送的消息的严重性。 此参数可以是任何 32 位整数。 介于 0 和 31 之间的值 (非独占) 与 32 到 0xFFFFFFFF 之间的值不同。 有关如何处理值的详细信息，请参阅 读取和筛选调试消息。

[in] Format

指向要打印的格式字符串的指针。 Format 字符串支持大多数 printf 样式的格式设置代码。 但是，只能在 IRQL = PASSIVE_LEVEL 的情况下使用 Unicode 格式代码 (%C、 %S、 %lc、 %ls、 %wc、 %ws 和 %w) Z 。 vDbgPrintExWithPrefix 例程不支持 (%f、%e、%E、%g、%G、%a 或 %A) 的任何浮点类型。

[in] arglist

格式字符串的参数列表。 vDbgPrintExWithPrefix 例程使用此列表的方式与 vprintf 相同。

返回值

如果操作成功，vDbgPrintExWithPrefix 将返回STATUS_SUCCESS。 否则，此例程将返回相应的错误代码。

注解

只有内核模式驱动程序可以调用 vDbgPrintExWithPrefix 例程。

可以在 IRQL = DIRQL <中调用 vDbgPrintExWithPrefix。 但是，只能在 IRQL = PASSIVE_LEVEL 中使用 Unicode 格式代码 (%wc 和 %ws) 。 此外，由于调试器使用进程间中断 (IPI) 与其他处理器通信，因此调用 IRQL > DIRQL 处的 vDbgPrintExWithPrefix 可能会导致死锁。

vDbgPrintExWithPrefix 要么将创建的字符串传递给内核调试器，要么不执行任何操作，具体取决于 ComponentId、 Level 和相应的组件筛选器掩码的值。 有关 vDbgPrintEx 的作用的详细信息，请参阅 读取和筛选调试消息。

除非绝对必要，否则不应从用户输入或其他进程获取字符串并将其传递给 vDbgPrintExWithPrefix。 如果确实使用了未创建的字符串，则必须验证此字符串是有效的格式字符串，并且格式代码与类型和数量的参数列表匹配。 最佳编码做法是，所有 格式 字符串都是静态的，并在编译时定义。

格式字符串的大小或参数列表中的参数数没有上限。 但是，对 vDbgPrintExWithPrefix 的任何单个调用仅传输 512 字节的信息。

调试器使用的缓冲区的大小也有限制。 有关此限制的详细信息，请参阅 DbgPrint 缓冲区和调试器。

此例程在 Wdm.h 中定义。 组件筛选器 ID 在 Dpfilter.h 中定义。

要求

另请参阅

DbgPrintEx

vDbgPrintEx