本文同步刊載於謀智台客。

在研讀 Gecko 的程式碼時，常常會看到 do_QueryInterface 與 do_GetInterface 的用法出現，另外還有一個比較少見的 do_QueryObject。這三個函式的主要用途都是對於一個物件請求另一個介面的物件。在介紹這三個函式之前，我們先介紹 QueryInterface 與 GetInterface 這兩個函式的用途。

QueryInterface

讓我們先從 QueryInterface 講起。在 Gecko 中，所有的 XPCOM 元件都是繼承自 nsISupports 這個類別。在 nsISupports 中，定義了三個成員函式，分別是：

  • AddRef
  • Release
  • QueryInterface

這邊要探討的就是其中的 QueryInterface 這個成員函式。一般來說，XPCOM 元件都會繼承不同的 XPIDL interface，要查詢一個物件是否「具備」某個 XPIDL interface 就可以使用 QueryInterface 來進行。若該物件具備該 XPIDL interface 可以使用的話，QueryInterface 就會以該 XPIDL interface 來回傳該物件的指標。也就是說，該物件的類別本身有繼承該 XPIDL interface，所以才能用 QueryInterface 來取得。因此，經過 QueryInterface 取得的物件與原本的物件其實還是同一個物件，所以同樣能夠用 QueryInterface 來返回原本的物件。也就是說，QueryInterface 是個 interface 間的雙向通道。

P.S. 當類別被定義為可以被 cycle collector 偵測時，便可以向該類別請求 nsCycleCollectionISupports 與 nsXPCOMCycleCollectionParticipant 這兩個 interface。而這兩個 interface 本身並不是 XPCOM，因此並無法再透過 QueryInterface 將已經被轉型為這兩個 interface 的物件轉型回原本的 interface。

QueryInterface

而 QueryInterface 的函式定義不需要自己編寫，編譯器可以幫我們產生。在編寫 XPCOM 元件時，只要加入 NS_DECL_ISUPPORTS 這個敘述在類別的定義中即可使得該類別具有 nsISupports 的介面。而在成員函式的實作中，只要加上 NS_IMPL_ISUPPORTS(class name, interface1, interface2, ...)，編譯器就會產生相對應的 QueryInterface、AddRef 與 Release 這三個成員函式的定義。如果是使用 JavaScript 所寫的 XPCOM 元件的話，只要在 prototype 中加入 QueryInterface: XPCOMUtils.generateQI([Ci.interface1, Ci.interface2, ...]) 這個項目，即可自動產生相對應的 QueryInterface 函式。

GetInterface

GetInterface 來自 nsIInterfaceRequestor 這個 XPIDL interface。前面提到的 QueryInterface 是用來查詢物件是否「具備」某個 XPIDL interface，所以該物件的類別必須有繼承要查詢的 XPIDL interface 才能返回結果。而 GetInterface 則是用來向物件「請求」某個 XPIDL interface 的物件，而這個物件可以不必是該物件的類別所繼承的。所以回傳的結果可能是該類別的成員物件、另外創建的物件或是物件本身。因此，經由 GetInterface 取得的物件，大部分都不是同一個物件。這使得該物件並不一定能夠用 GetInterface 來返回原本的物件。

GetInterface

若要令一個類別支援 GetInterface 必須要讓該類別繼承 nsIInterfaceRequestor 這個 interface。並且，需要自行編寫 GetInterface 的函式定義。因為每個類別針對不同 XPIDL interface 的請求會有不同的需求，所以需要自己定義。

以 nsDocShell 的 GetInterface 片段程式碼為例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

