DXGK_SPB_INTERFACE estructura (dispmprt.h)

La estructura de DXGK_SPB_INTERFACE contiene punteros a funciones de la interfaz simple de Bus periférico (SPB) a la que un controlador de controlador de pantalla de Windows (WDDM) 1.2 y versiones posteriores pueden llamar al controlador de miniporte para inspeccionar y modificar los recursos de SPB.

Sintaxis

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;

Miembros

Size

Tamaño, en bytes, de esta estructura.

Version

Número de versión de la interfaz SPB. Las constantes de número de versión se definen en Dispmprt.h (por ejemplo, DXGK_SPB_INTERFACE_VERSION_1).

Context

Puntero a un contexto proporcionado por el controlador de minipuerto de pantalla.

InterfaceReference

Puntero a una función de referencia de interfaz implementada por el controlador de minipuerto de pantalla.

InterfaceDereference

Puntero a una función de desreferencia de interfaz implementada por el controlador de minipuerto de pantalla.

OpenSpbResource

Abre un recurso de Bus periférico simple (SPB). El controlador de miniporte de pantalla proporciona todos los parámetros de entrada.

Parámetro OpenSpbResource	Descripción
DeviceHandle	Identificador que representa un adaptador de pantalla. El controlador de minipuerto de pantalla obtuvo previamente este identificador en el miembro DeviceHandle de la estructura de DXGKRNL_INTERFACE que se pasó a la función DxgkDdiStartDevice .
SpbReourceId	Identificador de recurso del centro de recursos de SPB.
SpbResourceSubName	Puntero opcional al subnombre de recurso SPB Unicode.
DesiredAccess	Valor ACCESS_MASK que determina el acceso solicitado al recurso SPB. Para obtener más información, vea el parámetro DesiredAccess de la función ZwCreateFile .
ShareAccess	Tipo de acceso a recursos compartidos para el archivo. Para obtener más información, vea el parámetro ShareAccess de ZwCreateFile.
OpenOptions	Las opciones que se aplicarán al abrir el recurso SPB. Para obtener más información, vea el parámetro CreateOptions de ZwCreateFile.
SpbResource	Puntero a un búfer que se usa para devolver el identificador al recurso SPB.

CloseSpbResource

Cierra un recurso SPB. El controlador de miniporte de pantalla proporciona todos los parámetros de entrada.

El cierre de un identificador de objeto abierto hace que ese identificador no sea válido. El sistema también disminuye el número de identificadores del objeto y comprueba si el objeto se puede eliminar. El sistema no elimina realmente el objeto hasta que se cierran todos los identificadores del objeto y no quedan punteros a los que se hace referencia.

El controlador debe llamar a CloseSpbResource para cerrar todos los identificadores que ha abierto con OpenSpbResource en cuanto el identificador ya no sea necesario.

Los autores de llamadas de CloseSpbResource no deben suponer que esta función espera automáticamente a que se completen todas las E/S antes de devolver.

Parámetro CloseSpbResource	Descripción
DeviceHandle	Identificador que representa un adaptador de pantalla. El controlador de minipuerto de pantalla obtuvo previamente este identificador en el miembro DeviceHandle de la estructura de DXGKRNL_INTERFACE que se pasó a la función DxgkDdiStartDevice .
SpbResource	Puntero a un recurso SPB que el controlador de minipuerto de pantalla abrió mediante la función OpenSpbResource .

ReadSpbResource

Lee datos de un recurso SPB abierto. El controlador de miniporte de pantalla proporciona todos los parámetros de entrada.

Si la llamada a OpenSpbResource establece cualquiera de las marcas OpenOptionsFILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT (definida en Wdm.h), el Administrador de E/S mantiene la posición actual del archivo. Si es así, el autor de la llamada de ReadSpbResource puede especificar que se use el desplazamiento de posición del archivo actual en lugar de un valor ByteOffset explícito. Esta especificación se puede realizar mediante uno de los métodos siguientes:

• Especifique un puntero a un valor de LARGE_INTEGER con el miembro HighPart establecido en -1 y el miembro LowPart establecido en el valor definido por el sistema FILE_USE_FILE_POINTER_POSITION (definido en Wdm.h).
• Pase un puntero NULL para ByteOffset.

ReadSpbResource actualiza la posición del archivo actual agregando el número de bytes leídos cuando completa la operación de lectura, si usa la posición del archivo actual mantenida por el Administrador de E/S.

