Метод IMoniker::ComposeWith (objidl.h)

  • Статья

Создает новый составной моникер путем объединения текущего моникера с указанным моникером.

Синтаксис

HRESULT ComposeWith(
  [in]  IMoniker *pmkRight,
  [in]  BOOL     fOnlyIfNotGeneric,
  [out] IMoniker **ppmkComposite
);

Параметры

[in] pmkRight

Указатель на интерфейс IMoniker в моникере для создания на конце этого моникера.

[in] fOnlyIfNotGeneric

Если задано значение TRUE, вызывающей стороне требуется негенерическая композиция, поэтому операция должна выполняться только в том случае, если pmkRight является классом моникера, с которым этот моникер может компоновать каким-то образом, кроме формирования универсального составного элемента. При значении FALSE метод при необходимости может создать универсальный составной элемент. Большинство вызывающих абонентов должны установить для этого параметра значение FALSE.

[out] ppmkComposite

Указатель на переменную указателя IMoniker , которая получает указатель составного моникера. При успешном выполнении реализация должна вызвать AddRef для результирующего моникера; вызов Release лежит на вызывающем объекте. Если возникает ошибка или если моникеры не составляют ничего (например, при создании антимоникера с помощью моникера элемента или файлового моникера), параметру *ppmkComposite должно быть присвоено значение NULL.

Возвращаемое значение

Этот метод может возвращать стандартные возвращаемые значения E_OUTOFMEMORY и E_UNEXPECTED, а также следующие значения.

Код возврата Описание
S_OK
 Моникеры были успешно объединены.
MK_E_NEEDGENERIC
 Указывает, что fOnlyIfNotGeneric имеет значение TRUE, но моникеры не могут быть сложены вместе без создания универсального составного моникера.

Комментарии

Объединение двух моникеров вместе называется композицией. Иногда два моникера одного класса могут быть объединены в так называемую необщиническую композицию. Например, моникер файла, представляющий неполный путь, и другой моникер файла, представляющий относительный путь, можно объединить для формирования одного моникера файла, представляющего полный путь. Негенерическую композицию для данного класса моникера можно обрабатывать только в реализации ComposeWith для этого класса моникера.

Объединение двух моникеров любого класса называется универсальной композицией, которую можно выполнить с помощью вызова функции CreateGenericComposite .

Композиция моникеров является ассоциативной операцией. То есть, если A, B и C являются моникерами, то, где Comp() представляет операцию композиции, Comp( Comp( A, B ), C )

всегда равен Comp( A, Comp( B, C ) ).

Примечания к вызывающим абонентам

Чтобы объединить два моникера, следует вызвать ComposeWith , а не функцию CreateGenericComposite , чтобы дать первому моникеру возможность выполнить необщиническую композицию.

Объект, предоставляющий моникеры элемента для идентификации своих объектов, будет вызывать ComposeWith , чтобы предоставить моникер, который полностью идентифицирует расположение объекта. Это относится, например, к серверу, поддерживающму связывание с частями документа, или к контейнеру, поддерживающем связывание с внедренными объектами в документах. В такой ситуации необходимо сделать следующее:

  1. Создайте моникер элемента, который идентифицирует объект .
  2. Получите моникер, идентифицирующий контейнер объекта.
  3. Вызовите ComposeWith в моникере, идентифицируя контейнер, передавая моникер элемента в качестве параметра pmkRight .

Примечания для разработчиков

Для создания текущего моникера с помощью моникера, на который указывает pmkRight, можно использовать негенерную или универсальную композицию. Если класс моникера, на который указывает pmkRight , совпадает с классом текущего моникера, можно использовать содержимое pmkRight для выполнения более интеллектуальной необщивой композиции.

При написании нового класса моникеров вы должны решить, есть ли какие-либо моникеры, будь то ваш собственный или другой класс, к которому вы хотите дать особое отношение. Если это так, реализуйте ComposeWith, чтобы проверка, является ли pmkRight моникером типа, который должен иметь эту обработку. Для этого можно вызвать метод IPersist::GetClassID моникера или, если вы определили объект моникера, поддерживающий пользовательский интерфейс, можно вызвать QueryInterface для моникера для этого интерфейса. Примером специальной обработки может быть негенерическая композиция абсолютного моникера файла с относительным моникером файла. Наиболее распространенным случаем специального моникера является обратный для класса моникера (независимо от того, что вы возвращаете из реализации IMoniker::Inverse).

Если pmkRight полностью отрицает получатель, чтобы результирующий составной элемент был пустым, необходимо передать обратно NULL в ppmkComposite и вернуть код состояния S_OK.

