ComPtr 類別ComPtr Class

建立代表範本參數所指定之介面的 「智慧型指標」 (Smart Pointer) 類型。Creates a smart pointer type that represents the interface specified by the template parameter. ComPtr 自動維護基礎介面指標的參考計數,並在參考計數歸零時釋放介面。ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

語法Syntax

template <typename T>
class ComPtr;

template<class T>
friend class ComPtr;

參數Parameters

TT
表示的介面 ComPtrThe interface that the ComPtr represents.

UU
目前 ComPtr 為 friend 的類別。A class to which the current ComPtr is a friend. (使用這個參數的範本會受到保護)。(The template that uses this parameter is protected.)

備註Remarks

ComPtr<>宣告代表基礎介面指標的類型。ComPtr<> declares a type that represents the underlying interface pointer. 使用 ComPtr<> 來宣告變數,然後使用箭號成員存取運算子( -> )來存取介面成員函式。Use ComPtr<> to declare a variable and then use the arrow member-access operator (->) to access an interface member function.

如需智慧型指標的詳細資訊,請參閱Com 編碼實務文章的「Com 智慧型指標」子節。For more information about smart pointers, see the "COM Smart Pointers" subsection of the COM Coding Practices article.

成員Members

公用 TypedefsPublic Typedefs

名稱Name 說明Description
InterfaceType T範本參數所指定之類型的同義字。A synonym for the type specified by the T template parameter.

公用建構函式Public Constructors

名稱Name 說明Description
ComPtr:: ComPtrComPtr::ComPtr 初始化 ComPtr 類別的新執行個體。Initializes a new instance of the ComPtr class. 多載提供預設、複製、移動和轉換建構函式。Overloads provide default, copy, move, and conversion constructors.
ComPtr:: ~ ComPtrComPtr::~ComPtr 將的實例 ComPtrDeinitializes an instance of ComPtr.

公用方法Public Methods

名稱Name 說明Description
ComPtr:: AsComPtr::As 傳回 ComPtr 物件,表示指定之範本參數所識別的介面。Returns a ComPtr object that represents the interface identified by the specified template parameter.
ComPtr:: AsIIDComPtr::AsIID 傳回 ComPtr 物件,表示指定之介面識別碼所識別的介面。Returns a ComPtr object that represents the interface identified by the specified interface ID.
ComPtr:: AsWeakComPtr::AsWeak 擷取目前物件的弱式參考。Retrieves a weak reference to the current object.
ComPtr:: AttachComPtr::Attach 將這個 ComPtr 與目前範本類型參數所指定的介面類別型產生關聯。Associates this ComPtr with the interface type specified by the current template type parameter.
ComPtr:: CopyToComPtr::CopyTo 將與這個相關聯的目前或指定的介面複製 ComPtr 到指定的輸出指標。Copies the current or specified interface associated with this ComPtr to the specified output pointer.
ComPtr::D etachComPtr::Detach 將這個 ComPtr 與它所代表的介面解除。Disassociates this ComPtr from the interface that it represents.
ComPtr:: GetComPtr::Get 抓取與這個相關聯之介面的指標 ComPtrRetrieves a pointer to the interface that is associated with this ComPtr.
ComPtr:: GetAddressOfComPtr::GetAddressOf 抓取ptr_資料成員的位址,其中包含這個所表示之介面的指標 ComPtrRetrieves the address of the ptr_ data member, which contains a pointer to the interface represented by this ComPtr.
ComPtr:: ReleaseAndGetAddressOfComPtr::ReleaseAndGetAddressOf 釋放與這個相關聯的介面, ComPtr 然後抓取ptr_資料成員的位址,其中包含已釋放之介面的指標。Releases the interface associated with this ComPtr and then retrieves the address of the ptr_ data member, which contains a pointer to the interface that was released.
ComPtr::ResetComPtr::Reset 釋放與這個相關聯的介面 ComPtr ,並傳回新的參考計數。Releases the interface associated with this ComPtr and returns the new reference count.
ComPtr:: SwapComPtr::Swap ComPtr使用由指定之管理的介面,交換目前所管理的介面 ComPtrExchanges the interface managed by the current ComPtr with the interface managed by the specified ComPtr.

