VIDEO_PORT_DEBUG_REPORT_INTERFACE 结构 (video.h)

项目
02/29/2024

VIDEO_PORT_DEBUG_REPORT_INTERFACE结构包含指向调试报告函数的指针，这些函数由视频端口驱动程序实现。

语法

typedef struct _VIDEO_PORT_DEBUG_REPORT_INTERFACE
{
    IN USHORT                  Size;
    IN USHORT                  Version;
    OUT PVOID                  Context;
    OUT PINTERFACE_REFERENCE   InterfaceReference;
    OUT PINTERFACE_DEREFERENCE InterfaceDereference;

    OUT
    PVIDEO_DEBUG_REPORT
    (*DbgReportCreate)(
        IN PVOID HwDeviceExtension,
        IN ULONG ulCode,
        IN ULONG_PTR ulpArg1,
        IN ULONG_PTR ulpArg2,
        IN ULONG_PTR ulpArg3,
        IN ULONG_PTR ulpArg4
        );

    OUT
    BOOLEAN
    (*DbgReportSecondaryData)(
        IN OUT PVIDEO_DEBUG_REPORT pReport,
        IN PVOID pvData,
        IN ULONG ulDataSize
        );

    OUT
    VOID
    (*DbgReportComplete)(
        IN OUT PVIDEO_DEBUG_REPORT pReport
        );
} VIDEO_PORT_DEBUG_REPORT_INTERFACE, *PVIDEO_PORT_DEBUG_REPORT_INTERFACE;

成员

Size

指定此结构的大小（以字节为单位）。

Version

指定视频端口驱动程序返回的接口的版本。目前，唯一受支持的版本是VIDEO_PORT_DEBUG_REPORT_INTERFACE_VERSION_1。

Context

指向视频端口驱动程序提供的上下文的指针。

InterfaceReference

指向由视频端口驱动程序实现的接口引用函数的指针。

InterfaceDereference

指向由视频端口驱动程序实现的接口取消引用函数的指针。

OUT (IN PVOID HwDeviceExtension,IN ULONG ulCode,IN ULONG_PTR ulpArg1,IN ULONG_PTR ulpArg2,IN ULONG_PTR ulpArg3,IN ULONG_PTR ulpArg4) PVIDEO_DEBUG_REPORT( *DbgReportCreate unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport,IN PVOID pvData,IN ULONG ulDataSize) BOOLEAN( *DbgReportSecondaryData unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport) VOID( *DbgReportComplete unnamedParam1)

注解

视频微型端口驱动程序提供此结构的 Size 和 Version 成员，然后调用 VideoPortQueryServices，这将初始化其剩余成员。

如果视频微型端口驱动程序检测到故障，然后从中恢复，则可以创建一个错误报告，稍后可以通过调用 VIDEO_PORT_DEBUG_REPORT_INTERFACE 的回调函数成员来用于调试，如下所示：

首先，调用 DbgReportCreate 来创建初始报表。
然后，通过对 DbgReportSecondaryData 进行一次或多项调用，将数据添加到报表。
将数据添加到报表后，请调用 DbgReportComplete。

错误报告保存在文件中，并计划在计算机重新启动时发送给 Microsoft。错误报告包含一个错误代码和四个参数。错误代码和前三个参数由 DbgReportCreate 的调用方提供。报表中的第四个参数由操作系统提供，指示自计算机启动以来生成的报表数。例如，如果 ulpArg4 的值为 5，则表示自上次启动计算机以来，显示微型端口驱动程序会生成四个以前的错误报告。仅保存第五个报表，因为每个报表都覆盖了上一个报表。

DbgReportCreate 返回并随后传递给 DbgReportSecondaryData 和 DbgReportComplete 的VIDEO_DEBUG_REPORT结构是不透明的。请勿尝试直接访问其成员。

以下部分详细介绍了这些回调函数。必须在 IRQL = PASSIVE_LEVEL 调用这些回调。

