Estructura KSPROPERTY

Artículo
06/15/2023

La estructura KSPROPERTY especifica una única propiedad de streaming de kernel dentro de un conjunto de propiedades.

Las estructuras KSEVENT, KSMETHOD y KSPROPERTY son alias para la estructura KSIDENTIFIER . Por lo tanto, sus definiciones son idénticas.

Sintaxis

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

Miembros

Set

Especifica un GUID que identifica un conjunto de propiedades de streaming de kernel. Para obtener más información sobre los GUID del conjunto de propiedades, vea la sección Comentarios a continuación.

Id

Especifica el miembro del conjunto de propiedades.

Flags

Especifica el tipo de solicitud. Si va a escribir un minidriver de clase de secuencia, consulte también KSPROPERTY_ITEM para obtener información de marca específica de la clase.

Las marcas deben ser uno de los valores enumerados en la tabla siguiente. Algunas de las marcas se pueden combinar mediante una operación OR bit a bit.

Valor	Descripción
KSPROPERTY_TYPE_GET	Recupera el valor del elemento de propiedad especificado.
KSPROPERTY_TYPE_SET	Establece el valor del elemento de propiedad especificado.
KSPROPERTY_TYPE_SETSUPPORT	Consulta si el controlador admite este conjunto de propiedades.
KSPROPERTY_TYPE_BASICSUPPORT	Consulta los tipos de solicitud que controla el controlador para este elemento de propiedad. Devuelve KSPROPERTY_TYPE_GET o KSPROPERTY_TYPE_SET o ambos. Todos los conjuntos de propiedades deben admitir esta marca.
KSPROPERTY_TYPE_DEFAULTVALUES	Consulta los valores predeterminados para el elemento de propiedad especificado. Devuelve una estructura de tipo KSPROPERTY_VALUES.
KSPROPERTY_TYPE_RELATIONS	Consulta todas las propiedades con dependencias en el valor actual de esta propiedad. Especifica que se va a devolver la lista de relaciones de propiedades o la cantidad de espacio de búfer que requiere dicha lista si el búfer de devolución es el tamaño de un ULONG. Cada elemento está en FILE_QUAD_ALIGNMENT, precedido de una estructura KSMULTIPLE_ITEM . Esto no es válido al consultar la compatibilidad con la propiedad establecida en general. Todos los conjuntos de propiedades deben admitir esta marca.
KSPROPERTY_TYPE_SERIALIZESET	Serialice el conjunto de propiedades mediante las estructuras estándar KSPROPERTY_SERIALHDR y KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_UNSERIALIZESET	Deserialice el conjunto de propiedades mediante las estructuras estándar KSPROPERTY_SERIALHDR y KSPROPERTY_SERIAL .
KSPROPERTY_TYPE_SERIALIZESIZE	Devuelve un ULONG que especifica el tamaño de los datos de propiedad cuando se serializa como parte de una solicitud de KSPROPERTY_TYPE_SERIALIZESET . Un tamaño de cero indica que no es necesario serializar una propiedad.
KSPROPERTY_TYPE_SERIALIZERAW	Especifica que el controlador de compatibilidad del conjunto de propiedades debe serializar las propiedades de este conjunto, si existe. Si no es así, se produce un error en la llamada. El formato de serialización es privado. Esta operación debe ser la inversa de KSPROPERTY_TYPE_UNSERIALIZERAW.
KSPROPERTY_TYPE_TOPOLOGY	La propiedad pasada es de tipo KSP_NODE, donde NodeId indica el identificador numérico del nodo de topología. No establezca esta marca por sí sola; en su lugar, O bien con otras marcas de esta tabla.
KSPROPERTY_TYPE_UNSERIALIZERAW	Especifica que el búfer proporcionado contiene un grupo de propiedades que pertenecen a este conjunto que el controlador de compatibilidad del conjunto de propiedades debe deserializar, si existe alguno. Si no es así, se produce un error en la llamada. El formato de serialización es privado. Esta operación debe ser la inversa de KSPROPERTY_TYPE_SERIALIZERAW.

Comentarios

