winrt：：com_ptr結構範本 (C++/WinRT)
參考計數 COM 智慧型指標範本。 com_ptr 代表樣板參數所指定之介面或執行時間類別實作類型的指標。 它會透過私用原始指標自動管理其目標的參考計數。
Syntax
template <typename T>
struct com_ptr
範本參數
typename T 介面或執行時間類別實作類型，其指標是由 com_ptr表示。 這是智慧型指標的目標型別。
規格需求
最低支援的 SDK：Windows SDK 版本 10.0.17134.0 (Windows 10版本 1803)
命名空間： 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版本，不會在失敗時擲回，但如果成功或 false 未成功，則會傳回 true 。 |
成員運算子
| 運算子 | 描述 |
|---|---|
| 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 物件與其原始介面中斷連結，而不會遞減參考計數，或許可將它傳回給呼叫端。 |
| swap 函式 | 交換兩 個com_ptr 參數的內容，使其指向彼此的目標。 |
免費運算子
| 函式 | 描述 |
|---|---|
| operator！= (不等比較運算子) | 傳回值，指出兩個參數是否參考不同的目標。 |
| 運算子 < (小於運算子) | 傳回值，指出第一個參數的目標是否早于記憶體中，而不是第二個參數的目標。 |
| operator < = (小於或等於運算子) | 傳回值，指出第一個參數的目標是否早于記憶體中發生，或是在與第二個參數相同的位置發生。 |
| operator== (等號比較運算子) | 傳回值，指出兩個參數是否參考相同的介面和/或 物件。 |
| 運算子 > (大於運算子) | 傳回值，指出第一個參數的目標是否晚于記憶體中，而不是第二個參數的目標。 |
| operator > = (大於或等於運算子) | 傳回值，指出第一個參數的目標是否晚于記憶體或與第二個參數相同的位置。 |
com_ptr：：com_ptr 建構函式
使用輸入資料的複本或移動，初始化 com_ptr 結構的新實例。
建 void* 構函式會採用 T*，並假設擁有權。 winrt：：take_ownership_from_abi_t 是一種標記類型，可明確 負責釋放此指標現在會傳送至com_ptr。 refcount 不一定是 1;這只是說責任正在轉移。
Syntax
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 函式
如果支援，則傳回要求的介面。 如果不是，則會擲回 。 如果您想要查詢不需要傳回給呼叫端的介面，此函式會很有用。
如需程式碼範例，請參閱具 現化和傳回投影類型和介面一節，以及該主題中的其他章節。
Syntax
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 函式範本。
Syntax
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 函式物件類型，例如 free 函式或 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 函式
從參考的介面或物件中斷連結，而不遞減參考計數，或許可以將其傳回給呼叫端。
Syntax
T* detach() noexcept;
傳回值
com_ptr物件所參考之介面或物件的指標。
com_ptr：：get 函式
傳回基礎原始指標，您應該必須將它傳遞至函式。 您可以在傳回的指標上呼叫 AddRef、 Release或 QueryInterface 。
Syntax
T* get() const noexcept;
傳回值
com_ptr物件所參考之介面或物件的指標。
com_ptr：:p ut 函式
傳回基礎原始指標的位址;此函式可協助您呼叫方法 (，例如 COM 方法) ，透過指標指標將參考傳回為 out 參數。 如果 com_ptr 物件已經有目標，則在呼叫此函式之前，指派 nullptr 給 com_ptr 物件，否則函式會判斷提示。
Syntax
T** put() noexcept;
傳回值
基礎原始指標的位址。
com_ptr：:p ut_void 函式
傳回基礎原始指標的位址，做為 void指標的指標;此函式可協助您呼叫方法 (，例如 COM 方法) 透過 void指標的指標傳回 out 參數的參考。 如果 com_ptr 物件已經有目標，則在呼叫此函式之前，指派 nullptr 給 com_ptr 物件，否則函式會判斷提示。
Syntax
void** put_void() noexcept;
傳回值
基礎原始指標的位址，做為 void指標的指標。
com_ptr：：try_as 函式
如果支援，則傳回要求的介面。 nullptr傳回 (auto 傳回多載) ，如果沒有，則 falsebool 傳回 (傳回多載) 。 如果您想要查詢不需要傳回給呼叫端的介面，此函式會很有用。
Syntax
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 傳回多載) 。
com_ptr：：try_capture 函式
在失敗時不會擲回的 com_ptr：：capture版本，但如果成功或 false 未成功，則會傳回 。 true
另請參閱 winrt：：try_capture函式範本。
com_ptr：：operator bool
檢查智慧型指標是否參考介面或物件。 如果智慧型指標未參考介面或物件，則會以邏輯方式為 Null;否則，其邏輯上不是 Null。
Syntax
explicit operator bool() const noexcept;
傳回值
true 如果智慧型指標參考介面或物件 (邏輯上不是 null) ，則為 ，否則 false (邏輯上為 null) 。
com_ptr：：operator* (間接運算子)
傳回 com_ptr目標的參考，以便您將它傳遞至預期目標型別 T參考的函式。
Syntax
T& operator*() const noexcept;
傳回值
com_ptr目標的參考。
com_ptr：：operator= (指派運算子)
將值指派給 com_ptr 物件。
Syntax
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。
Syntax
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;
參數
leftrightcom_ptr值，其目標記憶體位址要與其他參數的記憶體位址進行比較。
傳回值
true 如果兩個參數指向不同的目標，則為 ，否則 false 為 。
運算子 < (小於運算子)
傳回值，指出第一個參數的目標是否早于記憶體中，而不是第二個參數的目標。
語法
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
leftrightcom_ptr值，其目標記憶體位址要與其他參數的記憶體位址進行比較。
傳回值
true 如果第一個參數的目標記憶體位址小於第二個參數的記憶體位址，則為 ，否則 false 為 。
operator < = (小於或等於運算子)
傳回值，指出第一個參數的目標是否早于記憶體中發生，或是在與第二個參數相同的位置發生。
語法
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
leftrightcom_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;
參數
leftrightcom_ptr值，其目標記憶體位址要與其他參數的記憶體位址進行比較。
傳回值
true 如果兩個參數指向相同的目標，則為 ，否則 false 為 。
運算子 > (大於運算子)
傳回值，指出第一個參數的目標是否晚于記憶體中，而不是第二個參數的目標。
語法
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
leftrightcom_ptr值，其目標記憶體位址要與其他參數的記憶體位址進行比較。
傳回值
true 如果第一個參數的目標記憶體位址大於第二個參數的記憶體位址，則為 ，否則 false 為 。
operator > = (大於或等於運算子)
傳回值，指出第一個參數的目標是否晚于記憶體或與第二個參數相同的位置。
語法
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
參數
leftrightcom_ptr值，其目標記憶體位址要與其他參數的記憶體位址進行比較。
傳回值
true 如果第一個參數的目標記憶體位址大於或等於第二個參數的記憶體位址，則為 ，否則 false 為 。
swap 函式
交換兩 個com_ptr 參數的內容，使其指向彼此的目標。
語法
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
參數
leftrightcom_ptr值，其指標會與其他參數的指標相互交換。
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應