保護方法Protected Methods

名稱Name 說明Description
ComPtr:: InternalAddRefComPtr::InternalAddRef 遞增與這個相關聯之介面的參考計數 ComPtrIncrements the reference count of the interface associated with this ComPtr.
ComPtr:: InternalReleaseComPtr::InternalRelease 在與此相關聯的介面上執行 COM 發行作業 ComPtrPerforms a COM Release operation on the interface associated with this ComPtr.

公用運算子Public Operators

名稱Name 說明Description
ComPtr:: operator&ComPtr::operator& 抓取目前的位址 ComPtrRetrieves the address of the current ComPtr.
ComPtr:: operator->ComPtr::operator-> 擷取目前範本參數所指定之類型的指標。Retrieves a pointer to the type specified by the current template parameter.
ComPtr:: operator =ComPtr::operator= 將值指派給目前的 ComPtrAssigns a value to the current ComPtr.
ComPtr:: operator = =ComPtr::operator== 表示兩個 ComPtr 物件是否相等。Indicates whether two ComPtr objects are equal.
ComPtr:: operator! =ComPtr::operator!= 指出兩個 ComPtr 物件是否不相等。Indicates whether two ComPtr objects aren't equal.
ComPtr:: operator Microsoft:: WRL::D etails:: BoolTypeComPtr::operator Microsoft::WRL::Details::BoolType 指出是否 ComPtr 正在管理介面的物件存留期。Indicates whether a ComPtr is managing the object lifetime of an interface.

受保護的資料成員Protected Data Members

名稱Name 說明Description
ComPtr::p tr_ComPtr::ptr_ 包含與這個相關聯之介面的指標,並由這個所管理 ComPtrContains a pointer to the interface that is associated with, and managed by this ComPtr.

繼承階層架構Inheritance Hierarchy

ComPtr

需求Requirements

標頭: client.hHeader: client.h

命名空間: Microsoft::WRLNamespace: Microsoft::WRL

ComPtr:: ~ ComPtrComPtr::~ComPtr

將的實例 ComPtrDeinitializes an instance of ComPtr.

WRL_NOTHROW ~ComPtr();

ComPtr:: AsComPtr::As

傳回 ComPtr 物件,表示指定之範本參數所識別的介面。Returns a ComPtr object that represents the interface identified by the specified template parameter.

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

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

參數Parameters

UU
要由參數p表示的介面。The interface to be represented by parameter p.

p&idp
ComPtr物件,表示參數U所指定的介面。參數p不能參考目前的 ComPtr 物件。A ComPtr object that represents the interface specified by parameter U. Parameter p must not refer to the current ComPtr object.

備註Remarks

第一個範本是程式碼中應該使用的表單。The first template is the form that you should use in your code. 第二個範本是內部的協助程式特製化。The second template is an internal, helper specialization. 它支援 c + + 語言功能,例如auto類型推斷關鍵字。It supports C++ language features such as the auto type deduction keyword.

傳回值Return Value

如果作業成功,會傳送 S_OK;反之則傳送表示錯誤的 HRESULT 值。S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr:: AsIIDComPtr::AsIID

傳回 ComPtr 物件,表示指定之介面識別碼所識別的介面。Returns a ComPtr object that represents the interface identified by the specified interface ID.

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

參數Parameters

riidriid
介面識別碼。An interface ID.

p&idp
如果物件的識別碼等於riid的介面,則為riid參數所指定之介面的雙向間接指標。If the object has an interface whose ID equals riid, a doubly indirect pointer to the interface specified by the riid parameter. 否則為的指標 IUnknownOtherwise, a pointer to IUnknown.

傳回值Return Value

