IDispatch：：GetIDsOfNames 方法 (oaidl.h)

發行項
02/29/2024

將單一成員和一組選擇性的自變數名稱對應至一組對應的整數 DISPID，可用於後續對 Invoke 的呼叫。分派函式 DispGetIDsOfNames 提供 GetIDsOfNames 的標準實作。

語法

HRESULT GetIDsOfNames(
  [in]  REFIID   riid,
  [in]  LPOLESTR *rgszNames,
  [in]  UINT     cNames,
  [in]  LCID     lcid,
  [out] DISPID   *rgDispId
);

參數

[in] riid

保留供未來使用。必須是 IID_NULL。

[in] rgszNames

要對應的名稱陣列。

[in] cNames

要對應之名稱的計數。

[in] lcid

用於解譯名稱的地區設定內容。

[out] rgDispId

呼叫端配置的陣列，其中每個元素都包含標識碼 (標識碼) 對應至 rgszNames 陣列中傳遞的其中一個名稱。第一個專案代表成員名稱。後續元素代表每個成員的參數。

傳回值

這個方法可以傳回其中一個值。

傳回碼	描述
S_OK	成功。
E_OUTOFMEMORY	記憶體不足。
DISP_E_UNKNOWNNAME	不知道一或多個指定的名稱。 DISPID 的傳回數位包含對應至未知名稱之每個專案的DISPID_UNKNOWN。
DISP_E_UNKNOWNLCID	無法辨識 LCID) 的地區設定標識碼 (。

備註

IDispatch 實作可以將任何正整數標識碼值與指定名稱產生關聯。零會保留給預設值，或 Value 屬性;–1 是保留來表示未知的名稱;和其他負值會針對其他用途定義。例如，如果呼叫 GetIDsOfNames ，而且實作無法辨識一或多個名稱，則會傳回DISP_E_UNKNOWNNAME，而 rgDispId 陣列包含對應至未知名稱之專案的DISPID_UNKNOWN。

成員和參數 DISPID 在物件的存留期內必須維持不變。這可讓用戶端取得 DISPID 一次，並快取它們以供稍後使用。

當使用多個名稱呼叫 GetIDsOfNames 時，名字 (rgszNames[0]) 對應至成員名稱，後續名稱會對應至成員的參數名稱。

相同的名稱可能會對應至不同的 DISPID，視內容而定。例如，當名稱當做具有特定介面的成員名稱使用時，名稱可能會有 DISPID、不同標識碼作為不同介面的成員，以及每次顯示為參數時的不同對應。

當 IDispatch 用戶端系結至運行時間的名稱時，會使用 GetIDsOfNames。若要改為在編譯時期系結， IDispatch 用戶端可以使用類型描述介面中所述的類型資訊介面，將名稱對應至 DISPID。這可讓客戶端在編譯時期系結至成員，並避免在運行時間呼叫 GetIDsOfNames 。如需編譯時期系結的描述，請參閱類型描述介面。

GetIDsOfNames 的實作不區分大小寫。需要區分大小寫名稱對應的用戶應該使用類型資訊介面，將名稱對應至 DISPID，而不是呼叫 GetIDsOfNames。

謹慎您無法使用此方法來存取已動態新增的值，例如透過 JavaScript 新增的值。請改用 IDispatchEx 介面的 GetDispID。如需詳細資訊，請參閱 IDispatchEx 介面。

範例

下列來自Lines範例檔案的程式代碼Lines.cpp實作 CLine 類別的 GetIDsOfNames 成員函式。 ActiveX 或 OLE 物件會使用標準實作 DispGetIDsOfNames。此實作依賴 DispGetIdsOfNames 來驗證輸入自變數。為了協助將安全性風險降到最低，請包含執行更強固驗證輸入自變數的程序代碼。

STDMETHODIMP 
CLine::GetIDsOfNames(
      REFIID riid,
      OLECHAR ** rgszNames,
      UINT cNames,
      LCID lcid,
      DISPID * rgDispId)
{
      return DispGetIDsOfNames(m_ptinfo, rgszNames, cNames, rgDispId);
}

下列程式代碼可能會出現在呼叫 GetIDsOfNames 的 ActiveX 用戶端中，以取得 CLineColor 屬性的 DISPID。

HRESULT hresult;
IDispatch * pdisp = (IDispatch *)NULL;
DISPID dispid;
OLECHAR * szMember = "color";

// Code that sets a pointer to the dispatch (pdisp) is omitted.

hresult = pdisp->GetIDsOfNames(
   IID_NULL,
   &szMember,
   1, LOCALE_SYSTEM_DEFAULT,
   &dispid);