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

Статья
02/26/2024

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

KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMи KSPROPERTY typedefs — это псевдонимы для структуры 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

См. приведенные ниже замечания.

Замечания

Описания членов KSIDENTIFIER

Set

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

Id

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

Flags

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

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

Указывает тип запроса 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	Указывает на запрос мини-driver, чтобы определить, поддерживает ли он указанный метод набора методов.
KSMETHOD_TYPE_SEND	Указывает, что мини-driver должен выполнить указанный метод. Эффект метода для заданных параметров должен быть известен клиенту, то есть, считываются ли параметры из, записываются в оба или ни в другое. Мини-driver использует структуру KSMETHOD_ITEM для указания влияния метода на параметры.
KSMETHOD_TYPE_SETSUPPORT	Указывает на запрос мини-driver, чтобы определить, поддерживает ли он указанный набор методов.
KSMETHOD_TYPE_TOPOLOGY	Указывает, что указанный метод имеет тип KSM_NODE, где элемент NodeId является идентификатором узла топологии. Не устанавливайте этот флаг самостоятельно; вместо этого или с другими флагами из этого списка.

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

Alignment

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

Примечания

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

Использование идентификатора в наборе позволяет выполнить одно большое сравнение для идентификатора набора, а затем меньшее быстрое сравнение (например, с помощью инструкции 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 вызывает обработчик, предоставляемый мини-driver. Размер буфера, необходимый для сериализации, также может запрашиваться путем передачи буфера нулевой длины в сериализуемый необработанный запрос. Так как обработчики присоединены к элементам свойств, а не набору свойств, необходимо указать определенный элемент в наборе свойств в параметре Property. Этот обработчик может иметь дело с несколькими свойствами в наборе.

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

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

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

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

Корпорация Майкрософт предоставляет несколько системных идентификаторов GUID методов. Мини-drivers указывают один из этих графических идентификаторов в элементе 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 представляет уникальные соединения между тюнерами, перекрестными панельми и другими компонентами средства настройки.

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

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

Требования

Требование	Ценность
заголовка	ks.h (include Ks.h)

См. также

KSPIN_INTERFACE

KSPIN_MEDIUM