NS_IMETHODIMP
nsDocShell::GetInterface(const nsIID& aIID, void** aSink)
{
  NS_PRECONDITION(aSink, "null out param");

  *aSink = nullptr;

  if (aIID.Equals(NS_GET_IID(nsICommandManager))) {
	NS_ENSURE_SUCCESS(EnsureCommandHandler(), NS_ERROR_FAILURE);
	*aSink = mCommandManager;
  } else if (aIID.Equals(NS_GET_IID(nsIURIContentListener))) {
	*aSink = mContentListener;
  } else if ((aIID.Equals(NS_GET_IID(nsIScriptGlobalObject)) ||
			  aIID.Equals(NS_GET_IID(nsIGlobalObject)) ||
			  aIID.Equals(NS_GET_IID(nsPIDOMWindow)) ||
			  aIID.Equals(NS_GET_IID(nsIDOMWindow)) ||
			  aIID.Equals(NS_GET_IID(nsIDOMWindowInternal))) &&
			 NS_SUCCEEDED(EnsureScriptEnvironment())) {
	return mScriptGlobal->QueryInterface(aIID, aSink);
  } else if (aIID.Equals(NS_GET_IID(nsIDOMDocument)) &&
			 NS_SUCCEEDED(EnsureContentViewer())) {
	mContentViewer->GetDOMDocument((nsIDOMDocument**)aSink);
	return *aSink ? NS_OK : NS_NOINTERFACE;
  } else if (aIID.Equals(NS_GET_IID(nsIDocument)) &&
			 NS_SUCCEEDED(EnsureContentViewer())) {
	nsCOMPtr<nsIDocument> doc = mContentViewer->GetDocument();
	doc.forget(aSink);
	return *aSink ? NS_OK : NS_NOINTERFACE;
  } else if (aIID.Equals(NS_GET_IID(nsIApplicationCacheContainer))) {
	*aSink = nullptr;

	// Return application cache associated with this docshell, if any
	...
  }
  ...
  NS_IF_ADDREF(((nsISupports*)*aSink));
  return *aSink ? NS_OK : NS_NOINTERFACE;
}

我們可以發現 GetInterface 其實就是一堆 if-else 的判斷敘述，並根據不同的 XPIDL interface 的 IID 來返回不同的對象。

do_QueryInterface 與 do_GetInterface

讓我們回到 do_QueryInterface、do_GetInterface 以及 do_QueryObject 這三個函式。不過這邊我們先介紹 do_QueryInterface 與 do_GetInterface，稍後在介紹 do_QueryObject。先以 NewChannelFromURIWithProxyFlagsInternal 這個函式內的片段程式碼為例：

1
2
3
4
5
6
7
8
9
10
11
12

nsCOMPtr<nsIProtocolHandler> handler;
rv = GetProtocolHandler(scheme.get(), getter_AddRefs(handler));

// do something

nsCOMPtr<nsIProxiedProtocolHandler> pph = do_QueryInterface(handler);
if (pph) {
  // do something
}
else {
  // do something
}

在這段程式碼中，一開始先拿到了一個指向 nsIProtocolHandler 的 nsCOMPtr 物件，接著便呼叫 do_QueryInterface 來嘗試取得指向 nsIProxiedProtocolHandler 的 nsCOMPtr 物件。這邊很神奇的是，為什麼 do_QueryInterface 並不需要給予 nsIProxiedProtocolHandler 的 IID 來進行查詢就可以返回相對應的物件呢？

這邊我們可以看到 do_QueryInterface 的原始碼：

1
2
3
4
5

inline nsQueryInterface
do_QueryInterface(nsISupports* aRawPtr)
{
  return nsQueryInterface(aRawPtr);
}

這裏很單純的返回一個用原始物件初始化的 nsQueryInterface 物件。而這個物件將被回傳給身為 nsCOMPtr<nsIProxiedProtocolHandler> 型別的變數 pph。此時，C++ 會默默的呼叫 nsCOMPtr<nsIProxiedProtocolHandler> 的建構子。其定義如下：

1
2
3
4
5
6

MOZ_IMPLICIT nsCOMPtr(const nsQueryInterface aQI)
  : NSCAP_CTOR_BASE(0)
{
  NSCAP_LOG_ASSIGNMENT(this, 0);
	assign_from_qi(aQI, NS_GET_TEMPLATE_IID(T));
}

這裡可以發現終於有 IID 的資訊了。只要呼叫 NS_GET_TEMPLATE_IID(T) 即可得到 nsIProxiedProtocolHandler 的 IID 了。再將 do_QueryInterface 所回傳的 nsQueryInterface 物件與 XPIDL interface 的 IID 作為參數來呼叫 assign_from_qi，其定義如下：

1
2
3
4
5
6
7
8
9
10