Если параметр pmkRight не относится к классу, которому вы предоставляете специальную обработку, изучите fOnlyIfNotGeneric , чтобы определить, что делать дальше. Если fOnlyIfNotGeneric имеет значение TRUE, передайте обратно NULL через ppmkComposite и верните код состояния MK_E_NEEDGENERIC. Если параметр fOnlyIfNotGeneric имеет значение FALSE, вызовите функцию CreateGenericComposite , чтобы выполнить общую композицию.

Примечания по реализации

Реализация Примечания
Антимоникер Если fOnlyIfNotGeneric имеет значение TRUE, этот метод присваивает ppmkComposite значение null и возвращает MK_E_NEEDGENERIC; В противном случае метод возвращает результат объединения двух моникеров в универсальный составной. Обратите внимание, что при создании файла, элемента или моникера указателя справа от моникера создается универсальный состав, а не ни к чему, как в случае, если порядок композиции был изменен.
Моникер класса Следует за контрактом и ведет себя как моникер элемента, в том, что он может возвращать E_INVALIDARG, MK_E_NEEDGENERIC и т. д.
Файловый моникер Если pmkRight является анти-моникером, возвращенный моникер имеет значение NULL. Если pmkRight является составным компонентом, левый компонент которого является анти-моникером, возвращенный моникер является составным с удаленным левым анти-моникером. Если pmkRight является моникером файла, этот метод сворачивает два моникера в один файловый моникер, если это возможно. Если это невозможно (например, если оба моникера файла представляют абсолютные пути, как в d:\work и e:\reports), возвращенный моникер имеет значение NULL , а возвращаемое значение — MK_E_SYNTAX. Если pmkRight не является ни антимоникером, ни моникером файла, метод проверяет параметр fOnlyIfNotGeneric ; если имеет значение FALSE, метод объединяет два моникера в универсальный составной; Если задано значение TRUE, метод присваивает *ppmkCompositeзначение NULL и возвращает MK_E_NEEDGENERIC.
Универсальный составной моникер Если fOnlyIfNotGeneric имеет значение TRUE, этот метод присваивает *pmkCompositeзначение NULL и возвращает MK_E_NEEDGENERIC; В противном случае метод возвращает результат объединения двух моникеров путем вызова функции CreateGenericComposite .
Моникер элемента Если pmkRight является анти-моникером, возвращенный моникер имеет значение NULL. Если pmkRight является составным элементом, левым компонентом которого является антимоникер, то возвращенный моникер является составным после удаления крайнего левого антимоникера. Если pmkRight не является антимоникером, метод объединяет два моникера в универсальный составной, если fOnlyIfNotGeneric имеет значение FALSE; Если fOnlyIfNotGeneric имеет значение TRUE, метод возвращает моникер NULL и возвращаемое значение MK_E_NEEDGENERIC.
Моникер OBJREF Если pmkRight является анти-моникером, возвращенный моникер имеет значение NULL. Если pmkRight является составным компонентом, левый компонент которого является анти-моникером, возвращенный моникер является составным с удаленным левым анти-моникером. Если pmkRight не является ни антимоникером, ни составным моникером, левым компонентом которого является антимоникер, метод проверяет параметр fOnlyIfNotGeneric . Если имеет значение FALSE, метод объединяет два моникера в универсальный составной; Если имеет значение TRUE, метод присваивает *ppmkCompositeзначение NULL и возвращает MK_E_NEEDGENERIC.
Моникер указателя Если pmkRight является анти-моникером, возвращенный моникер имеет значение NULL. Если pmkRight является составным элементом, левым компонентом которого является антимоникер, то возвращенный моникер является составным после удаления крайнего левого антимоникера. Если fOnlyIfNotGeneric имеет значение FALSE, возвращенный моникер является универсальным составным элементом двух моникеров; В противном случае метод присваивает *ppmkCompositeзначение NULL и возвращает MK_E_NEEDGENERIC.
Моникер URL-адреса Моникеры URL-адресов поддерживают композицию двух URL-адресов: базового URL-адреса, состоящего из относительного URL-адреса. Эта композиция выполняется в соответствии с RFC по относительным URL-адресам. Если fOnlyIfNotGeneric имеет значение TRUE, метод возвращает MK_E_NEEDGENERIC. В противном случае этот метод просто возвращает CreateGenericComposite(this, pmkRight, ppmkComposite).

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header objidl.h

См. также раздел

CreateGenericComposite

IMoniker