Структура SCOPEDATAITEM (mmc.h)

Статья
08/24/2023

Структура SCOPEDATAITEM указывает элементы, которые нужно вставить в область область.

Синтаксис

typedef struct _SCOPEDATAITEM {
  DWORD      mask;
  LPOLESTR   displayname;
  int        nImage;
  int        nOpenImage;
  UINT       nState;
  int        cChildren;
  LPARAM     lParam;
  HSCOPEITEM relativeID;
  HSCOPEITEM ID;
} SCOPEDATAITEM;

Члены

mask

Значение типа , указывающее массив флагов, указывающих, какие элементы структуры содержат допустимые данные. Если эта структура используется в методе IConsoleNameSpace2::GetItem , она указывает на атрибуты элемента, которые необходимо извлечь. Этот элемент может быть одним из следующих значений.

SDI_STR (0x00002)

Допустимый элемент displayname структуры. SDI_STR поддерживается только при указании значения для элемента displayname . MMC не сохраняет значение элемента displayname и не может быть извлечено путем вызова метода IConsoleNamespace2::GetItem .

SDI_IMAGE (0x00004)

Элемент nImage структуры является допустимым или должен быть заполнен.

SDI_OPENIMAGE (0x00008)

Элемент nOpenImage структуры является допустимым или должен быть заполнен.

SDI_STATE (0x00010)

Элемент nState структуры является допустимым или должен быть заполнен.

SDI_PARAM (0x00020)

Элемент lParam структуры является допустимым или должен быть заполнен.

SDI_CHILDREN (0x00040)

Член cChildren структуры является допустимым или должен быть заполнен.

SDI_PARENT (0x00000000)

Используйте только при вставке элементов в область область. Элемент relativeID структуры является HSCOPEITEM родительского элемента. Элемент вставляется как последний дочерний элемент элемента, на который ссылается relativeID.

SDI_PREVIOUS (0x10000000)

Используйте только при вставке элементов в область область. Элемент relativeID структуры является HSCOPEITEM предыдущего одноуровневого элемента.

SDI_NEXT (0x20000000)

Используйте только при вставке элементов в область область. Элемент relativeID структуры является HSCOPEITEM следующего одноуровневого элемента.

SDI_FIRST (0x08000000)

Используйте только при вставке элементов в область область. Элемент relativeID структуры является HSCOPEITEM родительского элемента. Элемент вставляется как первый дочерний элемент элемента, на который ссылается relativeID.

displayname

MMC_CALLBACK значение или указатель на строку, завершающуюся null, которая зависит от того, как используется структура.

При вставке элемента с помощью IConsoleNameSpace2::InsertItem этому элементу необходимо задать значение MMC_CALLBACK.
При изменении имени элемента, вставленного оснасткой, с помощью IConsoleNameSpace2::SetItem этому элементу необходимо задать значение MMC_CALLBACK.
При изменении имени статического узла (элемента, вставленного консолью) этому элементу можно задать значение MMC_CALLBACK или быть указателем на строку, завершающуюся null, которая содержит текст элемента.

Имейте в виду, что оснастка может использовать MMC_TEXTCALLBACK вместо MMC_CALLBACK. Значение MMC_TEXTCALLBACK является версией MMC_CALLBACK с правильным типом (приведение не требуется).

MMC_TEXTCALLBACK появилась в MMC версии 1.2.

nImage

Индекс виртуального образа в списке образов, когда элемент находится в неизбранном состоянии. Имейте в виду, что индекс виртуального образа внутренне сопоставляется с фактическим индексом. Этот элемент также можно указать как элемент обратного вызова: MMC_CALLBACK или MMC_IMAGECALLBACK. MMC_IMAGECALLBACK является версией MMC_CALLBACK с правильным типом (приведение не требуется).

MMC_IMAGECALLBACK появилась в MMC версии 1.2.

nOpenImage

Индекс виртуального образа в списке образов, когда элемент находится в выбранном состоянии. Имейте в виду, что индекс виртуального образа внутренне сопоставляется с фактическим индексом. Элемент похож на папку в Microsoft Windows Обозреватель. Значок для открытой папки.