如果作業成功,會傳送 S_OK;反之則傳送表示錯誤的 HRESULT 值。S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr:: AsWeakComPtr::AsWeak

擷取目前物件的弱式參考。Retrieves a weak reference to the current object.

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

參數Parameters

pWeakRefpWeakRef
當此作業完成時,即為弱式參考物件的指標。When this operation completes, a pointer to a weak reference object.

傳回值Return Value

如果作業成功,會傳送 S_OK;反之則傳送表示錯誤的 HRESULT 值。S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr:: AttachComPtr::Attach

將這個 ComPtr 與目前範本類型參數所指定的介面類別型產生關聯。Associates this ComPtr with the interface type specified by the current template type parameter.

void Attach(
   _In_opt_ InterfaceType* other
);

參數Parameters

另一方面other
介面類別型。An interface type.

ComPtr:: ComPtrComPtr::ComPtr

初始化 ComPtr 類別的新執行個體。Initializes a new instance of the ComPtr class. 多載提供預設、複製、移動和轉換建構函式。Overloads provide default, copy, move, and conversion constructors.

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 *>
);

參數Parameters

UU
一個參數的類型。The type of the other parameter.

另一方面other
類型為U的物件。An object of type U.

傳回值Return Value

備註Remarks

第一個函式是預設的函數,它會隱含建立空的物件。The first constructor is the default constructor, which implicitly creates an empty object. 第二個函式會指定__nullptr,以明確建立空的物件。The second constructor specifies __nullptr, which explicitly creates an empty object.

第三個函式會從指標所指定的物件建立物件。The third constructor creates an object from the object specified by a pointer. ComPtr 現在擁有指向的記憶體,並維護它的參考計數。The ComPtr now owns the pointed-to memory and maintains a reference count to it.

第四個和第五個是複製的函式。The fourth and fifth constructors are copy constructors. 第五個函式會複製物件(如果它可轉換成目前的類型)。The fifth constructor copies an object if it's convertible to the current type.

第六和第七個函式是移動的函式。The sixth and seventh constructors are move constructors. 第七個函式會移動物件(如果它可轉換成目前的類型)。The seventh constructor moves an object if it's convertible to the current type.

ComPtr:: CopyToComPtr::CopyTo

將與這個相關聯的目前或指定的介面複製 ComPtr 到指定的指標。Copies the current or specified interface associated with this ComPtr to the specified pointer.

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;

參數Parameters

UU
類型名稱。A type name.

ptrptr
當此作業完成時,為要求之介面的指標。When this operation completes, a pointer to the requested interface.

riidriid
介面識別碼。An interface ID.

傳回值Return Value

如果成功,則 S_OK;否則,就是指出隱含作業失敗原因的 HRESULT QueryInterfaceS_OK if successful; otherwise, an HRESULT that indicates why the implicit QueryInterface operation failed.

備註Remarks

第一個函式會傳回與這個相關聯之介面的指標複本 ComPtrThe first function returns a copy of a pointer to the interface associated with this ComPtr. 此函式一律會傳回 S_OK。This function always returns S_OK.

第二個函式會 QueryInterface 在與這個相關聯的介面上執行作業, ComPtr 以用於riid參數所指定的介面。The second function performs a QueryInterface operation on the interface associated with this ComPtr for the interface specified by the riid parameter.

第三個函式會 QueryInterface ComPtr 針對U參數的基礎介面,在與此相關聯的介面上執行運算。The third function performs a QueryInterface operation on the interface associated with this ComPtr for the underlying interface of the U parameter.

ComPtr::D etachComPtr::Detach

解除這個 ComPtr 物件與它所代表之介面的交互。Disassociates this ComPtr object from the interface that it represents.

T* Detach();

傳回值Return Value

這個物件所表示之介面的指標 ComPtrA pointer to the interface that was represented by this ComPtr object.

ComPtr:: GetComPtr::Get

