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

Статья
08/25/2023

Извлекает отображаемое имя для моникера.

Синтаксис

HRESULT GetDisplayName(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [out] LPOLESTR *ppszDisplayName
);

Параметры

[in] pbc

Указатель на интерфейс IBindCtx в контексте привязки, который будет использоваться в этой операции. Контекст привязки кэширует объекты, привязанные к процессу привязки, содержит параметры, которые применяются ко всем операциям, использующим контекст привязки, и предоставляет средства, с помощью которых реализация моникера должна извлекать сведения о своей среде.

[in] pmkToLeft

Если моникер является частью составного моникера, указатель на моникер слева от этого моникера. Этот параметр используется в основном средствами реализации моникеров для обеспечения взаимодействия между различными компонентами составного моникера. Клиенты моникера должны передавать значение NULL.

[out] ppszDisplayName

Адрес переменной указателя, которая получает указатель на строку отображаемого имени для моникера. Реализация должна использовать IMalloc::Alloc для выделения строки, возвращаемой в ppszDisplayName, а вызывающий объект отвечает за вызов IMalloc::Free , чтобы освободить ее. Как вызывающий объект, так и реализация этого метода используют распределитель задач COM, возвращаемый CoGetMalloc. При возникновении ошибки реализация должна задать для параметра *ppszDisplayName значение NULL.

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

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

Код возврата	Описание
S_OK	Метод завершился успешно.
MK_E_EXCEEDEDDEADLINE	Операция привязки не может быть завершена в течение времени, заданного структурой BIND_OPTS контекста привязки .
E_NOTIMPL	Отображаемое имя отсутствует.

GetDisplayName предоставляет строку, которая является отображаемым представлением моникера. Отображаемое имя не является полным представлением внутреннего состояния моникера; это просто форма, которую могут читать пользователи. В результате два разных моникера могут иметь одинаковое отображаемое имя (хотя и редко). Хотя при вызове функции MkParseDisplayName не гарантируется, что отображаемое имя моникера может быть проанализировано обратно в этот моникер, неудачные попытки сделать это редко.

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

Возможно, получение отображаемого имени моникера может оказаться дорогостоящей операцией. Для повышения эффективности может потребоваться кэшировать результаты первого успешного вызова GetDisplayName, а не повторяющиеся вызовы.

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

Если вы пишете класс моникера, в котором отображаемое имя не изменяется, просто кэшируйте отображаемое имя и укажите кэшированное имя по запросу. Если отображаемое имя может меняться со временем, получение текущего отображаемого имени может означать, что моникер должен получить доступ к хранилищу объекта или выполнить привязку к объекту, что может быть дорогостоящим. В этом случае реализация GetDisplayName должна возвращать MK_E_EXCEEDEDDEADLINE если имя не может быть получено к времени, указанному в структуре BIND_OPTS контекста привязки.

Моникер, который должен быть частью универсального составного моникера, должен включать любой предыдущий разделитель (например, "") в качестве части отображаемого имени. Например, отображаемое имя, возвращаемое моникером элемента, включает разделитель, указанный при его создании с помощью функции CreateItemMoniker . Отображаемое имя моникера файла не включает разделитель, так как моникеры файлов всегда должны быть крайним левым компонентом составного элемента.

Примечания, относящиеся к реализации

Реализация	Примечания
Антимникер	Для каждого антимоникера, содержащегося в этом моникере, этот метод возвращает один экземпляр "\..".
Моникер класса	Отображаемое имя моникеров класса имеет следующий вид: clsid:string-clsid-no-curly-braces [";" clsid-param=value*]:. Например, clsid:a7b90590-36fd-11cf-857d-00aa006d2ea4:.
Моникер файла	Этот метод возвращает путь, который представляет моникер.
Универсальный составной моникер	Этот метод возвращает объединение отображаемых имен, возвращаемых моникером каждого компонента составного элемента.
Моникер элемента	Этот метод возвращает объединение разделителя и имени элемента, указанного при создании моникера элемента.
Моникер OBJREF	Этот метод получает отображаемое имя для моникера OBJREF. Отображаемое имя — это 64-разрядная кодировка, которая инкапсулирует расположение компьютера, конечную точку процесса и идентификатор указателя интерфейса (IPID) выполняющегося объекта. Для обеспечения совместимости в будущем отображаемое имя ограничено символами, которые можно указать как часть URL-адреса.
Моникер указателя	Этот метод возвращает E_NOTIMPL.
Моникер URL-адреса	Моникер URL-адреса пытается вернуть полную строку URL-адреса. Если моникер был создан с частичной строкой URL-адреса (см. раздел CreateURLMonikerEx), он сначала попытается найти моникер URL-адреса в контексте привязки в разделе SZ_URLCONTEXT, а затем будет искать контекстные сведения с моникером слева от него. Если не удается вернуть полную строку URL-адреса, возвращается его частичная строка URL-адреса.

Требования


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

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

IMoniker

MkParseDisplayName

Share via