ComPtr 類別

建立代表範本參數所指定之介面的 「智慧型指標」 (Smart Pointer) 類型。 ComPtr 自動維護基礎介面指標的參考計數，並在參考計數歸零時釋放介面。

語法

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

參數

T
所表示的 ComPtr 介面。

U
目前 ComPtr 為 friend 的類別。 (使用這個參數的範本會受到保護)。

備註

ComPtr<> 宣告表示基礎介面指標的型別。 使用 ComPtr<> 來宣告變數，然後使用箭頭成員存取運算子 （ -> ） 來存取介面成員函式。

如需智慧型指標的詳細資訊，請參閱 COM 程式碼撰寫實務 文章的 小節。

成員

公用 Typedefs

名稱	描述
InterfaceType	T 範本參數所指定之類型的同義字。

公用建構函式

名稱	描述
ComPtr::ComPtr	初始化 ComPtr 類別的新執行個體。 多載提供預設、複製、移動和轉換建構函式。
ComPtr::~ComPtr	將 的 ComPtr 實例取消初始化。

公用方法

名稱	描述
ComPtr::As	ComPtr傳回 物件，表示指定之樣板參數所識別的介面。
ComPtr::AsIID	ComPtr傳回 物件，表示指定介面識別碼所識別的介面。
ComPtr::AsWeak	擷取目前物件的弱式參考。
ComPtr::Attach	將這個 ComPtr 與目前範本類型參數指定的介面類別型產生關聯。
ComPtr::CopyTo	將與此 ComPtr 相關聯的目前或指定的介面複製到指定的輸出指標。
ComPtr::Detach	將這個 ComPtr 與它所代表的介面解除關聯。
ComPtr::Get	擷取與這個 ComPtr 相關聯之介面的指標。
ComPtr::GetAddressOf	擷取資料成員的 ptr_ 位址，其中包含這個 ComPtr 所表示之介面的指標。
ComPtr::ReleaseAndGetAddressOf	釋放與此 ComPtr 相關聯的介面，然後擷取資料成員的 ptr_ 位址，其中包含已釋放之介面的指標。
ComPtr::Reset	釋放與此 ComPtr 相關聯的介面，並傳回新的參考計數。
ComPtr::Swap	使用所指定 ComPtr 所管理的介面，交換目前 ComPtr 所管理的介面。

受保護的方法

名稱	描述
ComPtr::InternalAddRef	遞增與這個 ComPtr 相關聯之介面的參考計數。
ComPtr::InternalRelease	在與此 ComPtr 相關聯的介面上執行 COM 發行作業。

公用運算子

名稱	描述
ComPtr::operator&	擷取目前 ComPtr 的位址。
ComPtr::operator->	擷取目前範本參數所指定之類型的指標。
ComPtr::operator=	將值指派給目前的 ComPtr 。
ComPtr::operator==	表示兩個 ComPtr 物件是否相等。
ComPtr::operator!=	指出兩個 ComPtr 物件是否不相等。
ComPtr::operator Microsoft::WRL::Details::BoolType	指出 是否 ComPtr 正在管理介面的物件存留期。

受保護的資料成員

名稱	描述
ComPtr::ptr_	包含與 相關聯之介面的指標，並由這個 ComPtr 管理。

繼承階層架構

ComPtr

需求

標頭：client.h

命名空間：Microsoft::WRL

ComPtr::~ComPtr

將 的 ComPtr 實例取消初始化。

WRL_NOTHROW ~ComPtr();

ComPtr::As

ComPtr傳回 物件，表示指定之樣板參數所識別的介面。

template<typename U>
HRESULT As(
   _Out_ ComPtr<U>* p
) const;

template<typename U>
HRESULT As(
   _Out_ Details::ComPtrRef<ComPtr<U>> p
) const;

參數

U
要以參數 p 表示的介面。

p
ComPtr物件，表示 參數 U 所指定的介面。 參數 p 不得參考目前的 ComPtr 物件。

備註

第一個範本是程式碼中應該使用的表單。 第二個範本是內部協助程式特製化。 它支援 C++ 語言功能，例如 auto 類型推算關鍵字。

傳回值

S_OK 如果成功，則為 ;否則， HRESULT 表示錯誤的 。

ComPtr::AsIID

ComPtr傳回 物件，表示指定介面識別碼所識別的介面。