抓取與這個相關聯之介面的指標 ComPtrRetrieves a pointer to the interface that is associated with this ComPtr.

T* Get() const;

傳回值Return Value

與這個相關聯之介面的指標 ComPtrPointer to the interface that is associated with this ComPtr.

ComPtr:: GetAddressOfComPtr::GetAddressOf

抓取ptr_資料成員的位址,其中包含這個所表示之介面的指標 ComPtrRetrieves the address of the ptr_ data member, which contains a pointer to the interface represented by this ComPtr.

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

傳回值Return Value

變數的位址。The address of a variable.

ComPtr:: InternalAddRefComPtr::InternalAddRef

遞增與這個相關聯之介面的參考計數 ComPtrIncrements the reference count of the interface associated with this ComPtr.

void InternalAddRef() const;

備註Remarks

這個方法受到保護。This method is protected.

ComPtr:: InternalReleaseComPtr::InternalRelease

在與此相關聯的介面上執行 COM 發行作業 ComPtrPerforms a COM Release operation on the interface associated with this ComPtr.

unsigned long InternalRelease();

備註Remarks

這個方法受到保護。This method is protected.

ComPtr:: operator&ComPtr::operator&

釋放與這個物件相關聯的介面 ComPtr ,然後抓取物件的位址 ComPtrReleases the interface associated with this ComPtr object and then retrieves the address of the ComPtr object.

Details::ComPtrRef<WeakRef> operator&()

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

傳回值Return Value

對目前的弱式參考 ComPtrA weak reference to the current ComPtr.

備註Remarks

這個方法與ComPtr:: GetAddressOf不同之處在于,這個方法會釋放介面指標的參考。This method differs from ComPtr::GetAddressOf in that this method releases a reference to the interface pointer. ComPtr::GetAddressOf當您需要介面指標的位址,但不想釋放該介面時,請使用。Use ComPtr::GetAddressOf when you require the address of the interface pointer but don't want to release that interface.

ComPtr:: operator->ComPtr::operator->

擷取目前範本參數所指定之類型的指標。Retrieves a pointer to the type specified by the current template parameter.

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

傳回值Return Value

目前範本類型名稱所指定之類型的指標。Pointer to the type specified by the current template type name.

備註Remarks

此 helper 函式會移除使用 STDMETHOD 宏所造成的不必要額外負荷。This helper function removes unnecessary overhead caused by using the STDMETHOD macro. 此函式會建立 IUnknown 類型 private ,而不是 virtualThis function makes IUnknown types private instead of virtual.

ComPtr:: operator =ComPtr::operator=

將值指派給目前的 ComPtrAssigns a value to the current 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
);

參數Parameters

UU
類別。A class.

另一方面other
類型或另一個的指標、參考或右值參考 ComPtrA pointer, reference, or rvalue reference to a type or another ComPtr.

傳回值Return Value

目前的參考 ComPtrA reference to the current ComPtr.

備註Remarks

這個運算子的第一個版本會將空值指派給目前的 ComPtrThe first version of this operator assigns an empty value to the current ComPtr.

在第二個版本中,如果指派的介面指標與目前的 ComPtr 介面指標不同,則會將第二個介面指標指派給目前的 ComPtrIn the second version, if the assigning interface pointer isn't the same as the current ComPtr interface pointer, the second interface pointer is assigned to the current ComPtr.

在第三個版本中,指派介面指標會指派給目前的 ComPtrIn the third version, the assigning interface pointer is assigned to the current ComPtr.

在第四個版本中,如果指派值的介面指標與目前的 ComPtr 介面指標不相同,則會將第二個介面指標指派給目前的 ComPtrIn the fourth version, if the interface pointer of the assigning value isn't the same as the current ComPtr interface pointer, the second interface pointer is assigned to the current ComPtr.

第五個版本是複製運算子;的參考 ComPtr 會指派給目前的 ComPtrThe fifth version is a copy operator; a reference to a ComPtr is assigned to the current ComPtr.

