Поделиться через

структура HW_STREAM_REQUEST_BLOCK (strmini.h)

  • Статья

Драйвер класса stream использует структуру HW_STREAM_REQUEST_BLOCK для передачи информации в мини-диск и из нее с помощью предоставленных мини-накопителем обратных вызовов.

Синтаксис

typedef struct _HW_STREAM_REQUEST_BLOCK {
  ULONG                           SizeOfThisPacket;
  SRB_COMMAND                     Command;
  NTSTATUS                        Status;
  PHW_STREAM_OBJECT               StreamObject;
  PVOID                           HwDeviceExtension;
  PVOID                           SRBExtension;
  union {
    PKSSTREAM_HEADER                       DataBufferArray;
    PHW_STREAM_DESCRIPTOR                  StreamBuffer;
    KSSTATE                                StreamState;
    PSTREAM_TIME_REFERENCE                 TimeReference;
    PSTREAM_PROPERTY_DESCRIPTOR            PropertyInfo;
    PKSDATAFORMAT                          OpenFormat;
    struct _PORT_CONFIGURATION_INFORMATION *ConfigInfo;
    HANDLE                                 MasterClockHandle;
    DEVICE_POWER_STATE                     DeviceState;
    PSTREAM_DATA_INTERSECT_INFO            IntersectInfo;
    PVOID                                  MethodInfo;
    LONG                                   FilterTypeIndex;
    BOOLEAN                                Idle;
  } CommandData;
  _CommandData                    _CommandData;
  ULONG                           NumberOfBuffers;
  ULONG                           TimeoutCounter;
  ULONG                           TimeoutOriginal;
  struct _HW_STREAM_REQUEST_BLOCK *NextSRB;
  PIRP                            Irp;
  ULONG                           Flags;
  PVOID                           HwInstanceExtension;
  union {
    ULONG NumberOfBytesToTransfer;
    ULONG ActualBytesTransferred;
  };
  PKSSCATTER_GATHER               ScatterGatherBuffer;
  ULONG                           NumberOfPhysicalPages;
  ULONG                           NumberOfScatterGatherElements;
  ULONG                           Reserved[1];
} HW_STREAM_REQUEST_BLOCK, *PHW_STREAM_REQUEST_BLOCK;

Члены

SizeOfThisPacket

Задает размер этой структуры (в байтах).

Command

Указывает операцию, выполняемую обратным вызовом мини-накопителя. Драйвер класса передает коды команд SRB_XXX обратным вызовам мини-driver.

Status

Когда мини-хранилище завершает потоковый запрос, он заполняет этот элемент кодом состояния запроса. В документации описана соответствующая подпрограмма запросаStrMiniXxx для кодов состояния, которые, как ожидается, будут использоваться мини-устройствами.

StreamObject

Для потоковых запросов драйвер класса задает этот параметр, чтобы указать HW_STREAM_OBJECT структуру, указывающую поток, в котором драйвер класса выполняет запрос.

HwDeviceExtension

Указатель на расширение устройства мини-накопителя. Мини-диск может использовать этот буфер для записи личных сведений. Мини-диск устанавливает размер этого буфера в HW_INITIALIZATION_DATA структуре, которая передается при регистрации с помощью StreamClassRegisterMinidriver. Драйвер класса также передает указатели на этот буфер в члене HwDeviceExtensionHW_STREAM_OBJECT, HW_TIME_CONTEXT и PORT_CONFIGURATION_INFORMATION структурах, которые он передает в мини-диск.

SRBExtension

Указывает на неинициализированный буфер, выделенный драйвером класса для использования мини-накопителем при обработке этого блока запроса потока. Этот буфер освобождается после того, как мини-накопитель завершит обработку блока (дополнительные сведения см. в разделе StreamClassDeviceNotification или StreamClassStreamNotification ).

CommandData

CommandData — это объединение элементов, предоставляемое для данных, относящихся к командному коду.

CommandData.DataBufferArray

