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

Статья
03/15/2023

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

Синтаксис

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

Параметры

[in] pbc

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

[in] pmkToLeft

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

[in] riidResult

Идентификатор интерфейса, который клиент хочет использовать для связи с объектом, идентифицируемым моникером.

[out] ppvResult

Адрес переменной указателя, получающей указатель интерфейса, запрошенный в riid. После успешного возврата *ppvResult содержит запрошенный указатель интерфейса на объект, который идентифицирует моникер. При успешном выполнении реализация должна вызвать Метод AddRef для моникера. Вызов Release лежит на вызывающем объекте. При возникновении ошибки значение *ppvResult должно иметь значение NULL.

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

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

Код возврата	Описание
S_OK	Операция привязки выполнена успешно.
MK_E_NOOBJECT	Не удалось найти объект, идентифицированный этим моникером, или какой-либо объект, определяемый составным моникером, частью которого является этот моникер.
MK_E_EXCEEDEDDEADLINE	Операция привязки не может быть завершена в течение срока, заданного структурой BIND_OPTS контекста привязки.
MK_E_CONNECTMANUALLY	Операция привязки требует помощи от конечного пользователя. Наиболее распространенной причиной для возврата этого значения является то, что требуется пароль или требуется подключить дискету. При возвращении этого значения извлеките моникер, вызвавший ошибку, вызовом IBindCtx::GetObjectParam с ключом ConnectManually. Затем можно вызвать IMoniker::GetDisplayName , чтобы получить отображаемое имя, отобразить диалоговое окно, в котором передаются нужные сведения, например инструкции по подключению дискеты или запроса пароля, а затем повторить операцию привязки.
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	Был найден промежуточный объект, но он не поддерживал интерфейс, необходимый для выполнения операции привязки. Например, моникер элемента возвращает это значение, если его контейнер не поддерживает интерфейс IOleItemContainer .
STG_E_ACCESSDENIED	Не удается получить доступ к объекту хранилища.

Этот метод также может возвращать ошибки, связанные с методом IOleItemContainer::GetObject .

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

Эти шаги иллюстрируются в следующем фрагменте кода.

HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk->BindToObject(pbc, NULL, IID_ICellRange, &pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc->Release(); 
pCellRange->Release();

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

Com-контейнеры, поддерживающие ссылки на объекты, используют моникеры для поиска связанного объекта и получения доступа к нему, но обычно не вызывают BindToObject напрямую. Вместо этого, когда пользователь активирует ссылку в контейнере, контейнер ссылок обычно вызывает IOleObject::D oVerb, используя реализацию обработчика ссылок, которая вызывает BindToObject для моникера, хранящегося в связанном объекте (если он не может обработать глагол).

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

То, что делает ваша реализация, зависит от того, будет ли моникер иметь префикс; то есть независимо от того, будет ли параметр pmkToLeft иметь значение NULL или нет. Например, моникер элемента, который идентифицирует объект в контейнере, ожидает, что pmkToLeft идентифицирует контейнер. Поэтому моникер элемента использует pmkToLeft для запроса служб из этого контейнера. Если вы ожидаете, что моникер имеет префикс, следует использовать параметр pmkToLeft (например, вызов BindToObject ) для запроса служб из идентифицируемых им объектов.

Если вы ожидаете, что моникер не имеет префикса, реализация BindToObject должна сначала проверка таблицу выполняющихся объектов (ROT), чтобы узнать, выполняется ли объект. Чтобы получить указатель на ROT, реализация должна вызвать IBindCtx::GetRunningObjectTable в параметре pbc . Затем можно вызвать метод IRunningObjectTable::GetObject , чтобы узнать, зарегистрирован ли текущий моникер в ROT. В этом случае можно немедленно вызвать QueryInterface , чтобы получить указатель на интерфейс, запрошенный вызывающим.

Когда реализация BindToObject привязывается к определенному объекту, она должна использовать параметр pbc для вызова IBindCtx::RegisterObjectBound для хранения ссылки на привязанный объект в контексте привязки. Это гарантирует, что связанный объект будет работать до тех пор, пока контекст привязки не будет освобожден, что может избежать расходов, связанных с последующей загрузкой операции привязки позже.

Если в структуре BIND_OPTS контекста привязки указан флаг BINDFLAGS_JUSTTESTEXISTENCE, реализация имеет возможность возвращать значение NULL в ppvResult (хотя флаг также можно игнорировать и выполнить полную операцию привязки).

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

Реализация	Примечания
Антимоникер	Этот метод не реализован. Он возвращает E_NOTIMPL.
Моникер класса	Если pmkLeft имеет значение NULL, вызывает CoGetClassObject, используя идентификатор CLSID, с помощью моникера класса был инициализирован (в CreateClassMoniker или с помощью MkParseDisplayName) и CLSCTX текущего PBC (IBindCtx). Если значение pmkLeft не равно NULL, вызывает pmkLeft-BindToObject> для IClassActivator и вызывает IClassActivator::GetClassObject с идентификатором CLSID, с помощью и параметров CLSCTX и языкового стандарта текущего PBC (IBindCtx).
Файловый моникер	Если значение pmkToLeft равно NULL, метод ищет моникер в ROT и, если он найден, запрашивает полученный объект для запрошенного указателя интерфейса. Если моникер не найден в ROT, метод загружает объект из файловой системы и извлекает запрошенный указатель интерфейса. Если значение pmkLeft не равно NULL, вместо определения класса для создания и инициализации с содержимым файла, на который ссылается моникер файла с помощью GetClassFile (или других средств), вызовите pmkLeft-BindToObject> для IClassFactory и IClassActivator, получите этот указатель в pcf. Если это не удается с E_NOINTERFACE, верните MK_E_INTERMEDIATEINTERFACENOTSUPPORTED. Если указатель IClassFactory успешно получен, вызовите pcf-CreateInstance>(IID_IPersistFile, (void**) &ppf), чтобы получить новый экземпляр класса для инициализации и инициализировать его с помощью IPersistFile или других соответствующих средств в соответствии с существующими путями инициализации моникера файла.
Универсальный составной моникер	Если pmkToLeft имеет значение NULL, этот метод ищет моникер в ROT и, если он найден, запрашивает полученный объект для запрошенного указателя интерфейса. Если значение pmkToLeft не равно NULL, метод рекурсивно вызывает BindToObject в крайнем правом компоненте составной части, передавая остальную часть составной части в качестве параметра pmkToLeft для этого вызова.
Моникер элемента	Если значение pmkToLeft равно NULL, этот метод возвращает E_INVALIDARG. В противном случае метод вызывает BindToObject для параметра pmkToLeft , запрашивая указатель интерфейса IOleItemContainer . Затем метод вызывает IOleItemContainer::GetObject, передавая строку, содержащуюся в моникере, и возвращает запрошенный указатель интерфейса.
Моникер OBJREF	Параметр pmkToLeft должен иметь значение NULL. Так как моникер OBJREF представляет выполняющийся объект, активация не выполняется. Если представленный объект больше не выполняется, BindToObject завершается сбоем с E_UNEXPECTED.
Моникер указателя	Этот метод запрашивает заключенный в оболочку указатель для запрошенного интерфейса.
Моникер URL-адреса	Так как моникер URL-адреса поддерживает асинхронную привязку, фактическое возвращаемое значение bindToObject может отличаться в зависимости от параметров объекта, установленных в контексте привязки. Дополнительные сведения приведены ниже.

Семантика операции привязки для моникера URL-адреса идентична независимо от синхронного или асинхронного использования и выглядит следующим образом:

Моникер URL-адреса извлекает дополнительные сведения для операции привязки из контекста привязки. Например, моникер может получить указатели на интерфейсы IBindStatusCallback и IEnumFORMATETC , зарегистрированные в контексте привязки. Дополнительные сведения могут включать дополнительные параметры привязки, указанные в контексте привязки через IBindCtx::SetBindOptions, например параметр dwTickCountDeadline или значение grfFlags BIND_MAYBOTHERUSER.
Затем моникер проверяет значение ROT контекста привязки, чтобы определить, выполняется ли объект, на который указывает ссылка. Моникер может получить эти сведения с помощью следующих вызовов:
```
IBindCtx::GetRunningObjectTable(&prot)
prot->IsRunning(this)
```
Если объект уже запущен, моникер извлекает выполняемый объект с помощью следующего вызова:
```
prot->GetObject(this, &punk)
```
Затем моникер вызывает QueryInterface для запрошенного интерфейса.
В противном случае моникер запрашивает клиент, вызывая IBindStatusCallback::GetBindInfo для получения дополнительных сведений о привязке. Затем моникер инициирует операцию привязки и передает полученный интерфейс IBinding клиенту, вызвав метод IBindStatusCallback::OnStartBinding.
Если на шаге 1 было определено, что это была асинхронная привязка, BindToObject возвращает MK_S_ASYNCHRONOUS на этом этапе со значением NULL в ppv. Вызывающий объект получит фактический указатель объекта во время метода IBindStatusCallback::OnObjectAvailable позже. Следующие шаги затем выполняются асинхронно для вызывающего объекта, как правило, в другом потоке выполнения.
Класс ресурса, обозначенного моникером URL-адреса, определяется одним из следующих способов:
- Моникер URL-адреса проверяет тип носителя данных. Если тип носителя — application/x-oleobject, первые 16 байт фактических данных (Content-Body) содержат CLSID ресурса, а последующие данные должны интерпретироваться самим классом . Для всех остальных типов мультимедиа моникер URL-адреса ищет в системном реестре HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID. Обратите внимание, что application/x-oleobject будет использоваться до утверждения приложения или oleobject.
- Моникер URL-адреса сопоставляет части поступающих данных с шаблонами, зарегистрированными в системном реестре в HKEY_CLASSES_ROOT\FileTypes.
- Наконец, если все остальные не удается, моникер URL-адреса сопоставляет конечное расширение ресурса, если таковое имеется, с ИДЕНТИФИКАТОРом CLSID с помощью HKEY_CLASSES_ROOT\.??? ключи в системном реестре, как это делает GetClassFile и оболочка.
Определив класс, моникер URL-адреса создает экземпляр с помощью CoCreateInstance CLSCTX_SERVER запрашивает интерфейс IUnknown .
Затем моникер URL-адреса вызывает метод QueryInterface нового объекта для интерфейса IPersistMoniker . Если queryInterface выполнен успешно, моникер URL-адреса вызывает IPersistMoniker::Load , передавая себя (this) в качестве параметра моникера. Объект обычно вызывает BindToStorage , запрашивая интерфейс хранилища, который его интересует.
В противном случае моникер URL-адреса вызывает QueryInterface для IPersistStream и в случае успешного выполнения вызывает IPersistStream::Load, передавая объект указателю IStream для объекта потока, заполняемого асинхронно транспортом.
Если вызываемый класс не помечен категорией CATID_AsyncAware, вызывает ISequentialStream::Read или ISequentialStream::Write этот блок ссылочных данных, пока не станет доступным. Эти вызовы блокируются в традиционном смысле COM. Вводится цикл сообщений, который позволяет обрабатывать определенные сообщения, и IMessageFilter потока вызывается соответствующим образом.

Если класс помечен категорией CATID_AsyncAware, вызовы ISequentialStream::Read или ISequentialStream::Write , которые еще недоступны, возвращают E_PENDING.
В противном случае моникер URL-адреса вызывает QueryInterface для IPersistFile и в случае успешного завершения скачивания во временный файл. По завершении моникер URL-адреса вызывает IPersistFile::Load. Созданный файл кэшируется вместе с другими загруженными из Интернета данными. Клиент должен не удалять этот файл.
Когда объект возвращается из одного из различных вызовов Load , описанных на предыдущих шагах, моникер URL-адреса вызывает метод IBindStatusCallback::OnObjectAvailable , чтобы вернуть указатель интерфейса, который клиент первоначально запрашивал при вызове BindToObject.

Требования

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

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

BindMoniker

IMoniker

Поделиться через

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

Синтаксис

Параметры

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

Комментарии

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

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

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

Требования

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

Обратная связь

Дополнительные ресурсы