Структура KSPROPERTY
Структура 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.
Требования
Заголовок: ks.h (включая Ks.h)