WRL_NOTHROW HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IUnknown>* p
) const;

參數

riid
介面識別碼。

p
如果 物件具有識別碼等於 riid 的介面，則為 參數所 riid 指定之介面的雙重間接指標。 否則，指向 的 IUnknown 指標。

傳回值

S_OK 如果成功，則為 ;否則， HRESULT 表示錯誤的 。

ComPtr::AsWeak

擷取目前物件的弱式參考。

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

參數

pWeakRef
當此作業完成時，弱式參考物件的指標。

傳回值

如果作業成功，會傳送 S_OK；反之則傳送表示錯誤的 HRESULT 值。

ComPtr::Attach

將這個 ComPtr 與目前範本類型參數指定的介面類別型產生關聯。

void Attach(
   _In_opt_ InterfaceType* other
);

參數

other
介面類別型。

ComPtr::ComPtr

初始化 ComPtr 類別的新執行個體。 多載提供預設、複製、移動和轉換建構函式。

WRL_NOTHROW ComPtr();

WRL_NOTHROW ComPtr(
   decltype(__nullptr)
);

template<class U>
WRL_NOTHROW ComPtr(
   _In_opt_ U *other
);

WRL_NOTHROW ComPtr(
   const ComPtr& other
);

template<class U>
WRL_NOTHROW ComPtr(
   const ComPtr<U> &other,
   typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

WRL_NOTHROW ComPtr(
   _Inout_ ComPtr &&other
);

template<class U>
WRL_NOTHROW ComPtr(
   _Inout_ ComPtr<U>&& other, typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

參數

U
other 參數的類型。

other
U 類型的物件。

傳回值

備註

第一個建構函式是預設建構函式，其會隱含建立空白物件。 第二個建構函式會 __nullptr 指定 ，它會明確建立空的物件。

第三個建構函式會從指標所指定的 物件建立 物件。 ComPtr現在擁有指向的記憶體，並維護它的參考計數。

第四個和第五個建構函式是複製建構函式。 第五個建構函式會複製物件，如果物件可轉換成目前類型。

第六個和第七個建構函式是移動建構函式。 第七個建構函式會在物件可轉換成目前類型時移動物件。

ComPtr::CopyTo

將與此 ComPtr 相關聯的目前或指定的介面複製到指定的指標。

HRESULT CopyTo(
   _Deref_out_ InterfaceType** ptr
);

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ void** ptr
) const;

template<typename U>
HRESULT CopyTo(
   _Deref_out_ U** ptr
) const;

參數

U
類型名稱。

ptr
此作業完成時，所要求介面的指標。

riid
介面識別碼。

傳回值

S_OK 如果成功，則為 ;否則， HRESULT 表示隱含 QueryInterface 作業失敗的原因。

備註

第一個函式會傳回與這個 ComPtr 相關聯之介面的指標複本。 此函式一律會傳 S_OK 回 。

第二個 QueryInterface 函式會針對 參數所 riid 指定的介面，對與這個 ComPtr 相關聯的介面執行作業。

第三個 QueryInterface 函式會針對 參數的基礎介面，在與這個 ComPtr 相關聯的介面 U 上執行作業。

ComPtr::Detach

將這個 ComPtr 物件與它所代表的介面解除關聯。

T* Detach();

傳回值

這個 ComPtr 物件所表示之介面的指標。

ComPtr::Get

擷取與這個 ComPtr 相關聯之介面的指標。

T* Get() const;

傳回值

與這個 ComPtr 相關聯之介面的指標。

ComPtr::GetAddressOf

擷取資料成員的 ptr_ 位址，其中包含這個 ComPtr 所表示之介面的指標。

T* const* GetAddressOf() const;
T** GetAddressOf();

傳回值

變數的位址。

ComPtr::InternalAddRef

遞增與這個 ComPtr 相關聯之介面的參考計數。

void InternalAddRef() const;

備註

此方法受到保護。

ComPtr::InternalRelease

在與此 ComPtr 相關聯的介面上執行 COM 發行作業。

unsigned long InternalRelease();

備註

此方法受到保護。

ComPtr::operator&

釋放與此 ComPtr 物件相關聯的介面，然後擷取 物件的位址 ComPtr 。

Details::ComPtrRef<WeakRef> operator&()

const Details::ComPtrRef<const WeakRef> operator&() const

傳回值

目前 ComPtr 的弱式參考。

備註

這個方法與 ComPtr::GetAddressOf 不同之處在于，此方法會釋放介面指標的參考。 當您需要介面指標的位址，但不想釋放該介面時，請使用 ComPtr::GetAddressOf 。

ComPtr::operator->

擷取目前範本參數所指定之類型的指標。

WRL_NOTHROW Microsoft::WRL::Details::RemoveIUnknown<InterfaceType>* operator->() const;

傳回值

目前範本類型名稱所指定的型別指標。

備註

此協助程式函式會移除使用 STDMETHOD 宏所造成的不必要的額外負荷。 此函式會建立 IUnknown 型 private 別， virtual 而不是 。

ComPtr::operator=

將值指派給目前的 ComPtr 。

WRL_NOTHROW ComPtr& operator=(
   decltype(__nullptr)
);
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ T *other
);
template <typename U>
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ U *other
);
WRL_NOTHROW ComPtr& operator=(
   const ComPtr &other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   const ComPtr<U>& other
);
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr &&other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr<U>&& other
);

