winrt：：com_ptr結構範本（C++/WinRT）

2025-05-08

參考計數的 COM 智慧型手機指標範本。 com_ptr 表示指向template參數指定的介面或運行時類實現類型的指標。它會透過私人原始指標自動管理其目標的參考計數。

語法

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 函數	如果支援，則傳回要求的介面。傳回，否則`false`返回`nullptr`或。
com_ptr：：try_capture 函數	不引發失敗但返回成功或`false`失敗的 com_ptr：：capture 版本。`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== （相等運算符）	傳回值，指出兩個參數是否參考相同的介面和/或物件。
運算子> （greater-than 運算子）	傳回值，指出第一個參數的目標是否晚於第二個參數的記憶體中發生。
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 函數物件類型，例如free函數或 std：：function。

typename O 介面類型。

typename M 方法類型。

typename Args 零個或多個參數類型。

參數

function 類型 F為的函數物件。

p 指向類型的 O物件的指標。

object類型為O的 winrt：：com_ptr 。

method類型M為的方法（由 O實現）。

args 零個或多個類型的 Args參數。

言論

capture(F function, Args&&...args)重載調用 function 物件。
capture(O* p, M method, Args&& ...args)重載調用指標上的方法。
capture(winrt::com_ptr<O> const& object, M method, Args&&...args)重載調用物件上的方法。

所有多載都會傳遞您所提供的任何其他自變數（至叫用者）。所有重載還傳遞此類調用所需的兩個附加參數，具體而言， REFIID （ winrt：：com_ptr 目標的 ID）和 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 參數返回。

語法

T** put() noexcept;

傳回值

基礎原始指標的位址。

com_ptr：:p ut_void 函式

將基礎原始指標的位址作為指向 void 的指標的指標返回，以將其傳遞給函數（，例如 COM 方法），該函數通過指向 void 的指標將引用作為 out 參數傳回。

語法

void** put_void() noexcept;

傳回值

基礎原始指標的位址，作為指向 void 的指標的指標。

com_ptr：：try_as 函式

如果支援，則傳回要求的介面。返回 nullptr （ auto-returning 重載）或 false （ bool-returning 重載）（如果不是）。如果您想要查詢不需要傳回給呼叫端的介面，此函式會很有用。

語法

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-returning 重載）或 false （ bool-returning 重載）。

com_ptr：：try_capture 函式

不引發失敗但返回成功或false失敗的 com_ptr：：capture 版本。true

另請參閱 winrt：：try_capture 函數範本。

com_ptr：：operator bool

檢查智慧型指標是否參考介面或物件。如果智慧型手機未參考介面或物件，則其邏輯為 Null;否則，它邏輯上不是 Null。

語法

explicit operator bool() const noexcept;

傳回值

true 如果智慧指標引用介面或對象（邏輯上不為 null），否則 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 如果兩個參數指向不同的 target，則 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<=（小於或等於運算符）

傳回值，指出第一個參數的目標發生於記憶體中早於第二個參數的相同位置。

語法

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。

運算子> （greater-than 運算子）

傳回值，指出第一個參數的目標是否晚於第二個參數的記憶體中發生。

語法

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：：com_ptr結構範本 （C++/WinRT）

語法

範本參數

要求

成員類型別名

構造 函數

成員函式

成員運算子

免費函式

免費運算子

com_ptr：：com_ptr建構函式

語法

範本參數

參數

com_ptr：：as 函式

語法

範本參數

參數

傳回值

com_ptr：：attach 函式

語法

參數

com_ptr：：capture 函式

語法

範本參數

參數

言論

例

com_ptr：：copy_from 函式

語法

參數

com_ptr：：copy_to 函式

語法

參數

com_ptr：:d etach 函式

語法

傳回值

com_ptr：：get 函式

語法

傳回值

com_ptr：:p ut 函式

語法

傳回值

com_ptr：:p ut_void 函式

語法

傳回值

com_ptr：：try_as 函式

語法

範本參數

參數

傳回值

com_ptr：：try_capture 函式

com_ptr：：operator bool

語法

傳回值

com_ptr：：operator* （間接運算符）

語法

傳回值

com_ptr：：operator= （指派運算符）

語法

範本參數

參數

傳回值

com_ptr：：operator-> （箭頭運算符）

語法

傳回值

attach_abi函式

語法

參數

detach_abi函式

語法

參數

傳回值

operator！= （不等運算符）

語法

參數

傳回值

運算子< （小於運算子）

語法

winrt：：com_ptr結構範本（C++/WinRT）

構造函數