nState

Значение типа , указывающее маску состояния для элемента. Для IConsoleNameSpace2::GetItem этот элемент возвращает MMC_SCOPE_ITEM_STATE_EXPANDEDONCE , если элемент был развернут хотя бы один раз, или 0 (ноль), если элемент не был развернут.

Этот элемент игнорируется для IConsoleNameSpace2::InsertItem и IConsoleNameSpace2::SetItem.

cChildren

Значение типа , указывающее количество перечисляемых элементов.

Когда оснастка вставляет область элемент, она должна задать для поля cChildren значение 0 (ноль) и установить флаг SDI_CHILDREN, если выполняются оба следующих условия:

В оснастке нет дочерних элементов, которые можно добавить под вставленным элементом.
Оснастка динамически не включает оснастки расширения пространства имен для этого элемента.

В противном случае при вставке элемента область поле cChildren должно иметь значение 1 (один) или не задаваться вообще.

Если условия изменятся позже, оснастка может изменить поле cChildren с помощью IConsoleNameSpace2::SetItem.

Если определение количества дочерних элементов займет значительное время, оснастка должна использовать наилучшее предположение во время вставки и сделать фактическое определение в другом потоке, чтобы пользовательский интерфейс MMC не был заблокирован. При необходимости можно использовать IConsoleNameSpace2::SetItem для исправления параметра.

Когда MMC обнаруживает элемент область с числом cChildren 0 (ноль), он проверяет наличие расширений пространства имен, которые были статически включены для элемента пользователем или интерфейсом IRequiredExtensions. Если нет, знак "плюс" (+) удаляется из элемента.

После развертывания элемента состояние знака "плюс" определяется фактическим количеством присутствующих дочерних элементов.

lParam

Значение типа , указывающее предоставленное пользователем 32-разрядное значение, которое необходимо связать с элементом. Этот элемент, также называемый файлом cookie, представляет собой значение, которое передается в качестве первого параметра в IComponentData::QueryDataObject.

relativeID

Предоставленный консолью уникальный идентификатор элемента. Элемент вставляется в положение относительно элемента, указанного этим элементом. Параметры маски определяют относительное положение.

Чтобы определить, как интерпретируется relativeID , укажите одну из следующих констант в качестве элемента маски .

SDI_PARENT

relativeID — это HSCOPEITEM родительского объекта. Элемент вставляется как последний дочерний элемент родительского элемента. Значение SDI_PARENT указывает на отсутствие операции, так как по умолчанию идентификатор родительского элемента имеет значение relativeID.

SDI_PREVIOUS

relativeID — это HSCOPEITEM предыдущего одноуровневого элемента.

SDI_NEXT

relativeID — это HSCOPEITEM следующего одноуровневого элемента.

SDI_FIRST

То же, что и SDI_PARENT, за исключением того, что элемент вставляется в качестве первого дочернего элемента.

ID

Значение типа , указывающее предоставленный консолью уникальный идентификатор элемента область. Это значение используется для идентификации элемента в области область вызовов некоторых методов интерфейса IConsole2 и IConsoleNameSpace2.

После успешной вставки элемента в область область (с помощью IConsoleNameSpace2::InsertItem) элемент идентификатора структуры SCOPEDATAITEM содержит дескриптор HSCOPEITEM вновь вставленного элемента. Этот дескриптор является уникальным идентификатором элемента область.

Для статического узла MMC вставляет элемент в область область оснастки. Затем MMC передает HSCOPEITEM статического узла оснастке в качестве параметра param в уведомлении MMCN_EXPAND .

Имейте в виду, что оснастки должны хранить HSCOPEITEM каждого вставленного элемента и использовать его позже для управления элементом с помощью методов интерфейсов IConsole2 и IConsoleNameSpace2 .

Недопустимо вставлять элемент как одноуровневый элемент статического узла. Если оснастка задает для члена relativeID значение HSCOPEITEM статического узла, устанавливает флаги SDI_PREVIOUS или SDI_NEXT , а затем вызывает IConsoleNameSpace2::InsertItem, MMC возвращает E_INVALIDARG.

Требования


Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Верхняя часть	mmc.h