шаблон структуры winrt::com_ptr (C++/WinRT)

Статья
08/17/2024

Шаблон интеллектуального указателя COM со ссылкой. com_ptr представляет указатель на тип реализации интерфейса или класса среды выполнения, указанный параметром шаблона. Он автоматически управляет счетчиком ссылок для своего целевого объекта через частный необработанный указатель.

Синтаксис

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 function	Возвращает запрошенный интерфейс, если он поддерживается. Бросает, если это не так.
com_ptr::attach function	Подключается к необработанной указателю, которому принадлежит ссылка на целевой объект; Дополнительная ссылка не добавляется.
com_ptr::capture function	Вызывает указанную функцию или метод (автоматически вызывая winrt::check_hresult на нем), и записывает указатель интерфейса, который выводится из функции или метода в виде `void**`.
функция com_ptr::copy_from	Копируется из другого указателя. Уменьшает количество ссылок на любой указанный в данный момент интерфейсе или объекте, копирует необработанный параметр указателя и начинает управлять временем существования интерфейса или объекта, на который он указывает.
функция com_ptr::copy_to	Копируется в другой указатель из объекта com_ptr. Увеличивает количество ссылок на любой указанный в данный момент интерфейсе или объекте и копирует адрес памяти интерфейса или объекта в параметр.
функция com_ptr::d etach	Отсоединяется от указанного интерфейса или объекта без уменьшения количества ссылок, возможно, чтобы вернуть его вызывающему объекту.
com_ptr::get function	Возвращает базовый необработанный указатель, который необходимо передать в функцию.
com_ptr::p ut function	Возвращает адрес базового необработанного указателя; эта функция помогает вызывать методы (например, методы COM), возвращающие ссылки в качестве параметров с помощью указателя на указатель.
com_ptr::p ut_void function	Возвращает адрес базового необработанного указателя в качестве указателя на указатель на void; эта функция помогает вызывать методы (например, методы COM), возвращающие ссылки в качестве параметров из указателя на указатель на 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 параметров, чтобы они указывали на целевой объект друг друга.

Бесплатные операторы

Функция	Описание
оператор!= (оператор неравенства)	Возвращает значение, указывающее, относятся ли два параметра к разным целевым объектам.
оператор< (оператор меньше, чем оператор)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра раньше в памяти, чем второй параметр.
оператор <= (оператор меньше или равно)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра раньше в памяти, чем в том же расположении, что и второй параметр.
оператор == (оператор равенства)	Возвращает значение, указывающее, относятся ли два параметра к одному интерфейсу и /или объекту.
оператор> (оператор больше)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра позже в памяти, чем второй параметр.
оператор >= (оператор больше или равно)	Возвращает значение, указывающее, происходит ли целевой объект первого параметра позже в памяти, чем в том же расположении, что и второй параметр.

конструктор 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 параметра необходимо преобразовать в объектаT com_ptr.

com_ptr::as function

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

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

Синтаксис

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 Тип метода A.

typename Args ноль или несколько типов аргументов.

Параметры

function объект функции типа F.

p Указатель на объект типа O.

object winrt::com_ptr типа O.

method метод A (реализован 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), возвращающие ссылки в качестве параметров с помощью указателя на указатель. Если объект com_ptr уже имеет целевой объект, назначьте nullptr объекту com_ptr перед вызовом этой функции, в противном случае функция будет утверждать.

Синтаксис

T** put() noexcept;

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

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

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

Возвращает адрес базового необработанного указателя в качестве указателя на указатель на void; эта функция помогает вызывать методы (например, методы COM), возвращающие ссылки в качестве параметров из указателя на указатель на void. Если объект com_ptr уже имеет целевой объект, назначьте nullptr объекту com_ptr перед вызовом этой функции, в противном случае функция будет утверждать.

Синтаксис

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

Версия 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 параметра необходимо преобразовать в объектаT com_ptr.

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

Ссылка на объект com_ptr.

com_ptr::operator-> (оператор со стрелкой)

Чтобы предоставить доступ к методам указанного интерфейса или объекта, возвращает базовый необработанный указатель. Вы не можете вызывать AddRef или выпуска на возвращаемом указателе, но вы можете вызвать 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.

оператор<= (оператор меньше или равно)

Возвращает значение, указывающее, происходит ли целевой объект первого параметра раньше в памяти, чем в том же расположении, что и второй параметр.

Синтаксис

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.

оператор> (оператор больше)

Возвращает значение, указывающее, происходит ли целевой объект первого параметра позже в памяти, чем второй параметр.

Синтаксис

template <typename T> bool operator>(winrt::com_ptr<T> const& left, 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.

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

Переключает содержимое двух com_ptr параметров, чтобы они указывали на целевой объект друг друга.

Синтаксис

void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;

Параметры

left right значение com_ptr, указатель которого на взаимоключение с другим параметром.

См. также

пространства имен winrt
использовать API с C++/WinRT

Поделиться через

шаблон структуры winrt::com_ptr (C++/WinRT)

Синтаксис

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

Требования

Псевдонимы типов элементов

Конструкторы

Функции-члены

Операторы-члены

Бесплатные функции

Бесплатные операторы

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

Синтаксис

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

Параметры

com_ptr::as function

Синтаксис

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

Параметры

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

функция 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!= (оператор неравенства)

Синтаксис

Параметры

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

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

Синтаксис