IMoniker：：BindToObject 方法 (objidl.h)

發行項
01/10/2024

系結至指定的物件。系結程式牽涉到尋找對象、視需要將其放入執行中狀態，以及為呼叫端提供所識別物件上指定介面的指標。

語法

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

參數

[in] pbc

系結內容物件上 IBindCtx 介面的指標，用於這個系結作業。系結內容會在系結程式期間快取系結的物件、包含套用至所有作業的參數，並提供Moniker實作應該擷取其環境相關信息的方法。

[in] pmkToLeft

如果Moniker是複合Moniker的一部分，則指向這個Moniker左邊的Moniker指標。此參數主要是由Moniker實作者用來啟用複合Moniker各種元件之間的合作。 Moniker 用戶端應該使用 NULL。

[in] riidResult

用戶端想要用來與Moniker所識別的物件通訊的介面 IID。

[out] ppvResult

接收 riid 中要求的介面指標的指標變數位址。成功傳回時，*ppvResult 包含Moniker所識別物件的要求介面指標。成功時，實作必須在Moniker上呼叫 AddRef 。呼叫者必須負責呼叫 Release。如果發生錯誤，*ppvResult 應該是 NULL。

傳回值

這個方法可以傳回標準傳回值E_OUTOFMEMORY和E_UNEXPECTED，以及下列值。

傳回碼	描述
S_OK	系結作業成功。
MK_E_NOOBJECT	找不到此Moniker所識別的物件，或這個Moniker所屬複合Moniker所識別的一些物件。
MK_E_EXCEEDEDDEADLINE	系結作業無法在系結內容 BIND_OPTS 結構所指定的時間限制內完成。
MK_E_CONNECTMANUALLY	系結作業需要終端用戶的協助。傳回此值最常見的原因是需要密碼，或需要掛接磁碟驅動器。傳回此值時，使用密鑰 “ConnectManually” 呼叫 IBindCtx：：GetObjectParam 來擷取造成錯誤的 Moniker。然後您可以呼叫 IMoniker：：GetDisplayName 來取得顯示名稱、顯示一個對話方塊來傳達所需的資訊，例如掛接磁碟驅動器或密碼要求的指示，然後重試系結作業。
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED	找到中繼物件，但不支援完成系結作業所需的介面。例如，如果專案Moniker不支援 IOleItemContainer 介面，則會傳回此值。
STG_E_ACCESSDENIED	無法存取記憶體物件。

這個方法也可以傳回與 IOleItemContainer：：GetObject 方法相關聯的錯誤。

備註

BindToObject 會實作Moniker的主要函式，這是找出Moniker所識別的物件，並傳回其中一個介面的指標。

來電者的附註

如果您使用Moniker作為兩個對象之間的持續性連線，您可以呼叫 BindToObject 來啟用連線。

您通常會在下列程式期間呼叫 BindToObject ：

