DispInvoke 函式 (oleauto.h)

發行項
03/05/2024

根據介面的類型資訊，自動呼叫介面上的成員函式。您可以使用這個單一呼叫來描述具有類型資訊的介面，並實作介面的 Invoke 。

語法

HRESULT DispInvoke(
  void       *_this,
  ITypeInfo  *ptinfo,
  DISPID     dispidMember,
  WORD       wFlags,
  DISPPARAMS *pparams,
  VARIANT    *pvarResult,
  EXCEPINFO  *pexcepinfo,
  UINT       *puArgErr
);

參數

_this

ptinfo 所描述之 IDispatch 介面的實作。

ptinfo

描述介面的類型資訊。

dispidMember

要叫用的成員。使用 GetIDsOfNames 或物件的檔來取得 DISPID。

wFlags

描述 Invoke 呼叫內容的旗標。

值	意義
DISPATCH_METHOD	成員會叫用為方法。如果屬性具有相同的名稱，則可以設定這個和 DISPATCH_PROPERTYGET 旗標。
DISPATCH_PROPERTYGET	成員會擷取為屬性或數據成員。
DISPATCH_PROPERTYPUT	成員會變更為屬性或數據成員。
DISPATCH_PROPERTYPUTREF	成員會由參考指派變更，而不是值指派。只有當屬性接受對象的參考時，這個旗標才有效。

pparams

結構指標，其中包含自變數陣列、具名自變數的自變數 DISPID 陣列，以及陣列中元素數目的計數。

pvarResult

要儲存結果的指標，如果呼叫端預期沒有結果，則為 Null。如果指定DISPATCH_PROPERTYPUT或DISPATCH_PROPERTYPUTREF，則會忽略此自變數。

pexcepinfo

包含例外狀況信息的結構的指標。如果傳回DISP_E_EXCEPTION，則應該填入這個結構。

puArgErr

發生錯誤之第一個自變數的 rgvarg 內的索引。自變數會以反向順序儲存在 pdispparams-rgvarg> 中，因此第一個自變數是陣列中具有最高索引的自變數。只有在產生的傳回值DISP_E_TYPEMISMATCH或DISP_E_PARAMNOTFOUND時，才會傳回此參數。

傳回值

傳回碼	描述
S_OK	成功。
DISP_E_BADPARAMCOUNT	提供給 DISPPARAMS 的項目數目與方法或屬性所接受的自變數數目不同。
DISP_E_BADVARTYPE	DISPPARAMS 中的其中一個自變數不是有效的變體類型。
DISP_E_EXCEPTION	應用程式必須引發例外狀況。在此情況下，應該填入以 pexcepinfo 傳遞的結構。
DISP_E_MEMBERNOTFOUND	要求的成員不存在。
DISP_E_NONAMEDARGS	IDispatch 的這個實作不支援具名自變數。
DISP_E_OVERFLOW	DISPPARAMS 中的其中一個自變數無法強制套用至指定的型別。
DISP_E_PARAMNOTFOUND	其中一個參數標識碼未對應至方法上的參數。在此情況下， puArgErr 會設定為包含錯誤的第一個自變數。
DISP_E_PARAMNOTOPTIONAL	省略必要的參數。
DISP_E_TYPEMISMATCH	無法強制一或多個自變數。在 puArgErr 中傳回類型不正確之第一個參數的索引。
E_INVALIDARG	其中一個參數無效。
E_OUTOFMEMORY	記憶體不足，無法完成作業。

也可以傳回任何 ITypeInfo：：Invoke 錯誤。

備註

參數 _this 是延遲之介面實作的指標。 DispInvoke 會建置堆疊框架、使用標準強制規則強制參數、在堆棧上推送參數，然後在 VTBL 中呼叫正確的成員函式。

範例

下列程式代碼來自 Lines 範例檔案Lines.cpp使用 DispInvoke 實作 Invoke。此實作依賴 DispInvoke 來驗證輸入自變數。為了協助將安全性風險降到最低，請包含執行更強固驗證輸入自變數的程序代碼。

STDMETHODIMP
CLines::Invoke(
   DISPID dispidMember,
   REFIID riid,
   LCID lcid,
   WORD wFlags,
   DISPPARAMS * pdispparams,
   VARIANT * pvarResult,
   EXCEPINFO* pexcepinfo,
   UINT * puArgErr)
{
   return DispInvoke(
   this, m_ptinfo,
   dispidMember, wFlags, pdispparams,
   pvarResult, pexcepinfo, puArgErr); 
}