Incluso cuando el Administrador de E/S mantiene la posición actual del archivo, el autor de la llamada puede restablecer esta posición pasando un valor ByteOffset explícito a ReadSpbResource. Esto cambia automáticamente la posición del archivo actual a ese valor ByteOffset , realiza la operación de lectura y, a continuación, actualiza la posición según el número de bytes leídos realmente. Esta técnica proporciona al autor de la llamada servicio atomic seek-and-read.

Parámetro OpenSpbResource	Descripción
DeviceHandle	Identificador que representa un adaptador de pantalla. El controlador de minipuerto de pantalla obtuvo previamente este identificador en el miembro DeviceHandle de la estructura de DXGKRNL_INTERFACE que se pasó a la función DxgkDdiStartDevice .
SpbResource	Puntero a un recurso SPB que el controlador de minipuerto de pantalla abrió mediante la función OpenSpbResource .
Duración	Tamaño, en bytes, del búfer al que apunta el parámetro Buffer .
Buffer	Puntero a un búfer que recibe los datos leídos del recurso SPB especificado.
ByteOffset	Puntero opcional a una variable que especifica el desplazamiento de bytes inicial en el recurso SPB donde se iniciará la operación de lectura. Si se intenta leer más allá del final del archivo, ReadSpbResource devuelve un error.
EventHandle	Identificador opcional para un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se pondrá en un estado de espera hasta que se complete la operación de lectura y el evento especificado se establezca en el estado Signaled . Este parámetro puede ser NULL.
IoStatusBlock	Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación de lectura solicitada. El miembro Information de la estructura IO_STATUS_BLOCK recibe el número de bytes leídos realmente del recurso SPB.

WriteSpbResource

Escribe datos en un recurso SPB abierto.

Si la llamada a la función OpenSpbResource establece solo la marca DesiredAccessFILE_APPEND_DATA, se omite el parámetro ByteOffset . En este caso, los datos del búfer a los que apunta el parámetro Buffer , para Bytes de longitud , se escriben a partir del final actual del archivo.

Si la llamada a OpenSpbResource establece cualquiera de las marcas CreateOptions , FILE_SYNCHRONOUS_IO_ALERT o FILE_SYNCHRONOUS_IO_NONALERT, el Administrador de E/S mantiene la posición del archivo actual. Si es así, el autor de la llamada de WriteSpbResource puede especificar que se use el desplazamiento de posición del archivo actual en lugar de un valor ByteOffset explícito. Esta especificación se puede realizar mediante uno de los métodos siguientes:

• Especifique un puntero a un valor de LARGE_INTEGER con el miembro HighPart establecido en -1 y el miembro LowPart establecido en el valor definido por el sistema FILE_USE_FILE_POINTER_POSITION (definido en Wdm.h).
• Pase un puntero NULL para ByteOffset.

WriteSpbResource actualiza la posición del archivo actual agregando el número de bytes escritos cuando completa la operación de escritura, si usa la posición del archivo actual mantenida por el Administrador de E/S.

Incluso cuando el Administrador de E/S mantiene la posición actual del archivo, el autor de la llamada puede restablecer esta posición pasando un valor ByteOffset explícito a WriteSpbResource. Esto cambia automáticamente la posición del archivo actual a ese valor ByteOffset , realiza la operación de escritura y, a continuación, actualiza la posición según el número de bytes realmente escritos. Esta técnica proporciona al autor de la llamada servicio atomic seek-and-write.

También es posible hacer que una operación de escritura se inicie al final actual del archivo especificando para ByteOffset un puntero a un valor de LARGE_INTEGER con HighPart establecido en -1 y LowPart establecido en FILE_WRITE_TO_END_OF_FILE. Esto funciona independientemente de si el Administrador de E/S mantiene la posición actual del archivo.

