Interfaces adicionales del modelo de datos del depurador de C++
En este tema se describen algunas interfaces adicionales asociadas al modelo de datos de C++ del depurador, como metadatos, conceptos y enumeración de objetos.
interfaces de metadatos del modelo de datos del depurador de
Una de las nociones principales del modelo de datos es que un objeto (especialmente uno sintético) es un diccionario de tuplas clave/valor/metadatos. Cada clave puede tener un almacén completo de metadatos asociados que describa una variedad de cosas que rodean la clave y su valor potencial. Tenga en cuenta que los metadatos no cambian de ninguna manera el valor de la clave. Solo es información auxiliar asociada a la clave y su valor que puede afectar a la presentación u otros atributos asociados de la clave y su valor.
En algunos sentidos, un almacén de metadatos no es todo lo que difiere de las tuplas clave/valor/metadatos que son la esencia de un objeto en el modelo de datos. Sin embargo, se simplifica desde esta vista. Un almacén de metadatos se representa mediante la interfaz IKeyStore. Aunque también hay una colección de tuplas clave/valor/metadatos, hay limitaciones en lo que se puede hacer con un almacén de claves de metadatos frente a un objeto de modelo:
- Un almacén de claves solo puede tener un único almacén primario; no puede tener una cadena arbitraria de modelos primarios.
- Un almacén de claves no tiene conceptos. Solo puede tener el diccionario de tuplas clave/valor/metadatos. Esto significa que las claves presentes en un almacén de claves son estáticas. Un sistema de lenguaje dinámico no puede crear a petición.
- Solo por convención, los valores de un almacén de claves definido por metadatos están restringidos a valores básicos (descriptores intrínsecos y descriptores de acceso de propiedad).
Aunque un almacén de claves puede tener un número arbitrario (y un nombre arbitrario) de claves, hay determinados nombres que tienen valores semánticos definidos. Actualmente, esos nombres son:
| Nombre de clave | Tipo de valor | Descripción |
|---|---|---|
| PreferredRadix | Entero: 2, 8, 10 o 16 | Indica en qué radix se debe mostrar un valor ordinal. |
| PreferredFormat | Entero: tal y como se define en la enumeración PreferredFormat | Indica el tipo de formato preferido para mostrar el valor. |
| PreferredLength | Entero | Para matrices y otros contenedores, indica cuántos elementos se deben mostrar de forma predeterminada. |
| FindDerivation | Boolean | Indica si el host de depuración debe realizar análisis de tipos derivados en el valor antes de usar (por ejemplo: mostrar). |
| Ayuda | Cuerda | Texto de ayuda de estilo de información sobre herramientas para la clave que puede presentar la interfaz de usuario de una manera apropiadamente útil. |
| ActionName | Cuerda | Indica que el método especificado (uno que no toma ningún argumento y no devuelve ningún valor) es una acción. El nombre de la acción se especifica en los metadatos. Una interfaz de usuario puede utilizar este nombre para presentar la opción en un menú contextual u otra interfaz adecuada. |
| ActionIsDefault | Boolean | Solo es válido si se especifica la clave ActionName, indica que esta es la acción predeterminada para el objeto . |
| ActionDescription | Cuerda | Solo es válido si se especifica la clave ActionName, lo que proporciona una descripción del estilo de información sobre herramientas para la acción. Este texto puede presentarse mediante la interfaz de usuario de una manera apropiadamente útil. |
Tenga en cuenta que, aunque las claves del almacén de metadatos pueden tener sus propios metadatos (ad infiniteum), actualmente no hay ningún uso para ello. La mayoría de los autores de llamada especificarán null para los parámetros de metadatos de los métodos en la interfaz IKeyStore.
la interfaz de metadatos principales: IKeyStore
La interfaz IKeyStore se define de la siguiente manera:
DECLARE_INTERFACE_(IKeyStore, IUnknown)
{
STDMETHOD(GetKey)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKey)(_In_ PCWSTR key, _In_opt_ IModelObject* object, _In_opt_ IKeyStore* metadata) PURE;
STDMETHOD(GetKeyValue)(_In_ PCWSTR key, _COM_Errorptr_opt_ IModelObject** object, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
STDMETHOD(SetKeyValue)(_In_ PCWSTR key, _In_ IModelObject* object) PURE;
STDMETHOD(ClearKeys)() PURE;
}
El método GetKey es análogo al método GetKey en IModelObject. Devolverá el valor de la clave especificada si existe en el almacén de claves o en el almacén primario del almacén de claves. Tenga en cuenta que si el valor de la clave es un descriptor de acceso de propiedad, no se llamará al método GetValue en el descriptor de acceso de propiedad. Se devolverá el IModelPropertyAccessor real boxed en un IModelObject. Es habitual que un cliente llame a GetKeyValue por este motivo.
El método SetKey es análogo al método SetKey en IModelObject. Es el único método que es capaz de crear una clave y asociar metadatos a él dentro del almacén de claves.
El método GetKeyValue es el primer método al que un cliente irá para encontrar el valor de una clave determinada dentro del almacén de metadatos. Si la clave especificada por el argumento key existe en el almacén (o en el almacén primario), se devolverá el valor de esa clave y los metadatos asociados a ella. Si el valor de la clave es un descriptor de acceso de propiedad (un IModelPropertyAccessor boxed en un IModelObject), el método GetValue del descriptor de acceso de propiedad se llamará automáticamente mediante GetKeyValue y el valor subyacente de la propiedad devuelta.
El método SetKeyValue es análogo al método SetKeyValue en IModelObject. Este método no es capaz de crear una nueva clave en el almacén de metadatos. Si hay una clave existente tal como se indica en el argumento key, su valor se establecerá como se indica. Si la clave es un descriptor de acceso de propiedad, se llamará al método SetValue en el descriptor de acceso de propiedad para establecer el valor subyacente. Tenga en cuenta que los metadatos suelen ser estáticos una vez creados. El uso de este método en un almacén de claves de metadatos debe ser poco frecuente.
El método ClearKeys es análogo al método ClearKeys en IModelObject. Quitará todas las claves del almacén de metadatos especificado. Este método no tiene ningún efecto en ningún almacén primario.
(enumeración de objetos) en el modelo de datos
enumerar objetos en el modelo de datos
Hay dos interfaces principales de enumeración de claves en el modelo de datos: IKeyEnumerator e IRawEnumerator. Aunque estas son las dos interfaces principales, se pueden usar para enumerar objetos en uno de estos tres estilos:
Claves: la interfaz IKeyEnumerator se puede adquirir a través de una llamada a EnumerateKeys para enumerar las claves de un objeto y sus valores o metadatos sin resolver ningún descriptor de acceso de propiedad subyacente. Este estilo de enumeración puede devolver valores IModelPropertyAccessor sin formato que se muestran en IModelObjects.
Valores: las interfaces IKeyEnumerator e IRawEnumerator se pueden adquirir a través de llamadas a EnumerateKeyValues o EnumerateRawValues para enumerar los valores sin procesar y claves en un objeto y sus valores o metadatos. Los descriptores de acceso de propiedad presentes en la enumeración se resuelven automáticamente a través de una llamada al método GetValue subyacente durante dicha enumeración.
referencias: las interfaces IKeyEnumerator e IRawEnumerator se pueden adquirir a través de llamadas a EnumerateKeyReferences o EnumerateRawReferences para enumerar las referencias a las claves o valores sin procesar de un objeto. Estas referencias se pueden guardar y usar más adelante para obtener o establecer la clave subyacente o el valor sin procesar.
KeyEnumerator: enumeración de claves sintéticas
La interfaz IKeyEnumerator es la interfaz única para la enumeración de todas las claves (por clave, valor o referencia) dentro de un objeto de instancia y todos los modelos primarios asociados de su cadena de modelos primarios. La interfaz se define de la siguiente manera:
DECLARE_INTERFACE_(IKeyEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_ BSTR* key, _COM_Errorptr_opt_ IModelObject** value, _COM_Outptr_opt_result_maybenull_ IKeyStore** metadata) PURE;
}
El método Reset restablece el enumerador a la posición en la que se adquirió por primera vez (por ejemplo: antes del primer elemento de la enumeración). Una llamada posterior a GetNext devolverá la primera clave enumerada.
El método GetNext mueve el enumerador hacia delante y devuelve la clave en esa posición de la enumeración.
IRawEnumerator: enumeración de construcciones de lenguaje nativo o subyacente (C/C++)
La interfaz IRawEnumerator es la interfaz única para la enumeración de todas las construcciones nativas o de lenguaje (por valor o referencia) dentro de un objeto que representa una construcción nativa dentro del espacio de direcciones del destino de depuración. La interfaz se define de la siguiente manera:
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
El método Reset restablece el enumerador a la posición en la que se adquirió por primera vez (por ejemplo: antes del primer elemento de la enumeración). Una llamada posterior a GetNext devolverá la primera construcción de lenguaje o nativo enumerado.
El método GetNext mueve el enumerador hacia delante y devuelve la construcción nativa o de lenguaje en esa posición de la enumeración.
consulte también
Este tema forma parte de una serie que describe las interfaces accesibles desde C++, cómo usarlas para compilar una extensión de depurador basada en C++ y cómo usar otras construcciones de modelo de datos (por ejemplo: JavaScript o NatVis) desde una extensión de modelo de datos de C++.
información general del modelo de datos del depurador de C++
interfaces de C++ del modelo de datos del depurador
objetos del modelo de datos del depurador de C++
interfaces adicionales del modelo de datos del depurador de C++