第六個版本是使用 move 語義的複製運算子;ComPtr如果有任何類型是靜態轉換,然後指派給目前的,則為的右值參考 ComPtrThe sixth version is a copy operator that uses move semantics; an rvalue reference to a ComPtr if any type is static cast and then assigned to the current ComPtr.

第七個版本是使用 move 語義的複製運算子;ComPtr類型U的右值參考是靜態轉換,然後指派給目前的 ComPtrThe seventh version is a copy operator that uses move semantics; an rvalue reference to a ComPtr of type U is static cast then and assigned to the current ComPtr.

ComPtr:: operator = =ComPtr::operator==

表示兩個 ComPtr 物件是否相等。Indicates whether two ComPtr objects are equal.

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
);

參數Parameters

a
ComPtr 物件的參考。A reference to a ComPtr object.

位元組b
另一個物件的參考 ComPtrA reference to another ComPtr object.

傳回值Return Value

true 如果物件a等於物件b,第一個運算子會產生,否則為 falseThe first operator yields true if object a is equal to object b; otherwise, false.

第二個和第三個運算子會產生, true 如果物件a等於 nullptr ,則為,否則為 falseThe second and third operators yield true if object a is equal to nullptr; otherwise, false.

ComPtr:: operator! =ComPtr::operator!=

指出兩個 ComPtr 物件是否不相等。Indicates whether two ComPtr objects aren't equal.

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
);

參數Parameters

a
ComPtr 物件的參考。A reference to a ComPtr object.

位元組b
另一個物件的參考 ComPtrA reference to another ComPtr object.

傳回值Return Value

true 如果物件a不等於物件b,第一個運算子會產生,否則為 falseThe first operator yields true if object a is not equal to object b; otherwise, false.

第二個和第三個運算子 true 會產生,如果物件a不等於,則為 nullptr ,否則為 falseThe second and third operators yield true if object a is not equal to nullptr; otherwise, false.

ComPtr:: operator Microsoft:: WRL::D etails:: BoolTypeComPtr::operator Microsoft::WRL::Details::BoolType

指出是否 ComPtr 正在管理介面的物件存留期。Indicates whether a ComPtr is managing the object lifetime of an interface.

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

傳回值Return Value

如果介面與此相關聯,則為 ComPtr BoolStruct:: Member資料成員的位址,否則為 nullptrIf an interface is associated with this ComPtr, the address of the BoolStruct::Member data member; otherwise, nullptr.

ComPtr::p tr_ComPtr::ptr_

包含與這個相關聯之介面的指標,並由這個所管理 ComPtrContains a pointer to the interface that is associated with, and managed by this ComPtr.

InterfaceType *ptr_;

備註Remarks

ptr_是內部受保護的資料成員。ptr_ is an internal, protected data member.

ComPtr:: ReleaseAndGetAddressOfComPtr::ReleaseAndGetAddressOf

釋放與這個相關聯的介面, ComPtr 然後抓取ptr_資料成員的位址,其中包含已釋放之介面的指標。Releases the interface associated with this ComPtr and then retrieves the address of the ptr_ data member, which contains a pointer to the interface that was released.

T** ReleaseAndGetAddressOf();

傳回值Return Value

這個的ptr_資料成員的位址 ComPtrThe address of the ptr_ data member of this ComPtr.

ComPtr:: ResetComPtr::Reset

釋放與這個相關聯的介面 ComPtr ,並傳回新的參考計數。Releases the interface associated with this ComPtr and returns the new reference count.

unsigned long Reset();

傳回值Return Value

基礎介面剩餘的參考數目(如果有的話)。The number of references remaining to the underlying interface, if any.

ComPtr:: SwapComPtr::Swap

ComPtr使用由指定之管理的介面,交換目前所管理的介面 ComPtrExchanges the interface managed by the current ComPtr with the interface managed by the specified ComPtr.

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

參數Parameters

rr
ComPtrA ComPtr.