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

Статья
02/07/2025

Драйверы используют структуру 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

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

GetSupported

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

MinProperty

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

MinData

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

SetPropertyHandler

Указатель на мини-driver, предоставленный 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 структуры, представляющие свойства, связанные с этим. Два свойства считаются связанными, если изменение одного свойства может повлиять на значение другого свойства. Флаги элемента каждой записи неиспользуются.

SupportHandler

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

SerializedSize

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

Замечания

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

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

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

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

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