template<class T>
void
nsCOMPtr<T>::assign_from_qi(const nsQueryInterface aQI, const nsIID& aIID)
{
  void* newRawPtr;
  if (NS_FAILED(aQI(aIID, &newRawPtr))) {
	newRawPtr = 0;
  }
  assign_assuming_AddRef(static_cast<T*>(newRawPtr));
}

在 assign_from_qi 裡面，nsQueryInterface 竟然被作為函式呼叫。讓我們來看到 nsQueryInterface 的定義：

1
2
3
4
5
6
7
8
9
10
11

class MOZ_STACK_CLASS nsQueryInterface MOZ_FINAL
{
public:
  explicit
  nsQueryInterface(nsISupports* aRawPtr) : mRawPtr(aRawPtr) {}

  nsresult NS_FASTCALL operator()(const nsIID& aIID, void**) const;

private:
  nsISupports* MOZ_OWNING_REF mRawPtr;
};

這裡定義了 nsQueryInterface 的 functor (operator())，所以 nsQueryInterface 該類別的物件可以被作為函式進行呼叫。而其定義如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

nsresult
nsQueryInterface::operator()(const nsIID& aIID, void** aAnswer) const
{
  nsresult status;
  if (mRawPtr) {
	status = mRawPtr->QueryInterface(aIID, aAnswer);
#ifdef NSCAP_FEATURE_TEST_NONNULL_QUERY_SUCCEEDS
	NS_ASSERTION(NS_SUCCEEDED(status),
				 "interface not found---were you expecting that?");
#endif
  } else {
	status = NS_ERROR_NULL_POINTER;
  }

  return status;
}

就在這個 functor 的定義中，終於讓發現 QueryInterface 被呼叫的蹤跡了。如此一來，就可以拿到指向 nsIProxiedProtocolHandler 介面的 nsCOMPtr 物件了。

讓我們整理一下從 do_QueryInterface 進行 interface 的請求的流程：

  1. do_QueryInterface 返回 nsQueryInterface 物件。
  2. 將回傳的 nsQueryInterface 物件作為參數來呼叫 nsCOMPtr<T> 的建構子。
  3. 取得 nsCOMPtr<T> 中 T 的 IID。
  4. 將 IID 作為參數來呼叫 nsQueryInterface 的 functor。
  5. nsQueryInterface 的 functor 裡在實際去呼叫原本物件的 QueryInterface 函式來進行 XPIDL interface 的請求。

至於 do_GetInterface 的做法也是類似的。比較不一樣的地方是 do_GetInterface 回傳的是一個 nsGetInterface 的物件。但是我們無法找到適用於 nsGetInterface 的 nsCOMPtr<T> 建構子。但可以發現 nsGetInterface 繼承自 nsCOMPtr_helper，並且 nsCOMPtr<T> 有相對應的建構子：

1
2
3
4
5
6
7

MOZ_IMPLICIT nsCOMPtr(const nsCOMPtr_helper& aHelper)
  : NSCAP_CTOR_BASE(0)
{
  NSCAP_LOG_ASSIGNMENT(this, 0);
  assign_from_helper(aHelper, NS_GET_TEMPLATE_IID(T));
  NSCAP_ASSERT_NO_QUERY_NEEDED();
}

接下來就類似 do_QueryInterface 的流程進行下去，最後一樣會把 nsGetInterface 物件作為函式呼叫，來實際呼叫 GetInterface。

do_QueryObject

除了前面提到的 do_QueryInterface 與 do_GetInterface 之外，Gecko 的程式碼中也很常看到使用 do_QueryObject 來進行轉型。先來看到 do_QeuryObject 的定義：

1
2
3
4
5
6

template<class T>
inline nsQueryObject<T>
do_QueryObject(T* aRawPtr)
{
  return nsQueryObject<T>(aRawPtr);
}

與其他兩者相似，都是產生一個物件回傳。該物件為 nsQueryObject，其定義如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

template<class T>
class MOZ_STACK_CLASS nsQueryObject : public nsCOMPtr_helper
{
public:
  explicit nsQueryObject(T* aRawPtr)
    : mRawPtr(aRawPtr)
  {
  }

  virtual nsresult NS_FASTCALL operator()(const nsIID& aIID,
                                          void** aResult) const MOZ_OVERRIDE
  {
    nsresult status = mRawPtr ? mRawPtr->QueryInterface(aIID, aResult)
                              : NS_ERROR_NULL_POINTER;
    return status;
  }
private:
  T* MOZ_NON_OWNING_REF mRawPtr;
};

