winrt：：com_ptr結構範本 （C++/WinRT）
參考計數的 COM 智慧型手機指標範本。 com_ptr 代表樣板參數所指定之介面或運行時間類別實作類型的指標。 它會透過私人原始指標自動管理其目標的參考計數。
語法
template <typename T>
struct com_ptr
範本參數
typename T 介面或運行時間類別實作類型，指標是由 com_ptr表示。 這是智慧型指標的目標類型。
要求
最低支援的 SDK： Windows SDK 10.0.17134.0 版（Windows 10 版本 1803）
Namespace： winrt
標頭： %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h （預設包含）
成員類型別名
| 別名名稱 | 類型 |
|---|---|
| com_ptr：：type | 實作定義的 typename T 樣板參數表示法的同義字。 |
構造 函數
| 構造 函數 | 描述 |
|---|---|
| com_ptr：：com_ptr建構函式 | 使用輸入數據的複本或移動，初始化 com_ptr 結構的新實例。 |
成員函式
| 功能 | 描述 |
|---|---|
| com_ptr：：as 函式 | 如果支援，則傳回要求的介面。 如果不是，則會擲回 。 |
| com_ptr：：attach 函式 | 附加至擁有其目標參考的原始指標;不會新增其他參考。 |
| com_ptr：：capture 函式 | 呼叫指定的函式或方法（在函式或方法上自動呼叫 winrt：：check_hresult），並以 void**擷取函式或方法輸出的介面指標。 |
| com_ptr：：copy_from 函式 | 從另一個指標複製。 遞減目前參考之介面或對象的參考計數、複製原始指標參數，並開始管理其所指向之介面或物件的存留期。 |
| com_ptr：：copy_to函式 | 從 com_ptr 物件複製到另一個指標。 在任何目前參考的介面或物件上遞增參考計數，並將該介面或物件的記憶體位址複製到 參數中。 |
| com_ptr：:d etach 函式 | 從參考的介面或對象中斷連結，而不遞減參考計數，或許可將它傳回給呼叫端。 |
| com_ptr：：get 函式 | 如果您需要將它傳遞給函式，傳回基礎原始指標。 |
| com_ptr：:p ut 函式 | 傳回基礎原始指標的位址;此函式可協助您呼叫方法（例如 COM 方法），透過指標的指標傳回作為 out 參數的參考。 |
| com_ptr：:p ut_void 函式 | 傳回基礎原始指標的位址，做為 void指標的指標;此函式可協助您呼叫方法（例如 COM 方法），透過指向 void指標的指標傳回作為 out 參數的參考。 |
| com_ptr：：try_as函式 | 如果支援，則傳回要求的介面。 如果不是 ，則傳回 nullptr或 false。 |
| com_ptr：：try_capture 函式 |
com_ptr：：capture 版本不會在失敗時擲回，但如果成功，則會傳回 true，否則傳回 false。 |
成員運算子
| 算子 | 描述 |
|---|---|
| com_ptr：：operator bool | 檢查智慧型指標是否參考介面或物件。 |
| com_ptr：：operator* （間接運算符） | 傳回 com_ptr目標的參考，以便您將它傳遞至預期目標型別參考的函式 T。 |
| com_ptr：：operator= （指派運算符） | 將值指派給 com_ptr 物件。 |
| com_ptr：：operator-> （箭頭運算子） | 若要能夠存取參考的介面或物件的方法，請傳回基礎原始指標。 |
免費函式
| 功能 | 描述 |
|---|---|
| attach_abi 函式 | 將 com_ptr 物件附加至擁有其目標參考的原始指標;不會新增其他參考。 |
| detach_abi 函式 | 將 com_ptr 物件與原始介面中斷連結，而不遞減參考計數，或許可將它傳回給呼叫端。 |
| 交換函式 | 交換兩個 com_ptr 參數的內容，使其指向彼此的目標。 |
免費運算子
| 功能 | 描述 |
|---|---|
| 運算子！= （不等運算子） | 傳回值，指出這兩個參數是否參考不同的目標。 |
| 運算子<（小於運算符） | 傳回值，指出第一個參數的目標是否比第二個參數早於記憶體中。 |
| 運算子<= （小於或等於運算子） | 傳回值，指出第一個參數的目標發生於記憶體中早於第二個參數的相同位置。 |
| operator== | 傳回值，指出兩個參數是否參考相同的介面和/或物件。 |
| 運算子> （大於運算符） | 傳回值，指出第一個參數的目標是否晚於第二個參數的記憶體中發生。 |
| 運算子>= （大於或等於運算子） | 傳回值，指出第一個參數的目標是否晚於記憶體中發生，或是在與第二個參數相同的位置發生。 |
com_ptr：：com_ptr建構函式
使用輸入數據的複本或移動，初始化 com_ptr 結構的新實例。
void* 建構函式會採用 T*，並假設擁有權。
winrt：：take_ownership_from_abi_t 是一種標記類型，可讓明確 釋放此指標的責任現在已轉移到com_ptr。 refcount 不一定是 1;只是說責任正在轉移。
語法
com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) noexcept;
com_ptr(void* ptr, winrt::take_ownership_from_abi_t) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U> const& other) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U>&& other) noexcept;
範本參數
typename U 輸入智慧型手機指標所指向的目標類型。
參數
other 另一個初始化 com_ptr 物件的 com_ptr。 參數的 T 必須可轉換成 com_ptr 物件的 T。
com_ptr：：as 函式
如果支援，則傳回要求的介面。 如果不是，則會擲回 。 如果您想要查詢不需要傳回給呼叫端的介面，此函式會很有用。
如需程式代碼範例，請參閱主題中 具現化和傳回投影類型和介面一節和其他章節。
語法
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
範本參數
typename To 所要求介面的類型。
參數
to 要接收要求介面之值的參考。
傳回值
com_ptr 參考要求的介面，或要求介面的強型別智慧指標（由C++/WinRT 或第三方宣告）。
com_ptr：：attach 函式
附加至擁有其目標參考的原始指標;不會新增其他參考。 如有需要，您可以使用此函式來聯合參考。
語法
void attach(T* value) noexcept;
參數
value 擁有其目標參考的原始指標。
com_ptr：：capture 函式
呼叫指定的函式或方法（在函式或方法上自動呼叫 winrt：：check_hresult），並以 void**擷取函式或方法輸出的介面指標。
另請參閱 winrt：：capture 函式範本。
語法
template <typename F, typename...Args>
void capture(F function, Args&&...args);
template <typename O, typename M, typename...Args>
void capture(O* p, M method, Args&& ...args);
template <typename O, typename M, typename...Args>
void capture(winrt::com_ptr<O> const& object, M method, Args&&...args);
範本參數
typename F 函式物件類型，例如免費函式，或 std：：function。
typename O 介面類型。
typename M 方法類型。
typename Args 零個或多個自變數類型。
參數
function 類型為 F的函式物件。
p 類型 O物件的指標。
object 類型為 Owinrt：：com_ptr 。
method 類型為 M的方法（由 O實作）。
args 類型為零或多個自變數 Args。
言論
-
capture(F function, Args&&...args)多載會叫用函式物件。 -
capture(O* p, M method, Args&& ...args)多載會在指標上叫用 方法。 -
capture(winrt::com_ptr<O> const& object, M method, Args&&...args)多載會在物件上叫用 方法。
所有多載都會傳遞您所提供的任何其他自變數（至叫用者）。 所有多載也會傳遞這類叫用所需的兩個額外自變數，特別是 REFIID（winrt：：com_ptr的目標標識符），以及 void** （winrt：：com_ptr目標指標的位址）。
例
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
com_ptr：：copy_from 函式
從另一個指標複製。 遞減目前參考之介面或對象的參考計數、複製原始指標參數，並開始管理其所指向之介面或物件的存留期。
語法
void copy_from(T* other) noexcept;
參數
other 目標的原始指標，其存留期應該由 com_ptr 物件管理。
com_ptr：：copy_to 函式
從 com_ptr 物件複製到另一個指標。 在任何目前參考的介面或物件上遞增參考計數，並將該介面或物件的記憶體位址複製到 參數中。 此函式可讓您在未呼叫 queryInterface
語法
void copy_to(T** other) const noexcept;
參數
other 原始指標的位址;將指標複製到 com_ptr 對象目標的目標。
com_ptr：:d etach 函式
從參考的介面或對象中斷連結，而不遞減參考計數，或許可將它傳回給呼叫端。
語法
T* detach() noexcept;
傳回值
com_ptr 物件所參考之介面或物件的指標。
com_ptr：：get 函式
如果您需要將它傳遞給函式，傳回基礎原始指標。 您可以在傳回的指標上呼叫 AddRef、Release或 QueryInterface。
語法
T* get() const noexcept;
傳回值
com_ptr 物件所參考之介面或物件的指標。
com_ptr：:p ut 函式
傳回基礎原始指標的位址;此函式可協助您呼叫方法（例如 COM 方法），透過指標的指標傳回作為 out 參數的參考。 如果 com_ptr 對象已經有目標，則在呼叫此函式之前，將 nullptr 指派給 com_ptr 對象，否則函式會判斷提示。
語法
T** put() noexcept;
傳回值
基礎原始指標的位址。
com_ptr：:p ut_void 函式
傳回基礎原始指標的位址，做為 void指標的指標;此函式可協助您呼叫方法（例如 COM 方法），透過指向 void指標的指標傳回作為 out 參數的參考。 如果 com_ptr 對象已經有目標，則在呼叫此函式之前，將 nullptr 指派給 com_ptr 對象，否則函式會判斷提示。
語法
void** put_void() noexcept;
傳回值
基礎原始指標的位址，做為 void 指標的指標，。
com_ptr：：try_as 函式
如果支援，則傳回要求的介面。 傳回 nullptr（傳回多載 auto），如果不是，則傳回 false（bool傳回多載）。 如果您想要查詢不需要傳回給呼叫端的介面，此函式會很有用。
語法
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
範本參數
typename To 所要求介面的類型。
參數
to 要接收要求介面之值的參考。
傳回值
com_ptr 參考要求的介面，或要求介面的強型別智慧型手機別指標（由C++/WinRT 或第三方宣告），如果支援要求的介面，則為 nullptr（auto傳回多載），或 false（bool-returning 多載）。
com_ptr：：try_capture 函式
com_ptr：：capture 版本不會在失敗時擲回，但如果成功，則會傳回 true，否則傳回 false。
另請參閱 winrt：：try_capture 函式範本。
com_ptr：：operator bool
檢查智慧型指標是否參考介面或物件。 如果智慧型手機未參考介面或物件，則其邏輯為 Null;否則，它邏輯上不是 Null。
語法
explicit operator bool() const noexcept;
傳回值
如果智慧型手機參考介面或物件（邏輯上不是 null），則 true 否則為 false（邏輯為 null）。
com_ptr：：operator* （間接運算符）
傳回 com_ptr目標的參考，以便您將它傳遞至預期目標型別參考的函式 T。
語法
T& operator*() const noexcept;
傳回值
com_ptr目標的參考。
com_ptr：：operator= （指派運算符）
將值指派給 com_ptr 物件。
語法
winrt::com_ptr& operator=(winrt::com_ptr const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U> const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U>&& other) noexcept;
範本參數
typename U 所指派值所指向的類型。
參數
other 要指派給 com_ptr 物件的 com_ptr 值。 參數的 T 必須可轉換成 com_ptr 物件的 T。
傳回值
com_ptr 對象的參考。
com_ptr：：operator-> （箭頭運算子）
若要能夠存取參考的介面或物件的方法，請傳回基礎原始指標。 您可能不會在傳回的指標上呼叫 AddRef 或 Release，但您可以呼叫 QueryInterface。
語法
auto operator->() const noexcept;
傳回值
com_ptr 物件所參考之介面或物件的指標。
attach_abi函式
將 com_ptr 物件附加至擁有其目標參考的原始指標;不會新增其他參考。 如有需要，您可以使用此函式來聯合參考。
語法
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
參數
object 要運作的 com_ptr 物件。
value 擁有其目標參考的原始指標。
detach_abi函式
將 com_ptr 物件與原始介面中斷連結，而不遞減參考計數，或許可將它傳回給呼叫端。
語法
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
參數
object 要運作的 com_ptr 物件。
傳回值
com_ptr 對象所參考之原始介面的指標。
operator！= （不等運算符）
傳回值，指出這兩個參數是否參考不同的目標。
語法
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator!=(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果兩個參數指向不同的目標，則 true，否則 false。
運算子< （小於運算子）
傳回值，指出第一個參數的目標是否比第二個參數早於記憶體中。
語法
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果第一個參數的目標記憶體位址小於第二個參數的記憶體位址，則 true，否則 false。
operator<= （less-than-or-equal-to operator）
傳回值，指出第一個參數的目標發生於記憶體中早於第二個參數的相同位置。
語法
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果第一個參數的目標記憶體位址小於或等於第二個參數的記憶體位址，則 true，否則 false。
operator== （等號運算符）
傳回值，指出兩個參數是否參考相同的介面和/或物件。
語法
template <typename T> bool operator==(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator==(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果兩個參數指向相同的目標，則 true，否則 false。
operator> （大於運算子）
傳回值，指出第一個參數的目標是否晚於第二個參數的記憶體中發生。
語法
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果第一個參數的目標記憶體位址大於第二個參數的記憶體位址，則 true 否則 false。
operator>= （大於或等於運算符）
傳回值，指出第一個參數的目標是否晚於記憶體中發生，或是在與第二個參數相同的位置發生。
語法
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
left
right 目標記憶體位址要與其他參數相比較的 com_ptr 值。
傳回值
如果第一個參數的目標記憶體位址大於或等於第二個參數的記憶體位址，則 true，否則 false。
swap 函式
交換兩個 com_ptr 參數的內容，使其指向彼此的目標。
語法
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
參數
left
right
com_ptr 值，其指向彼此交換的指標與其他參數的指標。
另請參閱
- winrt 命名空間
- 使用具有 C++/WinRT 的 API