WriteSpbResource (parámetro)	Descripción
DeviceHandle	Identificador que representa un adaptador de pantalla. El controlador de minipuerto de pantalla obtuvo anteriormente este identificador en el miembro DeviceHandle de la estructura DXGKRNL_INTERFACE que se pasó a la función DxgkDdiStartDevice .
SpbResource	Puntero a un recurso SPB que el controlador de miniporte de pantalla abrió mediante la función OpenSpbResource .
Duración	Tamaño, en bytes, del búfer al que apunta el parámetro Buffer .
Buffer	Puntero a un búfer asignado por el autor de la llamada que contiene los datos que se van a escribir en el recurso SPB especificado.
ByteOffset	Puntero opcional a una variable que especifica el desplazamiento de bytes inicial en el recurso SPB donde se iniciará la operación de escritura. Si los parámetros Length y ByteOffset especifican una operación de escritura más allá de la marca de fin de archivo actual, WriteSpbResource extiende automáticamente el archivo y actualiza la marca de fin de archivo; los bytes que no se escriben explícitamente entre estas marcas de fin de archivo antiguas y nuevas se definen como cero.
EventHandle	Identificador opcional para un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se colocará en un estado de espera hasta que se complete la operación de escritura y el evento especificado se establezca en el estado Signaled . Este parámetro puede ser NULL.
IoStatusBlock	Puntero a una estructura de IO_STATUS_BLOCK que recibe el estado de finalización final e información sobre la operación de escritura solicitada. El miembro Information de la estructura IO_STATUS_BLOCK recibe el número de bytes escritos realmente en el recurso SPB.

SpbResourceIoControl

Realiza una operación de control de E/S en un recurso de Bus periférico simple (SPB) abierto. El controlador de miniporte de pantalla proporciona todos los parámetros de entrada.

Si el autor de la llamada abrió el archivo para E/S asincrónica (sin FILE_SYNCHRONOUS_XXX conjunto de opciones de creación y apertura), el evento especificado, si existe, se establecerá en el estado Señalizado cuando se complete la operación de control de dispositivo. De lo contrario, el objeto de archivo especificado por el parámetro DeviceHandle se establecerá en el estado Signaled .

Parámetro SpbResourceIoControl	Descripción
DeviceHandle	Identificador que representa un adaptador de pantalla. El controlador de minipuerto de pantalla obtuvo anteriormente este identificador en el miembro DeviceHandle de la estructura DXGKRNL_INTERFACE que se pasó a la función DxgkDdiStartDevice .
SpbResource	Puntero a un recurso SPB que el controlador de miniporte de pantalla abrió mediante la función OpenSpbResource .
IoControlCode	Un código de control de E/S de dispositivo (IOCTL_XXX) que indica en qué operación de control de E/S de dispositivo se va a realizar, normalmente por el controlador de dispositivo subyacente. El valor de este parámetro determina el formato y la longitud necesaria de los parámetros InputBuffer y OutputBuffer , así como los pares de parámetros siguientes.
InBufferSize	Tamaño, en bytes, del búfer al que apunta el parámetro InputBuffer . Este valor se omite si InputBuffer es NULL.
InputBuffer	Puntero a un búfer de entrada asignado por el autor de la llamada que contiene información específica del dispositivo que se va a proporcionar al dispositivo de destino. Si el parámetro IoControlCode especifica una operación que no requiere datos de entrada, este puntero puede ser NULL.
OutBufferSize	Tamaño, en bytes, del búfer al que apunta el parámetro OutputBuffer . Este valor se omite si OutputBuffer es NULL.
OutputBuffer	Puntero a un búfer de salida asignado por el autor de la llamada en el que se devuelve información del dispositivo de destino. Si el parámetro IoControlCode especifica una operación que no genera datos de salida, este puntero puede ser NULL.
EventHandle	Identificador opcional para un evento creado por el autor de la llamada. Si se proporciona este parámetro, el autor de la llamada se colocará en un estado de espera hasta que se complete la operación solicitada y el evento especificado se establezca en el estado Signaled . Este parámetro puede ser NULL.
IoStatusBlock	Puntero a una variable que recibe el estado de finalización final e información sobre la operación de control de E/S solicitada. Para llamadas correctas que devuelven datos, el número de bytes escritos en el búfer al que apunta el parámetro OutputBuffer se devuelve en el miembro Information de la estructura IO_STATUS_BLOCK .

Comentarios

Para usar las funciones de esta estructura, primero proporcione los miembros Size y Version de la estructura DXGK_SPB_INTERFACE . A continuación, llame a la función DxgkCbQueryServices con el parámetro ServicesType establecido en un valor de DxgkServicesFirmwareTable y establezca el parámetro Interface en la dirección (conversión como PINTERFACE) de la estructura DXGK_SPB_INTERFACE .

Para obtener más información sobre la arquitectura de SPB, vea Simple Peripheral Buses and SPB Peripheral Driver Design Guide**.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8
Servidor mínimo compatible	Windows Server 2012
Encabezado	dispmprt.h (include Dispmprt.h)