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.
Lasde KSDEGRADE, KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMy KSPROPERTY typedefs son alias para la estructura de 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 a continuación.
_IDENTIFIER.Set
Vea los comentarios a continuación.
_IDENTIFIER.Id
Vea los comentarios a continuación.
_IDENTIFIER.Flags
Vea los comentarios a continuación.
Set
Vea los comentarios a continuación.
Id
Vea los comentarios a continuación.
Flags
Vea los comentarios a continuación.
Alignment
Vea los comentarios a continuación.
Observaciones
Descripciones de miembros KSIDENTIFIER
Set
Especifica un GUID que identifica una propiedad de streaming de kernel, evento, método, conjunto de bus de comunicación. La estructura KSPIN_INTERFACE describe una interfaz específica dentro de un conjunto de interfaces. La estructura de KSDEGRADE contiene detalles de las estrategias de degradación. Para obtener más información, consulte la sección comentarios de 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 clase. Marcas debe 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 losdeKSDEGRADE , KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMy KSPROPERTY temas de definición de tipos 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 del 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 requerido por dicha lista si el búfer de retorno es el tamaño de un ULONG. Cada elemento está en FILE_QUAD_ALIGNMENT, precedido por 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 | Deserializa el conjunto de propiedades utilizando 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, OR 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, OR 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 debe 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 debe 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 nodeId miembro es el identificador del nodo de topología. No establezca esta marca por sí sola; en su lugar, OR 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 losdeKSDEGRADE , KSEVENT, KSMETHOD, KSPIN_INTERFACE, KSPIN_MEDIUMy KSPROPERTY temas de definición de tipos para obtener información específica sobre el uso.
El uso de un identificador dentro del conjunto permite realizar una sola comparación grande para un identificador de conjunto y, a continuación, comparar 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 una propiedad establecida y el identificador corto hace referencia a las propiedades de ese conjunto.
Method, Event, Interfacey conjuntos medianos pueden considerarse 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 una 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 de 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 de kernel se usa para procesar solicitudes de propiedades, estos se dividen en varias llamadas por la función KsPropertyHandler. Al usar este controlador, la propiedad establece controles de definición de las propiedades que se van a serializar.
Para las solicitudes de serialización, el serializedSize miembro de la estructura de 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, de que el búfer debe 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 de 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 están asociados 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 conjuntos 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 KSPROPSETID o un prefijo PROPSETID de. Los conjuntos de propiedades de streaming de kernel se definen en ks.h, ksmedia.h, bdamedia.h, y posiblemente otros archivos de encabezado.
Para obtener más información sobre las propiedades de streaming de kernel, consulte propiedades de KS, eventos y métodos.
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 de . Los conjuntos de eventos de streaming de kernel se definen en ks.h, ksmedia.h, bdamedia.h, y posiblemente otros archivos de encabezado.
Para obtener más información sobre los eventos de streaming de kernel, consulte propiedades, eventos y métodos de KS.
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.hy, posiblemente, otros archivos de encabezado.
Para obtener más información sobre los métodos de streaming de kernel, consulte propiedades, eventos y métodos de KS.
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 KS Methods.
La estructura 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 streaming de 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 tuner, en el que KSPIN_MEDIUM representa conexiones únicas entre los tuners, las barras cruzadas y otros componentes de tuner.
El miembro Flags puede contener valores diferentes en función del tipo de degradación de señal que emplea el cliente. Consulte Quality Management. 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 la señal.
Dado que marcas contiene un valor ULONG, es posible que se necesiten varias solicitudes Skip para solucionar el problema de administración de calidad.
Requisitos
| Requisito | Valor |
|---|---|
| encabezado de | ks.h (incluya Ks.h) |