DbgReportCreate

DbgReportCreate 创建初始错误报告。它会在系统事件日志中创建一个条目，并显示一个对话框，该对话框通知用户失败并提供了将错误报告上传到 Microsoft 的机会。 DbgReportCreate 返回指向不透明 VIDEO_DEBUG_REPORT 结构的指针，该结构表示新创建的调试报表的句柄。

DbgReportCreate 参数

HwDeviceHandle [in] 与显示适配器关联的上下文块的句柄。显示微型端口驱动程序在其 DxgkDdiAddDevice 函数中创建此句柄。此参数可以为 NULL。
ulCode [in] 错误报告的代码。支持以下代码：THREAD_STUCK_IN_DEVICE_DRIVER VIDEO_DRIVER_DEBUG_REPORT_REQUEST、VIDEO_TDR_FATAL_ERROR和VIDEO_TDR_SUCCESS。
ulpArg1 [in] 要添加到报表中的第一个参数。显示微型端口驱动程序的开发人员确定 ulpArg1 的值和含义。
ulpArg2 [in] 要添加到报表中的第二个参数。显示微型端口驱动程序的开发人员确定 ulpArg2 的值和含义。
ulpArg3 [in] 要添加到报表的第三个参数。显示微型端口驱动程序的开发人员确定 ulpArg3 的值和含义。
ulpArg4 [in] 保留以供系统使用。

DbgReportSecondaryData

DbgReportSecondaryData 函数将数据追加到先前由 DbgReportCreate 创建的初始错误报告。如果 DbgReportSecondaryData 成功，则返回 TRUE。否则，它将返回 FALSE。

调用 DbgReportSecondaryData ，将数据添加到先前调用 DbgReportCreate 创建的初始报表。可以多次调用 DbgReportSecondaryData ，但每次调用时，写入报表的数据都会覆盖上一次调用写入的数据。以下步骤提供了以增量方式向报表添加数据的良好策略。

获取最安全收集的数据。
调用 DbgReportSecondaryData 以将数据写入报表。
获取收集风险更大的数据。
调用 DbgReportSecondaryData 将原始安全数据以及新收集的风险数据写入报表。必须在此调用中包含安全和有风险的数据，因为此调用写入的数据会覆盖第一次调用 DbgReportSecondaryData 所写入的数据。
继续调用 DbgReportSecondaryData，每次增强数据，直到没有更多要添加的数据。

将数据添加到报表后，通过调用 DbgReportComplete 关闭报表。如果计算机在调用 DbgReportComplete 之前停止响应，则会保存最近成功调用 DbgReportSecondaryData 添加到报表的数据，然后在计算机重新启动时发送到 Microsoft。

DbgReportSecondaryData 参数

hReport [in， out] 数据将追加到的错误报表的句柄。显示微型端口驱动程序以前通过调用 DbgReportCreate 获取此句柄。
pvData [in] 指向缓冲区的指针，该缓冲区保存要添加到报表中的数据。
ulDataSize [in] 要添加到报表的数据的大小（以字节为单位）。此参数的值必须小于或等于 DXGK_DEBUG_REPORT_MAX_SIZE。

DbgReportComplete

DbgReportComplete 函数关闭错误报告并释放与报表关联的任何资源。

DbgReportComplete 在系统事件日志中创建一个条目，并显示一个对话框，告知用户失败以及将错误报告上传到 Microsoft 的机会。

DbgReportComplete 参数

hReport 指向 VIDEO_DEBUG_REPORT 结构的指针，该结构包含要关闭的错误报告的句柄。显示微型端口驱动程序以前通过调用 DbgReportCreate 获取此句柄。

要求

要求	值
最低受支持的客户端	Windows XP SP2
最低受支持的服务器	Windows Server 2003 SP1
标头	video.h (包括 Video.h)

另请参阅

接口

VideoPortQueryServices

通过