Estructura KSIDENTIFIER (ks.h)

La estructura KSIDENTIFIER especifica un GUID que identifica de forma única un conjunto relacionado de GUID y un valor de índice para hacer referencia a un miembro específico dentro de ese conjunto.

Las definiciones de tipo KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM y KSPROPERTY son alias para la estructura KSIDENTIFIER . Por lo tanto, sus definiciones son idénticas. Consulte los temas de definición de tipos individuales para obtener información específica sobre el uso.

Sintaxis

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

Miembros

_IDENTIFIER

Vea los comentarios más abajo.

_IDENTIFIER.Set

Vea los comentarios más abajo.

_IDENTIFIER.Id

Vea los comentarios más abajo.

_IDENTIFIER.Flags

Vea los comentarios más abajo.

Set

Vea los comentarios más abajo.

Id

Vea los comentarios más abajo.

Flags

Vea los comentarios más abajo.

Alignment

Vea los comentarios más abajo.

Comentarios

Descripciones de miembros KSIDENTIFIER

Set

Especifica un GUID que identifica una propiedad de streaming del kernel, un evento, un método, un conjunto de buses de comunicación. La estructura KSPIN_INTERFACE describe una interfaz específica dentro de un conjunto de interfaces. La estructura KSDEGRADE contiene detalles de las estrategias de degradación. Para obtener más información, vea la sección Comentarios a continuación.

Id

Especifica el miembro de la propiedad, evento, conjunto de métodos. Para KSPIN_MEDIUM, identifica una conexión única en el bus. Para KSPIN_INTERFACE, especifica el número de identificador de esta interfaz determinada dentro del conjunto de interfaces. Para KSDEGRADE, especifica el identificador específico del conjunto para un elemento dentro del conjunto.

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.

Consulte los temas de definición de tipos KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM y KSPROPERTY para obtener información específica sobre el uso.

Especifica el tipo de solicitud KSPROPERTY .

Valor de marca KSPROPERTY	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 de 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 con 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.

Especifica el tipo de solicitud KSEVENT . Esta marca debe ser uno de los valores enumerados en la tabla siguiente.

Valor de marca KSEVENT	Descripción
KSEVENT_TYPE_ENABLE	Habilita la notificación de eventos para este tipo de evento. El controlador continúa la notificación de eventos hasta que el cliente la deshabilita explícitamente.
KSEVENT_TYPE_ONESHOT	Habilita la notificación de eventos solo para la siguiente aparición de este evento. El cliente no necesita (y no debe) deshabilitar el evento una vez que se ha producido.
KSEVENT_TYPE_SETSUPPORT	Consulta la lista de conjuntos de eventos o para admitir un conjunto de eventos determinado.
KSEVENT_TYPE_BASICSUPPORT	Consultas para admitir un tipo de evento determinado.
KSEVENT_TYPE_ENABLEBUFFERED	En lugar de notificar al cliente, el controlador pone en cola las notificaciones de eventos. A continuación, el cliente emite una segunda solicitud de IOCTL_KS_ENABLE_EVENT con el KSEVENT_TYPE_QUERYBUFFER para recibir las notificaciones de eventos en cola.
KSEVENT_TYPE_TOPOLOGY	Indica que el evento pasado es de tipo KSE_NODE, donde NodeId indica el identificador numérico del nodo de topología. No establezca esta marca por sí sola; en su lugar, O con otras marcas de esta lista.
KSEVENT_TYPE_QUERYBUFFER	Recupera la siguiente notificación de eventos almacenados en búfer.

Especifica el tipo de solicitud KSMETHOD . Consulte también las marcas de KSMETHOD_TYPE_Xxx para KSMETHOD_ITEM. Una solicitud puede contener una combinación de los valores enumerados en la tabla siguiente.

Valor de marca KSMETHOD	Descripción
KSMETHOD_TYPE_BASICSUPPORT	Indica que se va a consultar el minidriver para determinar si admite el método especificado del conjunto de métodos.
KSMETHOD_TYPE_SEND	Indica que el minidriver debe ejecutar el método especificado. El efecto del método en los parámetros especificados debe conocerse al cliente, es decir, si los parámetros se leen, escriben en, ambos o ninguno. El minidriver usa la estructura KSMETHOD_ITEM para especificar el efecto del método en los parámetros.
KSMETHOD_TYPE_SETSUPPORT	Indica que se va a consultar el minidriver para determinar si admite el conjunto de métodos especificado.
KSMETHOD_TYPE_TOPOLOGY	Indica que el método especificado es de tipo KSM_NODE, donde el miembro NodeId es el identificador del nodo de topología. No establezca esta marca por sí sola; en su lugar, O bien con otras marcas de esta lista.