參數

U
類別。

other
型別或其他 ComPtr 的指標、參考或右值參考。

傳回值

目前 ComPtr 的參考。

備註

這個運算子的第一個版本會將空值指派給目前的 ComPtr 。

在第二個版本中，如果指派介面指標與目前的 ComPtr 介面指標不同，則會將第二個介面指標指派給目前的 ComPtr 。

第三個版本中，指派介面指標會指派給目前的 ComPtr 。

在第四個版本中，如果指派值的介面指標與目前 ComPtr 介面指標不同，則會將第二個介面指標指派給目前的 ComPtr 。

第五個版本是複製運算子;的 ComPtr 參考會指派給目前的 ComPtr 。

第六個版本是使用移動語意的複製運算子;如果任何型別為靜態轉換，則為 的右值參考 ComPtr ，然後指派給目前的 ComPtr 。

第七個版本是使用移動語意的複製運算子;型別 的 ComPtr 右值參考是靜態轉換，然後指派給目前的 ComPtr 。 U

ComPtr::operator==

表示兩個 ComPtr 物件是否相等。

bool operator==(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator==(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator==(
   decltype(__nullptr),
   const ComPtr<T>& a
);

參數

a
對 ComPtr 物件的參考。

b
另一個 ComPtr 物件的參考。

傳回值

如果 物件等於 物件 ab ，則第一個運算子會產生 true ，否則 false 為 。

如果 物件等於 ，則第二個和第三個運算子會產生 true ，否則為 false 。 nullptra

ComPtr::operator!=

指出兩個 ComPtr 物件是否不相等。

bool operator!=(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator!=(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator!=(
   decltype(__nullptr),
   const ComPtr<T>& a
);

參數

a
對 ComPtr 物件的參考。

b
另一個 ComPtr 物件的參考。

傳回值

如果 物件不等於 物件 ab ，則第一個運算子會產生 true ;否則 false 為 。

如果 物件不等於 nullptr ，則第二個和第三個運算子會產生 true ，否則為 false 。 a

ComPtr::operator Microsoft::WRL::Details::BoolType

指出 是否 ComPtr 正在管理介面的物件存留期。

WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const;

傳回值

如果介面與此 ComPtr 相關聯，則為資料成員的 BoolStruct::Member 位址， nullptr 否則為 。

ComPtr::ptr_

包含與 相關聯之介面的指標，並由這個 ComPtr 管理。

InterfaceType *ptr_;

備註

ptr_ 是內部受保護的資料成員。

ComPtr::ReleaseAndGetAddressOf

釋放與此 ComPtr 相關聯的介面，然後擷取資料成員的 ptr_ 位址，其中包含已釋放之介面的指標。

T** ReleaseAndGetAddressOf();

傳回值

這個 ComPtr 的資料成員位址 ptr_ 。

ComPtr::Reset

釋放與此 ComPtr 相關聯的介面，並傳回新的參考計數。

unsigned long Reset();

傳回值

基礎介面剩餘的參考數目，如果有的話。

ComPtr::Swap

使用所指定 ComPtr 所管理的介面，交換目前 ComPtr 所管理的介面。

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

參數

r
ComPtr。