estructura KSPROPERTY_ITEM (ks.h)

Artículo
02/07/2025

Los controladores usan la estructura KSPROPERTY_ITEM para describir cómo admiten una propiedad en un conjunto de propiedades.

Sintaxis

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;

Miembros

PropertyId

Especifica el identificador de la propiedad que se describe.

GetPropertyHandler

Puntero a un minidriver suministrado KStrGetPropertyHandler. Si null, no se puede leer la propiedad . Este miembro solo lo usan los controladores que usan las interfaces de clase AVStream o Stream.

GetSupported

Se establece en TRUE si esta propiedad admite solicitudes get, FALSE si no lo hace. (El controlador de clase cumple la solicitud a través de las solicitudes de SRB_GET_DEVICE_PROPERTY o SRB_GET_STREAM_PROPERTY). Los minidrivers que se ejecutan en la clase stream solo usan este miembro.

MinProperty

Especifica la longitud mínima del búfer que contiene el identificador de propiedad. Debe ser al menos tamaño de(KSPROPERTY).

MinData

Especifica la longitud mínima del búfer para contener los datos leídos o escritos en esta propiedad.

SetPropertyHandler

Puntero a un minidriver suministrado KStrSetPropertyHandler. Si null, no se puede establecer la propiedad . Este miembro solo lo usan los controladores que usan las interfaces de clase AVStream o Stream.

SetSupported

Esta propiedad se establece en TRUE si esta propiedad admite solicitudes establecidas, FALSE si no lo hace. (El controlador de clase cumple la solicitud a través de las solicitudes de SRB_SET_DEVICE_PROPERTY o SRB_SET_STREAM_PROPERTY).

Values

Puntero a una estructura de tipo KSPROPERTY_VALUES. Especifica los valores aceptables o predeterminados de la propiedad . Estos son los mismos que los valores notificados por un controlador en respuesta a una solicitud de IOCTL_KS_PROPERTY con las marcas KSPROPERTY_TYPE_BASICSUPPORT y KSPROPERTY_TYPE_DEFAULTVALUES establecidas.

RelationsCount

Especifica el número de entradas de la matriz a las que apunta el miembro Relations.

Relations

Apunta a una matriz de KSPROPERTY estructuras que representan propiedades relacionadas con esta. Se consideran dos propiedades relacionadas si cambiar una propiedad puede afectar al valor de la otra propiedad. El miembro Flags de cada entrada no se usa.

SupportHandler

Proporcione este miembro solo si implementa su propio formato para la serialización sin procesar o la unserialización sin procesar. AVStream controla automáticamente las consultas de soporte técnico, las consultas de intervalo y las consultas de relaciones, que devuelven los valores pertinentes de otros miembros de esta estructura de KSPROPERTY_ITEM.

SerializedSize

Especifica el tamaño de la propiedad cuando se serializa en una solicitud de KSPROPERTY_TYPE_SERIALIZESET. Debe ser cero si la propiedad no se puede serializar. Consulte KSPROPERTY para obtener más información.

Observaciones

Los minidrivers de clase stream usan KSPROPERTY_ITEM para describir al cliente cómo cumplir las solicitudes de propiedad en cada propiedad de un conjunto. El control del conjunto de propiedades como un todo se especifica en la estructura KSPROPERTY_SET, que contiene punteros a matrices de estructuras de KSPROPERTY_ITEM.

El controlador de clase de secuencia controla las solicitudes de propiedad en nombre del minidriver. Cuando el controlador de clase de secuencia requiere más información del minidriver, pasa una solicitud de SRB_XXX a una de las rutinas de StrMiniReceiveXXXRequest del minidriver. El controlador de clase de secuencia controla los distintos tipos de solicitud, como se muestra en la tabla siguiente.

Valor de marcas de solicitud de propiedad	Respuesta
KSPROPERTY_TYPE_GET	Si GetSupported es TRUE, el controlador de clase de secuencia envía una solicitud de SRB_GET_DEVICE_PROPERTY o SRB_GET_STREAM_PROPERTY al minidriver adecuado rutina de StrMiniReceiveXXXRequest.
KSPROPERTY_TYPE_SET	Si SetSupported es TRUE, el controlador de clase de secuencia envía una solicitud de SRB_SET_DEVICE_PROPERTY o SRB_SET_STREAM_PROPERTY al minidriver adecuado rutina de StrMiniReceiveXXXRequest.
KSPROPERTY_TYPE_BASICSUPPORT	El controlador de clase stream usa KSPROPERTY_ITEM para obtener la información necesaria para cumplir esta solicitud. Por ejemplo, para especificar el tipo de datos y los intervalos permitidos de los datos de propiedad, cada uno usa el Valores miembro de esta estructura.
KSPROPERTY_TYPE_SETSUPPORT	El controlador de clase de secuencia completa el IRP de solicitud de propiedad como STATUS_SUCCESS solo si el controlador proporciona una entrada para la propiedad establecida dentro de su estructura de KSPROPERTY_SET.
KSPROPERTY_TYPE_DEFAULTVALUES	El controlador de clase de secuencia usa el miembro Values de esta estructura para determinar los valores predeterminados de los datos de propiedad.
KSPROPERTY_TYPE_RELATIONS	El controlador de clase de secuencia usa el miembro relaciones de para determinar qué propiedades están relacionadas con esta propiedad.

Si el cliente especifica KSPROPERTY_TYPE_DEFAULTVALUES, el controlador usa el búfer de datos para devolver una descripción de su tipo de valor, incluido posiblemente su intervalo permitido y el valor predeterminado. Esta marca es similar a KSPROPERTY_TYPE_BASICSUPPORT, salvo que los valores devueltos son los que se han marcado con KSPROPERTY_MEMBER_FLAG_DEFAULT en el miembro Flags de la estructura KSPROPERTY_MEMBERSHEADER.

Para obtener más información, vea propiedades de KS.