Указатель на массив KSSTREAM_HEADER структур. Количество записей в этом массиве указывается в поле NumberOfBuffers. Каждый KSSTREAM_HEADER описывает один блок данных.

Этот элемент используется, когда код команды SRB_READ_DATA или SRB_WRITE_DATA.

CommandData.StreamBuffer

Указывает на HW_STREAM_DESCRIPTOR структуру, заполняемую мини-накопителем, с описанием семантики потоковой передачи ядра, которая она поддерживает.

Мини-диск задает размер этого буфера в элементе StreamDescriptorSize своей PORT_CONFIGURATION_INFORMATION структуры.

Этот элемент используется, когда код команды SRB_GET_STREAM_INFO.

CommandData.StreamState

Состояние потока. Дополнительные сведения см. в разделе KSPROPERTY_CONNECTION_STATE .

Этот элемент используется, когда код команды SRB_GET_STREAM_STATE или SRB_SET_STREAM_STATE.

CommandData.TimeReference

Указатель на структуру STREAM_TIME_REFERENCE.

CommandData.PropertyInfo

Указывает на структуру STREAM_PROPERTY_DESCRIPTOR , указывающую параметры для операции получения или задания свойства.

Этот элемент используется, если код команды SRB_GET_DEVICE_PROPERTY, SRB_SET_DEVICE_PROPERTY, SRB_GET_STREAM_PROPERTY или SRB_SET_STREAM_PROPERTY.

CommandData.OpenFormat

Указатель на структуру KSDATAFORMAT , задающую формат.

Этот элемент используется, когда код команды SRB_OPEN_STREAM или SRB_PROPOSE_DATA_FORMAT.

CommandData.ConfigInfo

Указатель на структуру PORT_CONFIGURATION_INFORMATION , используемую для инициализации устройства

Этот элемент используется, когда код команды SRB_INITIALIZE_DEVICE.

CommandData.MasterClockHandle

Дескриптор объекта clock, который теперь служит в качестве master часов.

Этот элемент используется, когда код команды SRB_OPEN_MASTER_CLOCK или SRB_INDICATE_MASTER_CLOCK.

CommandData.DeviceState

Указывает новое состояние питания.

Этот член используется, когда код команды SRB_CHANGE_POWER_STATE.

CommandData.IntersectInfo

Указатель на структуру STREAM_DATA_INTERSECT_INFO , описывающую параметры этой операции.

Этот член используется, когда код команды SRB_GET_DATA_INTERSECTION.

CommandData.MethodInfo

Указатель на буфер, из который будут считываться или записываться данные метода.

CommandData.FilterTypeIndex

Индекс типа фильтра для SRB_OPEN_DEVICE_INSTANCE.

CommandData.Idle

Если открытых дескрипторов для устройства не остается, для этого элемента задано значение TRUE . Этот член имеет значение FALSE , если устройство больше не бездействует (был открыт дескриптор устройства).

Этот элемент используется, когда код команды SRB_NOTIFY_IDLE_STATE.

_CommandData

CommandData — это объединение элементов, предоставляемое для данных, относящихся к командному коду.

NumberOfBuffers

Если command является SRB_READ_DATA или SRB_WRITE_DATA, это указывает количество записей в массиве KSSTREAM_HEADER структур, который начинается с адреса, на который указывает CommandData.DataBufferArray. В противном случае этот параметр не используется.

TimeoutCounter

Количество секунд до истечения времени ожидания этого запроса. Драйвер класса уменьшает это значение один раз в секунду. Если драйвер класса уменьшает значение TimeoutCounter до нуля, прежде чем мини-драйвер завершит этот запрос, он вызовет подпрограмму StrMiniRequestTimeout для мини-накопителя . Если мини-диск устанавливает для этого параметра значение 0, время ожидания запроса не истекает.

TimeoutOriginal

Драйвер класса присваивает ей исходное значение TimeoutCounter при создании SRB.

NextSRB