使用呼叫 CreateBindCtx 函式來建立系結內容物件。
使用Moniker呼叫 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 容器會使用 Monikers 來尋找並取得連結物件的存取權，但通常不會直接呼叫 BindToObject 。相反地，當使用者在容器中啟動連結時，連結容器通常會使用連結處理程式的實作呼叫 IOleObject：:D oVerb，這會在鏈接物件中儲存的 Moniker 上呼叫 BindToObject ，如果它無法處理動詞) 則 (。

實作者的注意事項

實作的功能取決於您是否預期Moniker有前置詞;也就是說，您是否預期 pmkToLeft 參數為 NULL 。例如，識別容器內對象的專案Moniker預期 pmkToLeft 會識別容器。因此，專案Moniker會使用 pmkToLeft 向該容器要求服務。如果您預期Moniker有前置詞，您應該使用 pmkToLeft 參數 (例如，在它上呼叫 BindToObject ，) 要求其所識別物件的服務。

如果您預期Moniker沒有前置詞， 您的BindToObject 實作應該先檢查執行中的對象數據表 (ROT) ，以查看物件是否已執行。若要取得 ROT 的指標，您的實作應該呼叫 iBindCtx：：GetRunningObjectTable on the wifi 參數。然後，您可以呼叫 IRunningObjectTable：：GetObject 方法，以查看目前的 Moniker 是否已在 ROT 中註冊。如果是，您可以立即呼叫 QueryInterface ，以取得呼叫端所要求的介面指標。

當您 的 BindToObject 實作系結至某些物件時，它應該使用 azure 參數呼叫 IBindCtx：：RegisterObjectBound 來儲存系結內容中系結物件的參考。這可確保系結物件會繼續執行，直到釋放系結內容為止，這可避免後續的系結作業稍後再載入它的費用。

如果系結內容BIND_OPTS結構指定BINDFLAGS_JUSTTESTEXISTENCE旗標，則您的實作可以選擇在 ppvResult (傳回 NULL，不過您也可以忽略旗標並執行完整的系結作業) 。

實作特定附注

實作	備註
反Moniker	這個方法尚未實作。它會傳回E_NOTIMPL。
類別Moniker	如果 pmkLeft 為 NULL，請使用 CLSID 呼叫 CoGetClassObject，其類別 Moniker 已透過 CreateClassMoniker 中的 (初始化，或透過 MkParseDisplayName) ，以及目前 (IBindCtx) 的 CLSCTX。如果 pmkLeft 不是 NULL，請呼叫 pmkLeft-BindToObject> for IClassActivator，並使用它初始化的 CLSID 呼叫 iClassActivator：：GetClassObject，以及目前 (IBindCtx) 的 CLSCTX 和地區設定參數。
檔案Moniker	當 pmkToLeft 為 NULL 時，此方法會在 ROT 中尋找 Moniker，如果找到，則會查詢所要求介面指標的擷取物件。如果在 ROT 中找不到 Moniker，方法會從文件系統載入物件，並擷取要求的介面指標。如果 pmkLeft 不是 NULL，而不是判斷類別，以使用 GetClassFile (或其他) 方法來具現化和初始化檔案 Moniker 所參考的檔案內容，或呼叫 pmkLeft-BindToObject> for IClassFactory 和 IClassActivator，請在 pcf 中擷取此指標。如果此作業失敗，E_NOINTERFACE，請傳回MK_E_INTERMEDIATEINTERFACENOTSUPPORTED。如果已成功擷取 IClassFactory 指標，請呼叫 pcf-CreateInstance> (IID_IPersistFile， (void**) &ppf) ，以取得要初始化的類別全新實例，並使用 IPersistFile 或其他適當的方法，根據檔案 Moniker 的現有初始化路徑進行初始化。
泛型複合Moniker	如果 pmkToLeft 為 NULL，這個方法會在 ROT 中尋找 Moniker，如果找到，則會查詢所要求介面指標的擷取物件。如果 pmkToLeft 不是 NULL，方法會以遞歸方式在複合最右邊的元件上呼叫 BindToObject ，並將複合的其餘部分當做該呼叫的 pmkToLeft 參數傳遞。
專案Moniker	如果 pmkToLeft 為 NULL，這個方法會傳回E_INVALIDARG。否則，方法會在 pmkToLeft 參數上呼叫 BindToObject，要求 IOleItemContainer 介面指標。方法接著會呼叫 IOleItemContainer：：GetObject、傳遞 Moniker 內含的字串，並傳回要求的介面指標。
OBJREF Moniker	pmkToLeft 參數必須是 NULL。因為 OBJREF Moniker 代表執行中的物件，所以不會進行啟用。如果表示的物件不再執行， BindToObject 會失敗並E_UNEXPECTED。
指標 Moniker	這個方法會查詢所要求介面的包裝指標。
URL Moniker	因為 URL Moniker 支援異步系結，所以其 BindToObject 的實際傳回值可能會因系結內容中建立的物件參數而有所不同。如需詳細資訊，請參閱下列內容。

不論同步或異步使用方式為何，URL Moniker 系結作業的語意都相同，如下所示：

URL Moniker 會從系結內容提取系結作業的進一步資訊。例如，Moniker 可以取得系結內容中註冊之 IBindStatusCallback 和 IEnumFORMATETC 介面的指標。進一步的資訊可以包含透過 IBindCtx：：SetBindOptions 在系結內容上指定的其他系結選項，例如 dwTickCountDeadline 參數或 BIND_MAYBOTHERUSER的 grfFlags 值。
接下來，Moniker 會檢查系結內容的 ROT，以判斷參考的物件是否已執行。 Moniker 可以使用下列呼叫來取得這項資訊：
```
IBindCtx::GetRunningObjectTable(&prot)
prot->IsRunning(this)
```
如果物件已在執行中，Moniker 會使用下列呼叫來擷取執行中的物件：
```
prot->GetObject(this, &punk)
```
然後 Moniker 會呼叫所要求介面的 QueryInterface 。
否則，Moniker 會呼叫 IBindStatusCallback：：GetBindInfo 來查詢用戶端，以取得其他系結資訊。 Moniker 接著會起始系結作業，並藉由呼叫 IBindStatusCallback：：OnStartBinding 將產生的 IBinding 介面傳回用戶端。
如果在步驟 1 中判斷這是異步系結，則 BindToObject 會在 ppv中傳回MK_S_ASYNCHRONOUS。呼叫端會在稍後的某個時間點收到 IBindStatusCallback：：OnObjectAvailable 方法期間的實際物件指標。接著，下列步驟會以異步方式對呼叫端進行，通常是在另一個執行線程上。
URL Moniker 所指定的資源類別是以下列其中一種方式來決定：
- URL Moniker 會檢查數據的媒體類型。如果媒體類型是 application/x-oleobject，則實際數據的前 16 個字節 (Content-Body) 包含資源的 CLSID，而後續數據則由類別本身解譯。針對所有其他媒體類型，URL Moniker 會在系統登錄中尋找 HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID 機碼。請注意，在核准 application/oleobject 之前，將會使用 application/oleobject。
- URL Moniker 會將抵達數據的部分與在系統登錄中註冊的模式比對 HKEY_CLASSES_ROOT\FileTypes。
- 最後，如果所有其他項目都失敗，URL Moniker 會使用 HKEY_CLASSES_ROOT\.???,將資源的尾端延伸與 CLSID 相互關聯系統登錄中的機碼，如 GetClassFile 和殼層所完成。
判斷類別之後，URL Moniker 會使用 CLSCTX_SERVER要求 IUnknown 介面的 CoCreateInstance 建立實例。
URL Moniker 接著會針對 IPersistMoniker 介面呼叫新建立物件的 QueryInterface 方法。如果 QueryInterface 成功，URL Moniker 會呼叫 IPersistMoniker：：Load ， (此) 作為 Moniker 參數。物件通常會呼叫 BindToStorage ，要求他們感興趣的記憶體介面。
否則，URL Moniker 會呼叫適用於 IPersistStream 的 QueryInterface，如果成功，則會呼叫 IPersistStream：：Load，傳遞傳輸以異步方式填入數據流物件的 IStream 指針對象。
如果呼叫的類別未標示為類別CATID_AsyncAware，請呼叫 ISequentialStream：：Read 或 ISequentialStream：：寫入該參考數據尚未可用的區塊，直到數據可用為止。這些呼叫會封鎖傳統 COM 意義。系統會輸入訊息迴圈，以允許處理特定訊息，並適當地呼叫線程的 IMessageFilter 。

如果類別標示為類別CATID_AsyncAware，則呼叫 ISequentialStream：：Read 或 ISequentialStream：：Write ，該參考數據尚未可用傳回E_PENDING。
否則，URL Moniker 會呼叫適用於 IPersistFile 的 QueryInterface，如果成功，則會將下載完成暫存盤。完成時，URL Moniker 會呼叫 IPersistFile：：Load。建立的檔案會連同其他因特網下載的數據一起快取。用戶端必須確定不要刪除此檔案。
當物件從上述步驟所述的其中一個各種 Load 呼叫傳回時，URL Moniker會呼叫 IBindStatusCallback：：OnObjectAvailable 方法，以傳回用戶端在呼叫 BindToObject 時原本要求的介面指標。

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	objidl.h

另請參閱

BindMoniker

IMoniker

共用方式為