Дополнительные интерфейсы модели данных отладчика C++
В этом разделе описываются некоторые дополнительные интерфейсы, связанные с моделью данных отладчика C++, например метаданными, понятиями и перечислением объектов.
Интерфейсы метаданных модели данных отладчика
Одним из основных понятий в модели данных является то, что объект (особенно искусственный) является словарем кортежей ключей, значений или метаданных. Каждый ключ может иметь целое хранилище метаданных, связанных с ним, которое описывает различные вещи, окружающие ключ и его потенциальное значение. Обратите внимание, что метаданные не изменяют значение ключа. Это только вспомогательные сведения, связанные с ключом и его значением, которые могут повлиять на презентацию или другие связанные атрибуты ключа и его значения.
В некоторых смыслах хранилище метаданных не все, что отличается от кортежей ключей, значений или метаданных, которые являются сущностью объекта в модели данных. Однако это упрощено в этом представлении. Хранилище метаданных представлено интерфейсом IKeyStore. В то время как также коллекция кортежей ключей, значений и метаданных, существуют ограничения на то, что можно сделать с хранилищем ключей метаданных и объектом модели:
- Хранилище ключей может иметь только одно родительское хранилище . Оно не может иметь произвольную цепочку родительских моделей.
- Хранилище ключей не имеет концепций. Он может иметь только словарь кортежей ключей, значений и метаданных. Это означает, что ключи, присутствующих в хранилище ключей, являются статическими. Они не могут создаваться по запросу динамической языковой системой.
- Только по соглашению значения в определенном хранилище ключей метаданных ограничены основными значениями (встроенными и средствами доступа к свойствам)
Хотя хранилище ключей может иметь произвольное число (и произвольное именование) ключей, существуют определенные имена, имеющие определенные семантические значения. В настоящее время эти имена:
| Имя ключа | Тип значения | Description |
|---|---|---|
| PreferredRadix | Целое число: 2, 8, 10 или 16 | Указывает, в каком радиксе должно отображаться порядковое значение. |
| PreferredFormat | Целое число: как определено перечислением PreferredFormat | Указывает предпочтительный тип форматирования для отображения значения. |
| PreferredLength | Целое | Для массивов и других контейнеров указывает, сколько элементов должно отображаться по умолчанию. |
| FindDerivation | Логический | Указывает, должен ли узел отладки выполнять анализ производного типа для значения перед использованием (например, отображение) |
| Справка | Строка | Текст справки по стилю подсказки инструментов для ключа, который может быть представлен пользовательским интерфейсом соответствующим образом. |
| ActionName | Строка | Указывает, что заданный метод (который не принимает аргументы и возвращает значения) является действием. Имя действия указывается в метаданных. Пользовательский интерфейс может использовать это имя для представления параметра в контекстном меню или другом соответствующем интерфейсе. |
| ActionIsDefault | Логический | Допустимо только в том случае, если указан ключ ActionName, указывает, что это действие по умолчанию для объекта. |
| ActionDescription | Строка | Допустимо только в том случае, если указан ключ ActionName, это дает описание стиля подсказки для действия. Такой текст может быть представлен пользовательским интерфейсом соответствующим образом. |
Обратите внимание, что в то время как ключи в хранилище метаданных могут иметь собственные метаданные (ad infiniteum), в настоящее время для этого не используется. Большинство вызывающих объектов указывают значение NULL для всех параметров метаданных в методах интерфейса IKeyStore.
Интерфейс основных метаданных: IKeyStore
Интерфейс IKeyStore определяется следующим образом:
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;
}
Метод GetKey аналогичен методу GetKey в IModelObject. Он вернет значение указанного ключа, если оно существует в хранилище ключей или родительском хранилище ключей. Обратите внимание, что если значение ключа является методом доступа к свойствам, метод GetValue не будет вызываться в методе доступа к свойствам. Фактический объект IModelPropertyAccessor, размещенный в IModelObject, будет возвращен. Обычно клиент вызывает GetKeyValue по этой причине.
Метод SetKey аналогичен методу SetKey в IModelObject. Это единственный метод, который способен создавать ключ и связывать метаданные с ним в хранилище ключей.
Метод GetKeyValue — это первый метод, к который клиент перейдет, чтобы найти значение определенного ключа в хранилище метаданных. Если ключ, указанный аргументом ключа, существует в хранилище (или родительском хранилище), значение этого ключа и все метаданные, связанные с ним, будут возвращены. Если значение ключа является методом доступа к свойствам (iModelPropertyAccessor, вложенном в IModelObject), метод GetValue метода доступа к свойствам будет автоматически вызываться GetKeyValue и базовое значение возвращаемого свойства.
Метод SetKeyValue аналогичен методу SetKeyValue в IModelObject. Этот метод не может создавать новый ключ в хранилище метаданных. Если имеется существующий ключ, указанный аргументом ключа, его значение будет задано как указано. Если ключ является методом доступа к свойствам, метод SetValue будет вызываться для метода доступа к свойствам, чтобы задать базовое значение. Обратите внимание, что метаданные обычно являются статическими после создания. Использование этого метода в хранилище ключей метаданных должно быть редко.
Метод ClearKeys аналогичен методу ClearKeys в IModelObject. Он удаляет каждый ключ из данного хранилища метаданных. Этот метод не влияет на родительское хранилище.
Перечисление объектов в модели данных
Перечисление объектов в модели данных
В модели данных есть два основных интерфейса перечисления ключей: IKeyEnumerator и IRawEnumerator. Хотя это два основных интерфейса, их можно использовать для перечисления объектов в одном из трех стилей:
Ключи — интерфейс IKeyEnumerator можно получить через вызов ПеречислитьKeys, чтобы перечислить ключи объекта и их значения и метаданные без разрешения каких-либо базовых методов доступа к свойствам. Этот стиль перечисления может возвращать необработанные значения IModelPropertyAccessor, указанные в IModelObjects.
Значения — интерфейсы IKeyEnumerator и IRawEnumerator можно получить с помощью вызовов в ПеречислениеKeyValues или EnumerateRawValues для перечисления ключей или необработанных значений объекта и их значений или метаданных. Все методы доступа к свойствам, присутствующих в перечислении, автоматически разрешаются с помощью вызова базового метода GetValue во время такого перечисления.
Ссылки — интерфейсы IKeyEnumerator и IRawEnumerator можно получить с помощью вызовов в ПеречислениеKeyReferences или EnumerateRawReferences, чтобы перечислить ссылки на ключи или необработанные значения объекта. Такие ссылки можно сохранить и позже использовать для получения или задания базового ключа или необработанного значения.
KeyEnumerator: перечисление синтетических ключей
Интерфейс IKeyEnumerator — это единый интерфейс для перечисления всех ключей (по ключу, значению или ссылке) в объекте экземпляра и всех связанных родительских моделей в своей родительской цепочке моделей. Интерфейс определяется следующим образом:
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;
}
Метод Reset сбрасывает перечислитель в положение, в который он был получен при первом получении (например, до первого элемента перечисления). Последующий вызов GetNext вернет первый перечислимый ключ.
Метод GetNext перемещает перечислитель вперед и возвращает ключ в этой позиции в перечислении.
IRawEnumerator: перечисление собственных или базовых конструкций языка (C/C++)
Интерфейс IRawEnumerator — это единый интерфейс для перечисления всех конструкций собственного языка (по значению или ссылке) в объекте, представляющего собственную конструкцию в адресном пространстве целевого объекта отладки. Интерфейс определяется следующим образом:
DECLARE_INTERFACE_(IRawEnumerator, IUnknown)
{
STDMETHOD(Reset)() PURE;
STDMETHOD(GetNext)(_Out_opt_ BSTR* name, _Out_opt_ SymbolKind *kind, _COM_Errorptr_opt_ IModelObject** value) PURE;
}
Метод Reset сбрасывает перечислитель в положение, в который он был получен при первом получении (например, до первого элемента перечисления). Последующий вызов GetNext вернет первую перечисленную конструкцию машинного или языкового языка.
Метод GetNext перемещает перечислитель вперед и возвращает конструкцию собственного языка в этой позиции в перечислении.
См. также
Этот раздел является частью серии, в которой описываются интерфейсы, доступные на C++, как использовать их для создания расширения отладчика на основе C++ и использования других конструкций модели данных (например, JavaScript или NatVis) из расширения модели данных C++.
Обзор модели данных отладчика C++
Интерфейсы C++ модели данных отладчика
Объекты C++ модели данных отладчика
Дополнительные интерфейсы модели данных отладчика C++