DXGK_SPB_INTERFACE 结构 (dispmprt.h)
DXGK_SPB_INTERFACE 结构包含指向简单外围总线 (SPB) 接口中的函数的指针，Windows 显示驱动程序模型 (WDDM) 1.2 及更高版本显示微型端口驱动程序可以调用该接口来检查和更改 SPB 资源。
语法
typedef struct _DXGK_SPB_INTERFACE {
USHORT Size;
USHORT Version;
PVOID Context;
PINTERFACE_REFERENCE InterfaceReference;
PINTERFACE_DEREFERENCE InterfaceDereference;
NTSTATUS(HANDLE DeviceHandle,LARGE_INTEGER SpbReourceId,UNICODE_STRING *SpbResourceSubName,ACCESS_MASK DesiredAccess,ULONG ShareAccess,ULONG OpenOptions,VOID **SpbResource) * )(OpenSpbResource;
NTSTATUS()(HANDLE DeviceHandle,VOID *SpbResource) * CloseSpbResource;
NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock) * )(HReadSpbResource;
NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG Length,VOID *Buffer,LARGE_INTEGER *ByteOffset,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock) * )(HWriteSpbResource;
NTSTATUS(ANDLE DeviceHandle,VOID *SpbResource,ULONG IoControlCode,ULONG InBufferSize,VOID *InputBuffer,ULONG OutBufferSize,VOID *OutputBuffer,HANDLE EventHandle,IO_STATUS_BLOCK *IoStatusBlock) * )(HSpbResourceIoControl;
} DXGK_SPB_INTERFACE, *PDXGK_SPB_INTERFACE;
成员
Size
此结构的大小（以字节为单位）。
Version
SPB 接口的版本号。 版本号常量在 Dispmprt.h (中定义，例如，DXGK_SPB_INTERFACE_VERSION_1) 。
Context
指向显示微型端口驱动程序提供的上下文的指针。
InterfaceReference
指向由显示微型端口驱动程序实现的接口引用函数的指针。
InterfaceDereference
指向由显示微型端口驱动程序实现的接口取消引用函数的指针。
OpenSpbResource
(SPB) 资源打开简单外围总线。 所有输入参数都由显示微型端口驱动程序提供。
| OpenSpbResource 参数 | 说明 |
|---|---|
| DeviceHandle | 表示显示适配器的句柄。 显示微型端口驱动程序以前在传递给 DxgkDdiStartDevice 函数的 DXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。 |
| SpbReourceId | SPB 资源中心的资源 ID。 |
| SpbResourceSubName | 指向 Unicode SPB 资源子名称的可选指针。 |
| DesiredAccess | 一个ACCESS_MASK值，用于确定对 SPB 资源的请求访问权限。 有关详细信息，请参阅 ZwCreateFile 函数的 DesiredAccess 参数。 |
| ShareAccess | 文件的共享访问类型。 有关详细信息，请参阅 ZwCreateFile 的 ShareAccess 参数。 |
| OpenOptions | 打开 SPB 资源时要应用的选项。 有关详细信息，请参阅 ZwCreateFile 的 CreateOptions 参数。 |
| SpbResource | 指向缓冲区的指针，用于将句柄返回到 SPB 资源。 |
CloseSpbResource
关闭 SPB 资源。 所有输入参数都由显示微型端口驱动程序提供。
关闭打开的对象句柄会导致该句柄无效。 系统还会递减对象的句柄计数，并检查是否可以删除该对象。 在关闭对象的所有句柄并且未保留引用的指针之前，系统不会实际删除对象。
驱动程序必须调用 CloseSpbResource ，以在不再需要句柄后立即关闭它已使用 OpenSpbResource 打开的每个句柄。
CloseSpbResource 的调用方不应假定此函数在返回之前自动等待所有 I/O 完成。
| CloseSpbResource 参数 | 说明 |
|---|---|
| DeviceHandle | 表示显示适配器的句柄。 显示微型端口驱动程序以前在传递给 DxgkDdiStartDevice 函数的 DXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。 |
| SpbResource | 指向显示微型端口驱动程序使用 OpenSpbResource 函数打开的 SPB 资源的指针。 |
ReadSpbResource
从打开的 SPB 资源读取数据。 所有输入参数都由显示微型端口驱动程序提供。
如果对 OpenSpbResource 的调用设置了在 Wdm.h) 中定义的 OpenOptions 标志FILE_SYNCHRONOUS_IO_ALERT或FILE_SYNCHRONOUS_IO_NONALERT (，则 I/O 管理器将维护当前文件位置。 如果是这样， ReadSpbResource 的调用方可以指定使用当前文件位置偏移量而不是显式 ByteOffset 值。 可以使用以下方法之一来制定此规范：
- 指定指向 LARGE_INTEGER 值的指针，其中 HighPart 成员设置为 -1，LowPart 成员设置为系统定义的值，FILE_USE_FILE_POINTER_POSITION Wdm.h) 中定义的 (。
- 为 ByteOffset 传递 NULL 指针。
ReadSpbResource 通过使用 I/O 管理器维护的当前文件位置，通过在完成读取操作时添加读取的字节数来更新当前文件位置。
即使 I/O 管理器维护当前文件位置，调用方也可以通过将显式 ByteOffset 值传递给 ReadSpbResource 来重置此位置。 执行此操作会自动将当前文件位置更改为该 ByteOffset 值，执行读取操作，然后根据实际读取的字节数更新位置。 此方法为调用方提供原子查找和读取服务。
| OpenSpbResource 参数 | 说明 |
|---|---|
| DeviceHandle | 表示显示适配器的句柄。 显示微型端口驱动程序以前在传递给 DxgkDdiStartDevice 函数的 DXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。 |
| SpbResource | 指向显示微型端口驱动程序使用 OpenSpbResource 函数打开的 SPB 资源的指针。 |
| 时长 | Buffer 参数指向的缓冲区的大小（以字节为单位）。 |
| Buffer | 指向接收从指定 SPB 资源读取的数据的缓冲区的指针。 |
| ByteOffset | 指向变量的可选指针，该变量指定将开始读取操作的 SPB 资源中的起始字节偏移量。 如果尝试读取文件末尾以外的内容， ReadSpbResource 将返回错误。 |
| EventHandle | 调用方创建的事件的可选句柄。 如果提供此参数，则调用方将进入等待状态，直到读取操作完成并且给定事件设置为 “已发出信号” 状态。 此参数可以为 NULL。 |
| IoStatusBlock | 指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态和有关所请求的读取操作的信息。 IO_STATUS_BLOCK 结构的 Information 成员接收实际从 SPB 资源读取的字节数。 |
WriteSpbResource
将数据写入打开的 SPB 资源。
如果对 OpenSpbResource 函数的调用仅设置 DesiredAccess 标志 FILE_APPEND_DATA，则 忽略 ByteOffset 参数。 在这种情况下， Buffer 参数指向的缓冲区中的数据（对于 长度 字节）从文件的当前末尾开始写入。
如果对 OpenSpbResource 的调用设置了 CreateOptions 标志之一、 FILE_SYNCHRONOUS_IO_ALERT 或 FILE_SYNCHRONOUS_IO_NONALERT，则 I/O 管理器将维护当前文件位置。 如果是这样， WriteSpbResource 的调用方可以指定使用当前文件位置偏移量而不是显式 ByteOffset 值。 可以使用以下方法之一来制定此规范：
- 指定指向 LARGE_INTEGER 值的指针，其中 HighPart 成员设置为 -1，LowPart 成员设置为系统定义的值FILE_USE_FILE_POINTER_POSITIONWdm.h) 中定义的 (。
- 为 ByteOffset 传递 NULL 指针。
WriteSpbResource 通过使用 I/O 管理器维护的当前文件位置，则通过添加完成写入操作时写入的字节数来更新当前文件位置。
即使 I/O 管理器维护当前文件位置，调用方也可以通过将显式 ByteOffset 值传递给 WriteSpbResource 来重置此位置。 执行此操作会自动将当前文件位置更改为该 ByteOffset 值，执行写入操作，然后根据实际写入的字节数更新位置。 此方法为调用方提供原子查找和写入服务。
还可以通过在 HighPart 设置为 -1 且 LowPart 设置为 FILE_WRITE_TO_END_OF_FILE 的情况下，为 ByteOffset 指定指向LARGE_INTEGER值的指针，使写入操作在文件的当前末尾开始。 无论 I/O 管理器是否维护当前文件位置，这都有效。
| WriteSpbResource 参数 | 说明 |
|---|---|
| DeviceHandle | 表示显示适配器的句柄。 显示微型端口驱动程序之前在传递给 DxgkDdiStartDevice 函数的 DXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。 |
| SpbResource | 指向显示微型端口驱动程序使用 OpenSpbResource 函数打开的 SPB 资源的指针。 |
| 时长 | Buffer 参数指向的缓冲区的大小（以字节为单位）。 |
| Buffer | 指向调用方分配的缓冲区的指针，该缓冲区包含要写入指定 SPB 资源的数据。 |
| ByteOffset | 指向变量的可选指针，该变量指定写入操作将开始的 SPB 资源中的起始字节偏移量。 如果 Length 和 ByteOffset 参数指定超过当前文件结束标记的写入操作， 则 WriteSpbResource 会自动扩展文件并更新文件结束标记;在此类旧标记和新文件结束标记之间未显式写入的任何字节都定义为零。 |
| EventHandle | 调用方创建的事件的可选句柄。 如果提供此参数，调用方将进入等待状态，直到写入操作完成，并将给定事件设置为 “已发出信号 ”状态。 此参数可以为 NULL。 |
| IoStatusBlock | 指向 IO_STATUS_BLOCK 结构的指针，该结构接收最终完成状态和有关请求的写入操作的信息。 IO_STATUS_BLOCK 结构的 Information 成员接收实际写入 SPB 资源的字节数。 |
SpbResourceIoControl
对打开的简单外围总线 (SPB) 资源执行 I/O 控制操作。 所有输入参数都由显示微型端口驱动程序提供。
如果调用方为异步 I/O (打开了文件，但两者均未 FILE_SYNCHRONOUS_XXX 创建/打开选项集) ，则指定的事件（如果有）将在设备控制操作完成时设置为 “已发出信号 ”状态。 否则， DeviceHandle 参数指定的文件对象将设置为 Signaled 状态。
| SpbResourceIoControl 参数 | 说明 |
|---|---|
| DeviceHandle | 表示显示适配器的句柄。 显示微型端口驱动程序之前在传递给 DxgkDdiStartDevice 函数的 DXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。 |
| SpbResource | 指向显示微型端口驱动程序使用 OpenSpbResource 函数打开的 SPB 资源的指针。 |
| IoControlCode | 设备 I/O 控制代码 (IOCTL_XXX) ，指示要对哪个设备 I/O 控制操作执行，通常由基础设备驱动程序执行。 此参数的值确定 InputBuffer 和 OutputBuffer 参数的格式和所需长度，以及以下哪些参数对是必需的。 |
| InBufferSize | InputBuffer 参数指向的缓冲区的大小（以字节为单位）。 如果 InputBuffer 为 NULL，则忽略此值。 |
| InputBuffer | 指向调用方分配的输入缓冲区的指针，该缓冲区包含要提供给目标设备的特定于设备的信息。 如果 IoControlCode 参数指定的操作不需要输入数据，则此指针可以为 NULL。 |
| OutBufferSize | OutputBuffer 参数指向的缓冲区的大小（以字节为单位）。 如果 OutputBuffer 为 NULL，则忽略此值。 |
| OutputBuffer | 指向调用方分配的输出缓冲区的指针，在该缓冲区中从目标设备返回信息。 如果 IoControlCode 参数指定的操作不生成输出数据，则此指针可以为 NULL。 |
| EventHandle | 调用方创建的事件的可选句柄。 如果提供此参数，调用方将进入等待状态，直到请求的操作完成，并将给定事件设置为 “已发出信号” 状态。 此参数可以为 NULL。 |
| IoStatusBlock | 指向一个变量的指针，该变量接收最终完成状态和有关所请求的 I/O 控制操作的信息。 对于返回数据的成功调用，将在 IO_STATUS_BLOCK 结构的 Information 成员中返回 OutputBuffer 参数指向的缓冲区中写入的字节数。 |
注解
若要使用此结构的函数，请首先提供 DXGK_SPB_INTERFACE 结构的 Size 和 Version 成员。 然后调用 DxgkCbQueryServices 函数，将 ServicesType 参数设置为 DxgkServicesFirmwareTable 的值，并将 Interface 参数设置为地址 (强制转换为 DXGK_SPB_INTERFACE 结构的 PINTERFACE) 。
有关 SPB 体系结构的详细信息，请参阅 简单外设总线 和 SPB 外设驱动程序设计指南**。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 8 |
| 最低受支持的服务器 | Windows Server 2012 |
| 标头 | dispmprt.h (包括 Dispmprt.h) |