Структура KSIDENTIFIER (ks.h)

Статья
02/26/2024

Структура KSIDENTIFIER задает GUID, который однозначно идентифицирует связанный набор идентификаторов GUID, и значение индекса для ссылки на определенный член в этом наборе.

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

Синтаксис

typedef struct {
  union {
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    } _IDENTIFIER;
    struct {
      GUID  Set;
      ULONG Id;
      ULONG Flags;
    };
    LONGLONG Alignment;
  };
} KSIDENTIFIER, *PKSIDENTIFIER;

Члены

_IDENTIFIER

См. примечания ниже.

_IDENTIFIER.Set

См. примечания ниже.

_IDENTIFIER.Id

См. примечания ниже.

_IDENTIFIER.Flags

См. примечания ниже.

Set

См. примечания ниже.

Id

См. примечания ниже.

Flags

См. примечания ниже.

Alignment

См. примечания ниже.

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

Id

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

Flags

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

Подробные сведения об использовании см. в разделах определение типа KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM и KSPROPERTY .

Указывает тип запроса KSPROPERTY .

Значение флага KSPROPERTY	Описание
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.

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

Значение флага KSEVENT	Описание
KSEVENT_TYPE_ENABLE	Включает уведомление о событиях этого типа. Драйвер продолжает уведомлять о событиях, пока клиент явно не отключит его.
KSEVENT_TYPE_ONESHOT	Включает уведомление о событиях только для следующего вхождения этого события. Клиенту не нужно (и не следует) отключать событие после его возникновения.
KSEVENT_TYPE_SETSUPPORT	Запрашивает список наборов событий или поддержку определенного набора событий.
KSEVENT_TYPE_BASICSUPPORT	Запросы на поддержку определенного типа событий.
KSEVENT_TYPE_ENABLEBUFFERED	Вместо уведомления клиента драйвер помещает в очередь уведомления о событиях. Затем клиент отправляет второй запрос IOCTL_KS_ENABLE_EVENT с KSEVENT_TYPE_QUERYBUFFER для получения уведомлений о событиях в очереди.
KSEVENT_TYPE_TOPOLOGY	Указывает, что переданное событие имеет тип KSE_NODE, где NodeId обозначает числовой идентификатор узла топологии. Не устанавливайте этот флаг самостоятельно; вместо этого или с другими флагами из этого списка.
KSEVENT_TYPE_QUERYBUFFER	Извлекает следующее уведомление о событии в буфере.

Указывает тип запроса KSMETHOD . Кроме того, см. флаги KSMETHOD_TYPE_Xxx для KSMETHOD_ITEM. Запрос может содержать сочетание значений, перечисленных в следующей таблице.

Значение флага KSMETHOD	Описание
KSMETHOD_TYPE_BASICSUPPORT	Указывает на запрос к мини-накопителю, чтобы определить, поддерживает ли он указанный метод набора методов.
KSMETHOD_TYPE_SEND	Указывает, что мини-диск должен выполнить указанный метод. Влияние метода на заданные параметры должно быть известно клиенту, т. е. о том, считываются ли параметры из , записываются в оба параметра или ни из них. Мини-диск использует структуру KSMETHOD_ITEM, чтобы указать влияние метода на параметры.
KSMETHOD_TYPE_SETSUPPORT	Указывает на запрос к мини-накопителю, чтобы определить, поддерживает ли он указанный набор методов.
KSMETHOD_TYPE_TOPOLOGY	Указывает, что указанный метод имеет тип KSM_NODE, где элемент NodeId является идентификатором узла топологии. Не устанавливайте этот флаг самостоятельно; вместо этого или с другими флагами из этого списка.

Для KSDEGRADE указывает текущий процент деградации, выраженный в частях на тысячу (где значение 1000 не означает снижение), или указывает количество времени в собственных единицах, как указано в интерфейсе.

Alignment

Не используется. Член неименованного объединения, используемого для принудительного выравнивания неименованной структуры.

Примечания

Использование идентификатора в наборе позволяет выполнить одно большое сравнение для идентификатора набора, а затем более мелкие быстрые сравнения (например, с помощью инструкции switch для идентификаторов в наборе). Например, на набор свойств ссылается уникальный идентификатор GUID, а на свойства в этом наборе — короткий идентификатор.

Наборы методов, событий, интерфейсов и средних сред можно рассматривать как "классы" наборов.

Размер переданного выходного буфера определяет, какие данные возвращаются из запроса 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.

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

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

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

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

Клиент может использовать запрос IOCTL_KS_METHOD вместе со структурой KSMETHOD для выполнения методов в объекте потоковой передачи ядра, обрабатываемом мини-driver. Дополнительные сведения см. в разделе Методы KS.

Структура KSPIN_MEDIUM идентифицирует среду с уникальным идентификатором GUID среды и экземпляра, который создается для конкретной шины. Существует зарезервированное значение идентификатора KSMEDIUM_TYPE_ANYINSTANCE, которое используется, если экземпляры шины не имеют никакого значения. Например, KSMEDIUMSETID_Standard относится к системной шине, из которой должен быть только один. Поэтому этот идентификатор экземпляра всегда используется в качестве удобства.

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

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

Пример использования этой структуры можно найти в примере тюнера, в котором KSPIN_MEDIUM представляет уникальные соединения между тюнерами, перекладиной и другими компонентами тюнера.

Элемент Flags может содержать различные значения в зависимости от типа снижения сигнала, используемого клиентом. См. раздел Управление качеством. дополнительные сведения о различных стратегиях решения проблем управления качеством путем снижения качества сигнала.

Так как flags содержит значение ULONG, для устранения проблемы с управлением качеством может потребоваться несколько запросов Skip.