Структура KSPROPERTY

Статья
06/15/2023

Структура KSPROPERTY указывает одно свойство потоковой передачи ядра в наборе свойств.

Структуры KSEVENT, KSMETHOD и KSPROPERTY являются псевдонимами для структуры KSIDENTIFIER . Таким образом, их определения идентичны.

Синтаксис

struct KSPROPERTY {
  GUID Set;
  ULONG Id;
  ULONG Flags;
};

Члены

Set

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

Id

Указывает член набора свойств.

Flags

Указывает тип запроса. Если вы пишете мини-хранилище класса потока, см. также KSPROPERTY_ITEM сведения о флаге класса.

Флаги должны быть одним из значений, перечисленных в следующей таблице. Некоторые флаги можно объединить с помощью побитовой операции ИЛИ.

Значение	Описание
KSPROPERTY_TYPE_GET	Извлекает значение указанного элемента свойства.
KSPROPERTY_TYPE_SET	Задает значение указанного элемента свойства.
KSPROPERTY_TYPE_SETSUPPORT	Запрашивает, поддерживает ли драйвер этот набор свойств.
KSPROPERTY_TYPE_BASICSUPPORT	Запрашивает типы запросов, обрабатываемые драйвером для этого элемента свойства. Возвращает KSPROPERTY_TYPE_GET , KSPROPERTY_TYPE_SET или и то, и другое. Все наборы свойств должны поддерживать этот флаг.
KSPROPERTY_TYPE_DEFAULTVALUES	Запрашивает значения по умолчанию для указанного элемента свойства. Возвращает структуру типа KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Запрашивает все свойства с зависимостями от текущего параметра этого свойства. Указывает, что должен быть возвращен список отношений свойств, или объем буферного пространства, необходимого для такого списка, если возвращаемый буфер имеет размер ULONG. Каждый элемент находится на FILE_QUAD_ALIGNMENT, перед которым стоит KSMULTIPLE_ITEM структура. Это недопустимо при запросе поддержки набора свойств в целом. Все наборы свойств должны поддерживать этот флаг.
KSPROPERTY_TYPE_SERIALIZESET	Сериализируйте набор свойств, используя стандартные структуры KSPROPERTY_SERIALHDR и KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_UNSERIALIZESET	Отмените инициализацию набора свойств, используя стандартные структуры KSPROPERTY_SERIALHDR и KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Возвращает значение ULONG, указывающее размер данных свойства при сериализации в рамках запроса KSPROPERTY_TYPE_SERIALIZESET . Нулевой размер указывает, что сериализация свойства не требуется.
KSPROPERTY_TYPE_SERIALIZERAW	Указывает, что свойства в этом наборе должны быть сериализованы обработчиком поддержки набора свойств, если таковой существует. В противном случае вызов завершается ошибкой. Формат сериализации является частным. Эта операция должна быть обратной KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	Переданное свойство имеет тип KSP_NODE, где NodeId обозначает числовой идентификатор узла топологии. Не устанавливайте этот флаг самостоятельно; вместо этого или с другими флагами в этой таблице.
KSPROPERTY_TYPE_UNSERIALIZERAW	Указывает, что предоставленный буфер содержит группу свойств, принадлежащих этому набору, которые должны быть несериализированы обработчиком поддержки набора свойств, если таковой существует. В противном случае вызов завершается ошибкой. Формат сериализации является частным. Эта операция должна быть обратной KSPROPERTY_TYPE_SERIALIZERAW.

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

Для запроса KSPROPERTY_TYPE_RELATIONS возвращаемые данные также зависят от размера выходного буфера. Если размер выходного буфера равен нулю, размер, необходимый для возврата связанных свойств, возвращается в BytesReturned с состоянием предупреждения STATUS_BUFFER_OVERFLOW. Если буфер равен размеру KSMULTIPLE_ITEM структуры, возвращаются как размер байтов, так и количество связей. В противном случае буфер должен быть достаточно длинным, чтобы вернуть структуру KSMULTIPLE_ITEM и все связанные идентификаторы свойств, которые возвращаются в виде списка структур KSIDENTIFIER .

запросы KSPROPERTY_TYPE_SERIALIZESET и KSPROPERTY_TYPE_UNSERIALIZESET позволяют взаимодействовать с несколькими свойствами при одном вызове клиента. Если обработчик потоковой передачи ядра используется для обработки запросов свойств, они разбиваются на несколько вызовов функцией KsPropertyHandler . При использовании этого обработчика определение набора свойств определяет, какие свойства следует сериализовать.

Для запросов сериализации элемент SerializedSize соответствующей структуры KSPROPERTY_ITEM проверяется на наличие ненулевого значения, указывающего размер свойства в байтах. Если значение элемента SerializedSize равно 1, он неизвестен и должен запрашиваться (все неизвестные свойства начинаются с KSMULTIPLE_ITEM структуры, которую можно запрашивать отдельно). Чтобы запросить общий размер сериализации, клиент передает буфер нулевой длины в вызове DeviceIoControl. Затем BytesReturned возвращает размер (в байтах), который должен быть буфером для сериализации набора, и состояние предупреждения STATUS_BUFFER_OVERFLOW. Затем выделенный буфер этого размера можно заполнить сериализованными данными.

Формат буфера сериализации — это KSPROPERTY_SERIALHDR, за которым следуют сериализованные свойства. Каждое следующее свойство содержит заголовок (KSPROPERTY_SERIAL), за которым следуют данные свойства с началом каждого свойства на FILE_LONG_ALIGNMENT. Обратите внимание, что структура последовательного заголовка определена для FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW и KSPROPERTY_TYPE_UNSERIALIZERAW поддерживаются, если существует обработчик элемента свойства. Функция KsPropertyHandler вызывает обработчик, предоставляемый мини-накопителем. Размер буфера, необходимый для сериализации, также можно запросить путем передачи буфера нулевой длины в необработанный запрос сериализации. Так как обработчики присоединяются к элементам свойств, а не к набору свойств, определенный элемент в наборе свойств должен быть указан в параметре Property . Этот обработчик может работать с несколькими свойствами в наборе.

Корпорация Майкрософт предоставляет несколько идентификаторов GUID набора свойств, определяемых системой. Мини-накопители указывают один из этих идентификаторов GUID в элементе Set . Наборы свойств потоковой передачи ядра обычно начинаются с префикса KSPROPSETID или PROPSETID . Наборы свойств потоковой передачи ядра определяются в файлах ks.h, ksmedia.h, bdamedia.h и, возможно, других файлах заголовков.

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