單從這個物件的 functor 來看，似乎與 nsQueryInterface 的 functor 無異。因此，do_QueryObject 的實際行為與 do_QueryInterface 完全相同。不一樣的地方在於 do_QueryObject 是一個函式樣板 (function template)，其參數不像 do_QueryInterface 一樣都是 nsISupports* 而是根據傳入的參數型別所生成的 T*。因此使用 do_QueryObject 的話，物件並不會被轉型為 nsISupports*，而是保持原本的型別來呼叫 QueryInterface。

而之所以會有需要這個函式原因在於大部份的實體類別 (concrete class) 存在 diamond inheritance pattern 的現象，因此使得該物件在進行轉型到 nsISupports 出現的混淆 (ambiguous) 的情況。

以 nsDocShell 這個類別來說，其繼承的 XPIDL interface 如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class nsDocShell MOZ_FINAL
  : public nsDocLoader
  , public nsIDocShell
  , public nsIWebNavigation
  , public nsIBaseWindow
  , public nsIScrollable
  , public nsITextScroll
  , public nsIDocCharset
  , public nsIContentViewerContainer
  , public nsIRefreshURI
  , public nsIWebProgressListener
  , public nsIWebPageDescriptor
  , public nsIAuthPromptProvider
  , public nsILoadContext
  , public nsIWebShellServices
  , public nsILinkHandler
  , public nsIClipboardCommands
  , public nsIDOMStorageManager
  , public nsINetworkInterceptController
  , public mozilla::SupportsWeakPtr<nsDocShell>
{
  // something
};

nsDocShell 繼承的所有 XPIDL interface 本身也都繼承自 nsISupports，diamond inheritance pattern 的現象就這麼發生了。在 Gecko 中，有非常多的實體類別與 nsDocShell 一樣都同時繼承了兩個以上的 XPIDL interface，所以 diamond inheritance pattern 的現象其實在 Gecko 裡面很常見。因此，當我們要對 nsDocShell* 請求他所支援的 XPIDL interface 時，就需要使用 do_QueryObject 來進行，才不會產生編譯錯誤。

不過，使用 do_QueryObject 也是需要付出代價的。前面有提到，do_QueryObject 本身是一個函式樣板，樣板的運作原理是透過編譯器來產生一份針對該型別的程式碼。在 Gecko 中有非常多實體類別，如果這些類別在進行請求 interface 時都透過 do_QueryObject 的話，除了編譯時間會增加外，編譯出來的程式大小也將變得更加肥大。畢竟這將使得每個類別都有一份屬於自己的 do_QueryObject 函式以及一份屬於自己的 nsQueryObject 類別。

此外，我們也可以透過 static_cast 來解決同樣的問題。在開發時，通常我們已知該實體類別所支援的 XPIDL interface。因此先透過 static_cast 轉型為其中一個 XPIDL interface 就不會有 diamond inheritance pattern 的現象發生了。例如以下的程式碼：

1

nsCOMPtr<nsIDocShellTreeItem> docShellItem(do_QueryInterface(static_cast<nsIDocShell*>(mDocShell)));

P.S. XPIDL interface 不允許多重繼承，因此不會有 diamond inheritance pattern 的現象。

然而，static_cast 不會檢查執行期的物件狀態，單純檢查類別之間是否存在繼承關係。因此，在執行期物件可能會無法轉型成功而造成程式執行錯誤。理論上，不建議使用 static_cast 這樣危險的轉型方法。

總結

以上我們介紹了 QueryInterface 與 GetInterface 的相異之處。主要的差別在於轉型後的結果是否可以透過同樣的方式轉型回去。

另外，我們介紹了這兩個轉型函式的輔助函式 do_QueryInterface、do_GetInterface 與 do_QueryObject。do_QueryInterface 與 do_GetInterface 差別在於 QueryInterface 與 GetInterface 的功能上差異。而 do_QueryInterface 與 do_QueryObject 其功能上完全相同，差別在於使用的對象。do_QueryInterface 用來對一個 XPIDL interface 的指標請求某個 XPIDL interface，do_QueryObject 則用來對一個實體類別的指標請求某個 XPIDL interface。