шаблон структуры 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::тип	Синоним представления параметра шаблона, `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), возвращающие ссылки в качестве параметров с помощью указателя на указатель.
com_ptr::p ut_void функция	Возвращает адрес базового исходного указателя в виде указателя на void; Эта функция помогает вызывать методы (например, методы COM), которые возвращают ссылки в качестве параметров out через указатель на void.
Функция 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!= (оператор неравенства)	Возвращает значение, указывающее, относятся ли два параметра к разным целевым объектам.
operator< (оператор меньше)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра раньше в памяти, чем второй параметр.
operator<= (оператор меньше-или-равно-кому)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра раньше в памяти, чем в том же расположении, что и второй параметр.
operator== (оператор равенства)	Возвращает значение, указывающее, относятся ли два параметра к одному интерфейсу и /или объекту.
operator> (оператор больше)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра позже в памяти, чем второй параметр.
operator>= (оператор больше, чем или равно)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра позже в памяти, чем в том же расположении, что и второй параметр.

конструктор com_ptr::com_ptr

Инициализирует новый экземпляр структуры com_ptr , опционально с копией или перемещением входных данных.

Конструктор void* берет T* и становится владельцем. winrt::take_ownership_from_abi_t - это тип маркера, который делает явным , что ответственность за освобождение этого указателя теперь передается com_ptr. Ссылка не должна быть ровно 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 параметра должен быть преобразуемым в Tt объекта com_ptr.

Функция com_ptr::as

Возвращает запрошенный интерфейс, если он поддерживается. Бросает, если это не так. Эта функция полезна, если вы хотите запросить интерфейс, который не нужно передавать вызывающей стороне.

Примеры кода см. в разделе Создание экземпляров и возврат проецируемых типов и интерфейсов, а также в других разделах этого раздела.

Синтаксис

template <typename To> auto as() const;
template <typename To> void as(To& to) const;

Параметры шаблона

typename To Тип запрашиваемого интерфейса.

Параметры

to Ссылка на значение для получения запрошенного интерфейса.

Возвращаемое значение

T 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 A winrt::com_ptr типа O.

method Метод (реализуемый с помощью O) типа M.

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), которые возвращают ссылки в качестве выходных параметров через указатель на указатель.

Синтаксис

T** put() noexcept;

Возвращаемое значение

Адрес базового необработанного указателя.

функция com_ptr::p ut_void

Возвращает адрес базового исходного указателя в виде указателя на void для передачи его функции (например, методам COM), которая возвращает ссылки в качестве параметров out через указатель на указатель на void.

Синтаксис

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перегрузочная версия -returning) или 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;

Возвращаемое значение

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 параметра должен быть преобразуемым в Tt объекта com_ptr.

Возвращаемое значение

Ссылка на объект 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.

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.

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.

Функция переключения

Меняет местами содержимое двух 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!= (оператор неравенства)

Синтаксис

Параметры

Возвращаемое значение

operator< (оператор меньше)

Синтаксис