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

Статья
06/10/2023

Шаблон интеллектуального указателя 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	Возвращает запрошенный интерфейс, если он поддерживается. Выдает, если это не так.
Функция 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-методы), возвращающие ссылки в качестве параметров выхода с помощью указателя на 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-> (оператор arrow)	Чтобы предоставить доступ к интерфейсу или методам объекта, на который указывает ссылка, возвращает базовый необработанный указатель.

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

Функция	Описание
Функция attach_abi	Присоединяет объект com_ptr к необработанному указателю, которому принадлежит ссылка на его целевой объект; дополнительная ссылка не добавляется.
Функция detach_abi	Отсоединяет объект com_ptr от его необработанного интерфейса без уменьшения количества ссылок, возможно, чтобы вернуть его вызывающему объекту.
Функция swap	Переключает содержимое двух параметров 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 параметра должен быть преобразован в T объекта com_ptr.

Функция 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.

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

Синтаксис

T** put() noexcept;

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

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

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

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

Синтаксис

void** put_void() noexcept;

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

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

Функция com_ptr::try_as

Возвращает запрошенный интерфейс, если он поддерживается. Возвращает nullptr ( auto-returning overload) или false ( bool-returning overload), если это не так. Эта функция полезна, если вы хотите запросить интерфейс, который не нужно передавать обратно вызывающей стороне.

Синтаксис

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-> (оператор arrow)

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

Параметры

leftrightЗначение com_ptr, адрес памяти которого целевого объекта сравнивает с адресом другого параметра.

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

true Значение , если два параметра указывают на разные целевые объекты; в противном случае — falseзначение .

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

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

Синтаксис

template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Параметры

leftrightЗначение com_ptr, адрес памяти которого целевого объекта сравнивает с адресом другого параметра.

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

true Значение , если адрес памяти целевого параметра первого параметра меньше адреса памяти второго параметра, в противном случае — falseзначение .

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

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

Синтаксис

template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Параметры

leftrightЗначение 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;

Параметры

leftrightЗначение com_ptr, адрес памяти которого целевого объекта сравнивает с адресом другого параметра.

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

true Значение , если два параметра указывают на один и тот же целевой объект; в противном случае — falseзначение .

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

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

Синтаксис

template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Параметры

leftrightЗначение com_ptr, адрес памяти которого целевого объекта сравнивает с адресом другого параметра.

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

true Значение , если адрес памяти целевого параметра первого параметра больше адреса памяти второго параметра, в противном случае — falseзначение .

operator>= (оператор больше или равно)

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

Синтаксис

template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Параметры

leftrightЗначение com_ptr, адрес памяти которого целевого объекта сравнивает с адресом другого параметра.

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

true Значение , если адрес памяти целевого параметра первого параметра больше или равен адресу памяти второго параметра, в противном случае — falseзначение .

Функция swap

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

Синтаксис

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

Параметры

leftrightЗначение 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-> (оператор arrow)

Синтаксис

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

Функция attach_abi

Синтаксис

Параметры

Функция detach_abi

Синтаксис

Параметры

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

operator!= (оператор неравенства)

Синтаксис

Параметры

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

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

Синтаксис

Параметры