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
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 asociado 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. Se trata unicamente de 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 tan diferente de las tuplas clave/valor/metadatos que son la esencia de un objeto en el modelo de datos. Sin embargo, desde este punto de vista se simplifica. Un almacén de metadatos se representa mediante la interfaz IKeyStore. Aunque también es una colección de tuplas clave/valor/metadatos, existen limitaciones sobre lo que se puede hacer con un almacén de claves de metadatos en comparación con un objeto 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. No se pueden crear a petición por un sistema de lenguaje dinámico.
- Solo por convención, los valores de un almacén de claves definido por metadatos están restringidos a valores básicos (descriptores de acceso intrínsecos y 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é base se debe mostrar un valor ordinal |
| PreferredFormat | Entero: tal 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 | Booleano | Indica si el host de depuración debe realizar análisis de tipo derivado en el valor antes de usarlo (por ejemplo: mostrar) |
| Ayuda | Cadena | Texto de ayuda en forma de información sobre herramientas para la clave que la interfaz de usuario pueda presentar de una manera útil y adecuada. |
| ActionName | Cadena | 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 | Booleano | Solo es válido si se especifica la clave ActionName, lo que indica que esta es la acción predeterminada para el objeto. |
| ActionDescription | Cadena | Solo es válido si se especifica la clave ActionName, lo que proporciona una descripción en forma de información sobre herramientas para la acción. La interfaz de usuario puede presentar dicho texto de una manera útil y adecuada. |
Tenga en cuenta que, si bien las claves del almacén de metadatos pueden tener sus propios metadatos (hasta el infinito), actualmente no tienen uso alguno. La mayoría de los autores de llamadas especificarán null para cualquier parámetro de metadatos en los métodos de la interfaz IKeyStore.
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 incluido 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 con él dentro del almacén de claves.
El método GetKeyValue es el primer método al que recurrirá un cliente 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 su 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 incluido en un IModelObject), el método GetValue del descriptor de acceso de propiedad será llamado automáticamente por GetKeyValue y se devolverá el valor subyacente de la propiedad.
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 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 debería ser poco frecuente.
El método ClearKeys es análogo al método ClearKeys en IModelObject. Este método quitará todas las claves del almacén de metadatos especificado. No tiene ningún efecto en ningún almacén primario.
Enumeración de objetos en el modelo de datos
Enumeración de objetos en el modelo de datos
Hay dos interfaces de enumeración de claves principales 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 procesar los incluidos en IModelObjects.
Valores: las interfaces IKeyEnumerator e IRawEnumerator se pueden adquirir mediante llamadas a EnumerateKeyValues o EnumerateRawValues para enumerar las claves y los valores sin procesar de un objeto y sus valores y 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 mediante 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 posteriormente para obtener o establecer la clave subyacente o el valor sin procesar.
KeyEnumerator: enumeración de claves sintéticas
La interfaz IKeyEnumerator es la única interfaz 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 única interfaz para la enumeración de todas las construcciones nativas o de lenguaje (por clave, 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 nativa o de lenguaje enumerada.
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.
Vea 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 sobre el modelo de datos del depurador de C++
Interfaces del modelo de datos del depurador de C++
Objetos C++ del modelo de datos del depurador
Interfaces adicionales del modelo de datos del depurador de C++