Указывает на другой блок запроса потока. Мини-driver может использовать этот член для постановки в очередь блоков запросов потока.

Irp

Указатель на IRP для запроса. Большинству мини-драйверов не требуется использовать этот элемент.

Flags

Указывает тип запроса. Драйвер класса и мини-драйвер могут использовать этот член, чтобы определить, в какой обратный вызов драйвер класса передал этот блок запроса потока.

Значение Используемый обратный вызов
None StrMiniReceiveDevicePacket
SRB_HW_FLAGS_STREAM_REQUEST StrMiniReceiveStreamControlPacket
SRB_HW_FLAGS_DATA_TRANSFER StrMiniReceiveStreamDataPacket
SRB_HW_FLAGS_STREAM_REQUEST StrMiniReceiveStreamDataPacket

SRB_HW_FLAGS_STREAM_REQUEST бит устанавливается для запросов, зависящих от потока (которые передаются в подпрограммы пакета StrMiniReceiveStreamXxx). Бит SRB_HW_FLAGS_DATA_TRANSFER задается для запросов на передачу данных (которые передаются в мини-диск).

HwInstanceExtension

Указатель на расширение экземпляра мини-накопителя. Мини-накопитель может использовать этот буфер для записи личных сведений, глобальных в этот экземпляр мини-накопителя. Мини-диск устанавливает размер этого буфера в HW_INITIALIZATION_DATA структуре, которая передается при регистрации с помощью StreamClassRegisterMinidriver.

NumberOfBytesToTransfer

Количество передаваемых байтов для запроса SRB_READ_DATA или SRB_WRITE_DATA.

ActualBytesTransferred

Для контрольных запросов — количество фактически переданных байтов.

ScatterGatherBuffer

Указывает на массив KSSCATTER_GATHER структур в формате :

typedef struct {
    PHYSICAL_ADDRESS PhysicalAddress;
    ULONG Length;
} KSSCATTER_GATHER, *PKSSCATTER_GATHER;

Массив описывает список точечной и сборной, который может использоваться мини-накопителем для выполнения DMA. Память не требуется проверять, блокировать, сопоставлять или очищать. Драйвер класса stream выполняет эти действия для мини-драйвера.

NumberOfPhysicalPages

Задает размер массива, передаваемого в члене ScatterGatherBuffer .

NumberOfScatterGatherElements

Указывает количество физических элементов, на которые указывает ScatterGatherBuffer.

Reserved[1]

Поле Reserved[1] зарезервировано для использования системой. Не используйте.

Комментарии

Драйвер класса stream передает указатели на HW_STREAM_REQUEST_BLOCK структуры на подпрограммы StrMiniReceiveStreamDataPacket, StrMiniReceiveStreamControlPacket и StrMiniReceiveDevicePacket .

Мини-driver владеет этим блоком запросов потока до истечения времени ожидания запроса или завершения запроса. Мини-драйвер сообщает драйверу класса, что он выполнил запрос, вызывая StreamClassDeviceNotification(DeviceRequestComplete, pSrb-HwDeviceExtension>, pSRB) для запросов, относящихся к устройству, или вызывая StreamClassStreamNotification(StreamRequestComplete, pSrb-StreamObject>, pSrb) для запросов, зависящих от потока. (Мини-диск также может завершить запрос, вызвав StreamClassCompleteRequestAndMarkQueueReady(pSrb). Дополнительные сведения см. в этой процедуре.)

Если драйвер класса истечет время ожидания запроса, он вызовет подпрограмму StrMiniRequestTimeout мини-драйвера, которая отвечает за завершение обработки запроса. Если мини-driver помещает в очередь запрос для последующей обработки, он должен задать для элемента TimeoutCounter нулевое значение, что предотвратит превышение времени ожидания запроса драйвером класса. Когда мини-диск будет готов к возобновлению обработки запроса, он должен сбросить элемент TimeoutCounter на значение TimeoutOriginal.

Требования

Требование Значение
Заголовок strmini.h (включая Strmini.h)