структура KSPROPERTY_ITEM (ks.h)

Статья
03/09/2023

Драйверы используют структуру KSPROPERTY_ITEM, чтобы описать, как они поддерживают свойство в наборе свойств.

Синтаксис

typedef struct {
  ULONG                   PropertyId;
  union {
    PFNKSHANDLER GetPropertyHandler;
    BOOLEAN      GetSupported;
  };
  ULONG                   MinProperty;
  ULONG                   MinData;
  union {
    PFNKSHANDLER SetPropertyHandler;
    BOOLEAN      SetSupported;
  };
  const KSPROPERTY_VALUES *Values;
  ULONG                   RelationsCount;
  const KSPROPERTY        *Relations;
  PFNKSHANDLER            SupportHandler;
  ULONG                   SerializedSize;
} KSPROPERTY_ITEM, *PKSPROPERTY_ITEM;

Члены

PropertyId

Указывает идентификатор описываемого свойства.

GetPropertyHandler

Указатель на предоставленный мини-накопителем KStrGetPropertyHandler. Если значение РАВНО NULL, свойство не может быть прочитано. Этот член используется только драйверами, которые используют интерфейсы класса AVStream или Stream.

GetSupported

Задайте значение TRUE , если это свойство поддерживает запросы на получение, и FALSE , если это не так. (Драйвер класса выполняет запрос через запросы SRB_GET_DEVICE_PROPERTY или SRB_GET_STREAM_PROPERTY.) Этот член используется только мини-драйверами, работающими в классе stream.

MinProperty

Указывает минимальную длину буфера для хранения идентификатора свойства. Значение должно быть не менее sizeof(KSPROPERTY).

MinData

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

SetPropertyHandler

Указатель на предоставленный мини-накопителем KStrSetPropertyHandler. Если значение NULL, свойство невозможно задать. Этот член используется только драйверами, которые используют интерфейсы класса AVStream или Stream.

SetSupported

Задайте значение TRUE , если это свойство поддерживает запросы задания, и FALSE , если это не так. (Драйвер класса выполняет запрос через запросы SRB_SET_DEVICE_PROPERTY или SRB_SET_STREAM_PROPERTY.)

Values

Указатель на структуру типа KSPROPERTY_VALUES. Задает допустимые значения и (или) значения по умолчанию для свойства . Эти значения совпадают со значениями, указанными драйвером в ответ на запрос IOCTL_KS_PROPERTY с установленными флагами KSPROPERTY_TYPE_BASICSUPPORT и KSPROPERTY_TYPE_DEFAULTVALUES.

RelationsCount

Указывает количество записей в массиве, на который указывает элемент Relations .

Relations

Указывает на массив структур KSPROPERTY, представляющих свойства, связанные с этим. Два свойства считаются связанными, если изменение одного свойства может повлиять на значение другого свойства. Элемент Flags каждой записи не используется.

SupportHandler

Этот член предоставляется только в том случае, если вы реализуете собственный формат для необработанной сериализации или необработанной несериализации. Основные запросы поддержки, запросы диапазона и запросы связей автоматически обрабатываются AVStream, который возвращает соответствующие значения из других членов этой KSPROPERTY_ITEM структуры.

SerializedSize

Указывает размер свойства при сериализации в запросе KSPROPERTY_TYPE_SERIALIZESET. Значение должно быть равно нулю, если свойство не может быть сериализовано. Дополнительные сведения см. в разделе KSPROPERTY .

Stream мини-накопители класса используют KSPROPERTY_ITEM, чтобы описать клиенту, как выполнять запросы свойств для каждого свойства в наборе. Обработка набора свойств в целом указывается в структуре KSPROPERTY_SET , содержащей указатели на массивы KSPROPERTY_ITEM структур.

Драйвер класса stream обрабатывает запросы свойств от имени мини-драйвера. Когда драйверу класса потока требуется дополнительная информация от мини-драйвера, он передает запрос SRB_XXX одной из подпрограмм StrMiniReceiveXXXRequest мини-driver . Драйвер класса stream обрабатывает различные типы запросов, как указано в следующей таблице.

Значение флагов запроса свойства	Ответ
KSPROPERTY_TYPE_GET	Если getSupported имеет значение TRUE, драйвер класса потока отправляет запрос SRB_GET_DEVICE_PROPERTY или SRB_GET_STREAM_PROPERTY в соответствующую подпрограмму StrMiniReceiveXXXRequest мини-драйвера.
KSPROPERTY_TYPE_SET	Если параметр SetSupported имеет значение TRUE, драйвер класса потока отправляет запрос SRB_SET_DEVICE_PROPERTY или SRB_SET_STREAM_PROPERTY в соответствующую подпрограмму StrMiniReceiveXXXRequest .
KSPROPERTY_TYPE_BASICSUPPORT	Драйвер класса потока использует KSPROPERTY_ITEM для получения сведений, необходимых для выполнения этого запроса. Например, чтобы указать тип данных и допустимые диапазоны данных свойства, каждый из них использует элемент Values этой структуры.
KSPROPERTY_TYPE_SETSUPPORT	Драйвер класса потока завершает IRP запроса свойства как STATUS_SUCCESS только в том случае, если драйвер предоставляет запись для набора свойств в своей KSPROPERTY_SET структуре.
KSPROPERTY_TYPE_DEFAULTVALUES	Драйвер класса потока использует элемент Values этой структуры для определения значений по умолчанию для данных свойства.
KSPROPERTY_TYPE_RELATIONS	Драйвер класса потока использует член Relations , чтобы определить, какие свойства связаны с этим свойством.

Если клиент указывает KSPROPERTY_TYPE_DEFAULTVALUES, драйвер использует буфер данных для возврата описания своего типа значения, включая, возможно, допустимый диапазон и значение по умолчанию. Результат этого флага аналогичен KSPROPERTY_TYPE_BASICSUPPORT, за исключением того, что все возвращаемые значения — это значения, помеченные KSPROPERTY_MEMBER_FLAG_DEFAULT в элементе FlagsKSPROPERTY_MEMBERSHEADER структуры.

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