Para KSDEGRADE, especifica el porcentaje actual de degradación, expresado en partes por mil (donde un valor de 1000 no representa ninguna degradación) o especifica la cantidad de tiempo en unidades nativas según lo especificado por la interfaz.

Alignment

No se usa. Miembro de una unión sin nombre utilizada para forzar la alineación adecuada en la estructura sin nombre.

Notas

Consulte los temas de definición de tipos KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUM y KSPROPERTY para obtener información específica sobre el uso.

El uso de un identificador dentro del conjunto permite que uno realice una sola comparación grande para un identificador de conjunto y, a continuación, comparaciones rápidas más pequeñas (por ejemplo, mediante una instrucción switch para identificadores dentro de un conjunto). Por ejemplo, un identificador GUID único hace referencia a un conjunto de propiedades y el identificador corto hace referencia a las propiedades de ese conjunto.

Los conjuntosde métodos, eventos, interfaz y medios se pueden considerar como "clases" de conjuntos.

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 de 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 desde el cliente. Si el controlador de streaming del 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.

Para las solicitudes de serialización, se comprueba el miembro SerializedSize de la estructura KSPROPERTY_ITEM pertinente para 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. Un búfer asignado a ese tamaño se puede rellenar 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. 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 . Normalmente, los conjuntos de propiedades de streaming de kernel comienzan con un KSPROPSETID o un prefijo 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 las propiedades de streaming de kernel, vea Propiedades, eventos y métodos de KS.

Microsoft proporciona varios GUID de conjunto de eventos definidos por el sistema. Los minidrivers especifican uno de estos GUID en el miembro Set . Los conjuntos de eventos de streaming de kernel suelen comenzar con un prefijo KSEVENTSETID . Los conjuntos de eventos 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.

Microsoft proporciona varios GUID de conjunto de métodos definidos por el sistema. Los minidrivers especifican uno de estos GUID en el miembro Set . Los conjuntos de métodos de streaming de kernel suelen comenzar con un prefijo KSMETHODSETID . Los conjuntos de métodos 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 métodos de streaming de kernel, vea Propiedades de KS, Eventos y Métodos.

Un cliente puede usar la solicitud de IOCTL_KS_METHOD junto con la estructura KSMETHOD para ejecutar métodos en un objeto de streaming de kernel que controla el minidriver. Para obtener más información, vea Métodos KS.

La estructura de KSPIN_MEDIUM identifica un medio, con un GUID medio único e identificador de instancia, que se genera de forma específica del bus. Hay un valor de identificador reservado KSMEDIUM_TYPE_ANYINSTANCE que se usa cuando las instancias de bus no son preocupantes. Por ejemplo, el KSMEDIUMSETID_Standard hace referencia al bus del sistema, del cual solo debe haber uno. Por lo tanto, este identificador de instancia siempre se usa como comodidad.

Un pin puede admitir varios medios e interfaces en esos medios. La forma en que se describe un pin implica que la lista de interfaces se admite en todos los medios enumerados para un pin. Si hay un caso en el que esto no es true, se puede usar otro pin para describir cada subconjunto de interfaces para los medios específicos.

El medio también se almacena en caché mediante el streaming del kernel para acelerar la búsqueda de una posible conexión.

Se puede encontrar un ejemplo de uso de esta estructura en un ejemplo de tuerca, en el que KSPIN_MEDIUM representa conexiones únicas entre los tuners, las barras cruzadas y otros componentes de tuerca.

El miembro Flags puede contener valores diferentes en función del tipo de degradación de señal que emplea el cliente. Consulte Gestión de la calidad. para obtener más información sobre diferentes estrategias para resolver problemas de gestión de la calidad mediante la reducción de la calidad de las señales.

Dado que Flags contiene un valor de ULONG, es posible que se necesiten varias solicitudes Skip para solucionar el problema de administración de calidad.

Requisitos

Requisito	Valor
Header	ks.h (incluya Ks.h)

Consulte también

KSDEGRADE

KSEVENT

KSMETHOD

KSPIN_INTERFACE

KSPIN_MEDIUM

KSPROPERTY