El tamaño del búfer de salida pasado determina qué datos se devuelven de una solicitud de KSPROPERTY_TYPE_BASICSUPPORT. Si el búfer de salida es el tamaño de un ULONG, solo se devuelven las marcas de acceso. Si el búfer de salida es el tamaño de la estructura de KSPROPERTY_DESCRIPTION , la estructura se rellena con las marcas de acceso, el tamaño inclusivo de toda la información de valores, la información del tipo de valor de propiedad y el número de listas de miembros que corresponden a la estructura.

Para una solicitud de KSPROPERTY_TYPE_RELATIONS, los datos devueltos también dependen del tamaño del búfer de salida. Si el tamaño del búfer de salida es cero, el tamaño necesario para devolver las propiedades relacionadas se devuelve en BytesReturned con un estado de advertencia de STATUS_BUFFER_OVERFLOW. Si el búfer es el tamaño de una estructura de KSMULTIPLE_ITEM , se devuelve el tamaño de bytes y el recuento de relaciones. De lo contrario, se espera que el búfer sea lo suficientemente largo como para devolver la estructura KSMULTIPLE_ITEM y todos los identificadores de propiedad relacionados, que se devuelven como una lista de estructuras KSIDENTIFIER .

KSPROPERTY_TYPE_SERIALIZESET y KSPROPERTY_TYPE_UNSERIALIZESET solicitudes permiten la interacción con varias propiedades con una sola llamada del cliente. Si el controlador de streaming de kernel se usa para procesar solicitudes de propiedad, estos se dividen en varias llamadas mediante la función KsPropertyHandler . Al usar este controlador, la definición del conjunto de propiedades controla qué propiedades se van a serializar.

En el caso de las solicitudes de serialización, el miembro SerializedSize de la estructura KSPROPERTY_ITEM pertinente se comprueba si hay un valor distinto de cero que indica el tamaño, en bytes, de la propiedad . Si el valor del miembro SerializedSize es 1, se desconoce y se debe consultar (todas las propiedades desconocidas comienzan con una estructura de KSMULTIPLE_ITEM que se puede consultar por separado). Para consultar el tamaño total que tomaría una serialización, el cliente pasa un búfer de longitud cero en la llamada a DeviceIoControl. BytesReturned devuelve el tamaño, en bytes, que el búfer debe ser para serializar el conjunto y un estado de advertencia de STATUS_BUFFER_OVERFLOW. Después, se puede rellenar un búfer asignado a ese tamaño con los datos serializados.

El formato del búfer de serialización es un KSPROPERTY_SERIALHDR, seguido de propiedades serializadas. Cada propiedad que sigue contiene un encabezado (KSPROPERTY_SERIAL), seguido de los datos de propiedad, con el inicio de cada propiedad en FILE_LONG_ALIGNMENT. Tenga en cuenta que la estructura del encabezado serie está definida para estar en FILE_LONG_ALIGNMENT.

KSPROPERTY_TYPE_SERIALIZERAW y KSPROPERTY_TYPE_UNSERIALIZERAW se admiten si existe un controlador de elementos de propiedad. La función KsPropertyHandler invoca el controlador proporcionado por el minidriver. El tamaño del búfer necesario para la serialización también se puede consultar pasando un búfer de longitud cero a una solicitud sin procesar serializar. Dado que los controladores se adjuntan a elementos de propiedad en lugar del conjunto de propiedades, se debe especificar un elemento específico dentro del conjunto de propiedades en el parámetro Property . Este controlador puede tratar con varias propiedades dentro del conjunto.

Microsoft proporciona varios GUID de conjunto de propiedades definidos por el sistema. Los minidrivers especifican uno de estos GUID en el miembro Set . Los conjuntos de propiedades de streaming de kernel suelen comenzar con un prefijo KSPROPSETID o PROPSETID . Los conjuntos de propiedades de streaming de kernel se definen en ks.h, ksmedia.h, bdamedia.h y, posiblemente, en otros archivos de encabezado.

Para obtener más información sobre los eventos de streaming de kernel, vea Propiedades de KS, Eventos y Métodos.