структура DXGK_SPB_INTERFACE (dispmprt.h)
Структура DXGK_SPB_INTERFACE содержит указатели на функции в интерфейсе простой периферийной шины (SPB), которую может вызывать драйвер windows Display Driver Model (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 | Дескриптор, представляющий видеоадаптер. Драйвер мини-порта дисплея ранее получил этот дескриптор в элементе DeviceHandleструктуры DXGKRNL_INTERFACE , переданной функции DxgkDdiStartDevice . |
| SpbReourceId | Идентификатор ресурса концентратора ресурсов SPB. |
| SpbResourceSubName | Необязательный указатель на подимя ресурса SPB в Юникоде. |
| DesiredAccess | Значение ACCESS_MASK , определяющее запрошенный доступ к ресурсу SPB. Дополнительные сведения см. в разделе Параметр DesiredAccess функции ZwCreateFile . |
| ShareAccess | Тип доступа к общей папке для файла. Дополнительные сведения см. в разделе Параметр ShareAccessдля ZwCreateFile. |
| OpenOptions | Параметры, применяемые при открытии ресурса SPB. Дополнительные сведения см. в разделе Параметр CreateOptionsдля ZwCreateFile. |
| SpbResource | Указатель на буфер, используемый для возврата дескриптора в ресурс SPB. |
CloseSpbResource
Закрывает ресурс SPB. Все входные параметры предоставляются драйвером мини-порта дисплея.
Закрытие дескриптора открытого объекта приводит к тому, что этот дескриптор становится недействительным. Система также уменьшает количество дескрипторов для объекта и проверяет, можно ли удалить объект. Система фактически не удаляет объект до тех пор, пока все дескрипторы объекта не будут закрыты, а указатели на них не остаются.
Драйвер должен вызвать CloseSpbResource , чтобы закрыть каждый дескриптор, открытый с помощью OpenSpbResource , как только дескриптор больше не требуется.
Вызывающие методы CloseSpbResource не должны предполагать, что эта функция автоматически ожидает завершения всех операций ввода-вывода перед возвратом.
| Параметр CloseSpbResource | Описание |
|---|---|
| DeviceHandle | Дескриптор, представляющий видеоадаптер. Драйвер мини-порта дисплея ранее получил этот дескриптор в элементе DeviceHandleструктуры DXGKRNL_INTERFACE , переданной функции DxgkDdiStartDevice . |
| SpbResource | Указатель на ресурс SPB, открытый драйвером мини-порта дисплея с помощью функции OpenSpbResource . |
ReadSpbResource
Считывает данные из открытого ресурса SPB. Все входные параметры предоставляются драйвером мини-порта дисплея.
Если при вызове OpenSpbResource задан любой из флагов OpenOptionsFILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT (определенный в Wdm.h), диспетчер операций ввода-вывода сохраняет текущую позицию файла. В этом случае вызывающий объект ReadSpbResource может указать, что вместо явного значения ByteOffset используется смещение текущей позиции файла. Эту спецификацию можно сделать с помощью одного из следующих методов:
- Укажите указатель на значение LARGE_INTEGER с элементом HighPart , равным -1, а элемент LowPart — на системное значение FILE_USE_FILE_POINTER_POSITION (определенное в Wdm.h).
- Передайте указатель NULL для ByteOffset.
ReadSpbResource обновляет текущую позицию файла, добавляя количество байтов, считанных по завершении операции чтения, если используется текущая позиция файла, поддерживаемая диспетчером ввода-вывода.
Даже если диспетчер операций ввода-вывода сохраняет текущую позицию файла, вызывающий объект может сбросить эту позицию, передав явное значение ByteOffsetв ReadSpbResource. Это автоматически изменяет текущую позицию файла на это значение ByteOffset , выполняет операцию чтения, а затем обновляет позицию в соответствии с количеством фактически прочитанных байтов. Этот метод предоставляет вызывающей объекту атомарную службу поиска и чтения.
| Параметр OpenSpbResource | Описание |
|---|---|
| DeviceHandle | Дескриптор, представляющий видеоадаптер. Драйвер мини-порта дисплея ранее получил этот дескриптор в элементе DeviceHandleструктуры DXGKRNL_INTERFACE , переданной функции DxgkDdiStartDevice . |
| SpbResource | Указатель на ресурс SPB, открытый драйвером мини-порта дисплея с помощью функции OpenSpbResource . |
| Длина | Размер (в байтах) буфера, на который указывает параметр Buffer . |
| Буфер | Указатель на буфер, который получает данные, считываемые из указанного ресурса SPB. |
| ByteOffset | Необязательный указатель на переменную, указывающую начальное смещение байтов в ресурсе SPB, где начнется операция чтения. Если предпринята попытка чтения за пределами конца файла, функция ReadSpbResource возвращает ошибку. |
| EventHandle | Необязательный дескриптор для события, созданного вызывающим. Если этот параметр указан, вызывающий объект будет переведен в состояние ожидания, пока операция чтения не будет завершена, а заданному событию будет присвоено состояние Signaled . Этот параметр может принимать значение NULL. |
| IoStatusBlock | Указатель на структуру IO_STATUS_BLOCK , получающую окончательное состояние завершения и сведения о запрошенной операции чтения. Элемент Information структуры IO_STATUS_BLOCK получает количество байтов, фактически считанных из ресурса SPB. |
WriteSpbResource
Записывает данные в открытый ресурс SPB.
Если вызов функции OpenSpbResource задает только флаг DesiredAccessFILE_APPEND_DATA, параметр ByteOffset игнорируется. В этом случае данные в буфере, на который указывает параметр Buffer для байтов длины , записываются, начиная с текущего конца файла.
Если при вызове OpenSpbResource задан любой из флагов CreateOptions , FILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT, диспетчер ввода-вывода сохраняет текущую позицию файла. Если это так, вызывающий объект WriteSpbResource может указать, что вместо явного значения ByteOffset используется текущее смещение позиции файла. Эту спецификацию можно сделать с помощью одного из следующих методов:
- Укажите указатель на значение LARGE_INTEGER с элементом HighPart , равным -1, а для элемента LowPart — системное значение , FILE_USE_FILE_POINTER_POSITION (определенное в Wdm.h).
- Передайте указатель NULL для ByteOffset.
WriteSpbResource обновляет текущую позицию файла, добавляя количество байтов, записанных при завершении операции записи, если используется текущая позиция файла, поддерживаемая диспетчером ввода-вывода.
Даже если диспетчер ввода-вывода сохраняет текущую позицию файла, вызывающий объект может сбросить эту позицию, передав явное значение ByteOffsetв WriteSpbResource. Это автоматически изменяет текущую позицию файла на это значение ByteOffset , выполняет операцию записи, а затем обновляет позицию в соответствии с фактически записанным числом байтов. Этот метод предоставляет вызывающей объекту атомарную службу поиска и записи.
Кроме того, можно вызвать запуск операции записи в текущем конце файла, указав для ByteOffset указатель на LARGE_INTEGER значение, если HighPart имеет значение -1, а LowPart — FILE_WRITE_TO_END_OF_FILE. Это работает независимо от того, поддерживает ли диспетчер ввода-вывода текущую позицию файла.
| Параметр WriteSpbResource | Описание |
|---|---|
| DeviceHandle | Дескриптор, представляющий видеоадаптер. Драйвер мини-порта дисплея ранее получил этот дескриптор в элементе DeviceHandleструктуры DXGKRNL_INTERFACE , переданной функции DxgkDdiStartDevice . |
| SpbResource | Указатель на ресурс SPB, открытый драйвером мини-порта дисплея с помощью функции OpenSpbResource . |
| Длина | Размер (в байтах) буфера, на который указывает параметр Buffer . |
| Буфер | Указатель на буфер, выделенный вызывающим объектом, который содержит данные для записи в указанный ресурс SPB. |
| ByteOffset | Необязательный указатель на переменную, указывающую смещение начального байта в ресурсе SPB, с которого начнется операция записи. Если параметры Length и ByteOffset указывают операцию записи после текущей метки окончания файла, WriteSpbResource автоматически расширяет файл и обновляет метку конца файла; все байты, которые не записываются явным образом между такими старыми и новыми метками окончания файла, определяются как нулевые. |
| EventHandle | Необязательный дескриптор для события, созданного вызывающим абонентом. Если указан этот параметр, вызывающий объект будет переведен в состояние ожидания, пока операция записи не будет завершена, а заданному событию будет присвоено состояние Signaled . Этот параметр может принимать значение NULL. |
| IoStatusBlock | Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения о запрошенной операции записи. Элемент Information структуры IO_STATUS_BLOCK получает количество байтов, фактически записанных в ресурс SPB. |
SpbResourceIoControl
Выполняет операцию управления вводом-выводом для открытого ресурса простой периферийной шины (SPB). Все входные параметры предоставляются драйвером мини-порта дисплея.
Если вызывающий объект открыл файл для асинхронного ввода-вывода (без FILE_SYNCHRONOUS_XXX набора параметров create/open), указанное событие, если таковое есть, будет установлено в состояние Signaled после завершения операции управления устройством. В противном случае объект файла, указанный параметром DeviceHandle , будет установлен в состояние Signaled .
| Параметр SpbResourceIoControl | Описание |
|---|---|
| DeviceHandle | Дескриптор, представляющий видеоадаптер. Драйвер мини-порта дисплея ранее получил этот дескриптор в элементе DeviceHandleструктуры DXGKRNL_INTERFACE , переданной функции DxgkDdiStartDevice . |
| SpbResource | Указатель на ресурс SPB, открытый драйвером мини-порта дисплея с помощью функции OpenSpbResource . |
| IoControlCode | Код управления вводом-выводом устройства (IOCTL_XXX), указывающий, какая операция управления вводом-выводом устройства должна быть выполнена, как правило, базовым драйвером устройства. Значение этого параметра определяет формат и требуемую длину параметров InputBuffer и OutputBuffer , а также то, какие из следующих пар параметров являются обязательными. |
| InBufferSize | Размер (в байтах) буфера, на который указывает параметр InputBuffer . Это значение игнорируется, если inputBuffer имеет значение NULL. |
| InputBuffer | Указатель на выделенный вызывающим объектом входной буфер, содержащий сведения о конкретном устройстве, которые будут переданы целевому устройству. Если параметр IoControlCode указывает операцию, которая не требует входных данных, этот указатель может иметь значение NULL. |
| OutBufferSize | Размер (в байтах) буфера, на который указывает параметр OutputBuffer . Это значение игнорируется, если OutputBuffer имеет значение NULL. |
| OutputBuffer | Указатель на выделенный вызывающим объектом выходной буфер, в котором данные возвращаются с целевого устройства. Если параметр IoControlCode указывает операцию, которая не создает выходные данные, этот указатель может иметь значение NULL. |
| EventHandle | Необязательный дескриптор для события, созданного вызывающим абонентом. Если указан этот параметр, вызывающий объект будет переведен в состояние ожидания, пока запрошенная операция не будет завершена, а заданному событию будет присвоено состояние Signaled . Этот параметр может принимать значение NULL. |
| IoStatusBlock | Указатель на переменную, которая получает окончательное состояние завершения и сведения о запрошенной операции управления вводом-выводом. Для успешных вызовов, возвращающих данные, число байтов, записанных в буфер, на который указывает параметр OutputBuffer , возвращается в элементе Informationструктуры IO_STATUS_BLOCK . |
Комментарии
Чтобы использовать функции этой структуры, сначала укажите элементы Size и Versionструктуры DXGK_SPB_INTERFACE . Затем вызовите функцию DxgkCbQueryServices , присвоив параметру ServicesType значение DxgkServicesFirmwareTable, а для параметра Interface задайте адрес (приведение к PINTERFACE) структуры DXGK_SPB_INTERFACE .
Дополнительные сведения об архитектуре SPB см. в разделе Simple PeripheralBus and SPB Peripheral Driver Design Guide**.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8 |
| Минимальная версия сервера | Windows Server 2012 |
| Верхняя часть | dispmprt.h (включая Dispmprt.h) |
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по