Plantilla de estructura winrt::com_ptr (C++/WinRT)

Plantilla de puntero inteligente COM con recuento de referencias. com_ptr representa un puntero al tipo de implementación de la interfaz o clase en tiempo de ejecución especificado por el parámetro template. Administra automáticamente el recuento de referencias de su destino a través de un puntero sin procesar privado.

Sintaxis

template <typename T>
struct com_ptr

Parámetros de plantilla

typename T Interfaz, o tipo de implementación de clase en tiempo de ejecución, cuyo puntero está representado por el com_ptr. Este es el tipo del destino del puntero inteligente.

Requisitos

SDK mínimo admitido: SDK de Windows, versión 10.0.17134.0 (Windows 10, versión 1803)

Espacio de nombres: winrt

Encabezado: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (incluido de forma predeterminada)

Alias de tipo de miembro

Constructores

Funciones miembro

Operadores de miembro

Funciones gratuitas

Operadores gratuitos

constructor com_ptr::com_ptr

Inicializa una nueva instancia de la estructura com_ptr , opcionalmente con una copia o movimiento de los datos de entrada.

El void* constructor toma una T* y asume la propiedad. winrt::take_ownership_from_abi_t es un tipo de marcador que hace explícita la responsabilidad de liberar este puntero se está transfiriendo ahora al com_ptr. El refcount no tiene que ser exactamente 1; sólo dice que se transfiere la responsabilidad.

Sintaxis

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;

Parámetros de plantilla

typename U El tipo de destino al que apunta el puntero inteligente de entrada.

Parámetros

other Otra com_ptr que inicializa el objeto com_ptr . La T del parámetro debe ser convertible a la T del objeto com_ptr.

com_ptr::as (función)

Devuelve la interfaz solicitada, si se admite. Produce si no lo es. Esta función es útil si desea consultar una interfaz que no necesita volver al autor de la llamada.

Para obtener ejemplos de código, consulte la sección Creación de instancias y devolución de tipos e interfaces proyectados y otras secciones de ese tema.

Sintaxis

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

Parámetros de plantilla

typename To El tipo de interfaz solicitada.

Parámetros

to Referencia a un valor para recibir la interfaz solicitada.

Valor devuelto

Un com_ptr que hace referencia a la interfaz solicitada o un puntero inteligente fuertemente tipado para la interfaz solicitada (declarado por C++/WinRT o por un tercero).

función com_ptr::attach

Adjunta a un puntero sin procesar que posee una referencia a su destino; no se agrega una referencia adicional. Si es necesario, puede usar esta función para fusionar referencias.

Sintaxis

void attach(T* value) noexcept;

Parámetros

value Puntero sin formato que posee una referencia a su destino.

com_ptr::capture (función)

Llama a una función o método especificado (llamando automáticamente a winrt::check_hresult en él) y captura el puntero de interfaz que se genera desde la función o el método como un void**archivo .

Consulte también la plantilla de función winrt::capture.

Sintaxis

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);

Parámetros de plantilla

typename F Un tipo de objeto de función, como una función libre o std::function.

typename O Un tipo de interfaz.

typename M Tipo de método.

typename Args Cero o más tipos de argumentos.

Parámetros

function Objeto de función de tipo F.

p Puntero a un objeto de tipo O.

object Un winrt::com_ptr de tipo O.

method Un método (implementado por O) de tipo M.

args Cero o más argumentos de tipo Args.

Observaciones

• La capture(F function, Args&&...args) sobrecarga invoca el objeto de función.
• La capture(O* p, M method, Args&& ...args) sobrecarga invoca el método en el puntero.
• La capture(winrt::com_ptr<O> const& object, M method, Args&&...args) sobrecarga invoca el método en el objeto.

Todas las sobrecargas pasan (al invocado) los argumentos adicionales que proporcione. Todas las sobrecargas también pasan los dos argumentos adicionales que requieren estas invocaciones, en concreto, un REFIID (el identificador del destino de winrt::com_ptr) y un void** (la dirección de un puntero al destino de winrt::com_ptr).

Ejemplo

winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);

función com_ptr::copy_from

Copia desde otro puntero. Disminuye el recuento de referencias en cualquier interfaz u objeto a los que se hace referencia actualmente, copia el parámetro de puntero sin procesar y comienza a administrar la duración de la interfaz o el objeto al que apunta.

Sintaxis

void copy_from(T* other) noexcept;

Parámetros

other Puntero sin formato a un destino cuya duración debe ser administrada por el objeto com_ptr .

función com_ptr::copy_to

Copia en otro puntero desde el objeto com_ptr . Incrementa el recuento de referencias en cualquier interfaz u objeto a los que se hace referencia actualmente y copia la dirección de memoria de esa interfaz o objeto en el parámetro . Esta función permite entregar una referencia a la misma interfaz sin llamar a QueryInterface.

Sintaxis

void copy_to(T** other) const noexcept;

Parámetros

other La dirección de un puntero sin procesar; en el que copiar el puntero al destino del objeto com_ptr .

función com_ptr::d etach

Se desasocia de la interfaz o objeto al que se hace referencia sin disminuir el recuento de referencias, quizás para devolverlo a un autor de la llamada.

Sintaxis

T* detach() noexcept;

Valor devuelto

Puntero a la interfaz u objeto al que hace referencia el objeto com_ptr .

com_ptr::get (función)

Devuelve el puntero sin procesar subyacente si necesita pasarlo a una función. Puede llamar a AddRef, Release o QueryInterface en el puntero devuelto.

Sintaxis

T* get() const noexcept;

Valor devuelto

Puntero a la interfaz u objeto al que hace referencia el objeto com_ptr .

función com_ptr::p ut

Devuelve la dirección del puntero sin formato subyacente que se pasará a una función que rellenará el valor; esta función le ayuda a llamar a métodos (como los métodos COM) que devuelven referencias como parámetros de salida a través de un puntero a un puntero.

Sintaxis

T** put() noexcept;

Valor devuelto

Dirección del puntero sin formato subyacente.

función com_ptr::p ut_void

Devuelve la dirección del puntero sin formato subyacente como puntero a un puntero a void para pasarlo a una función (como los métodos COM) que devuelven referencias como parámetros de salida a través de un puntero a un puntero a void.

Sintaxis

void** put_void() noexcept;

Valor devuelto

La dirección del puntero sin formato subyacente como puntero a un puntero a void.

función com_ptr::try_as

Devuelve la interfaz solicitada, si se admite. Devuelve nullptr (la autosobrecarga -returning) o false (la boolsobrecarga -returning), si no lo es. Esta función es útil si desea consultar una interfaz que no necesita volver al autor de la llamada.

Sintaxis

template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;

Parámetros de plantilla

typename To El tipo de interfaz solicitada.

Parámetros

to Referencia a un valor para recibir la interfaz solicitada.

Valor devuelto

Un com_ptr que hace referencia a la interfaz solicitada o un puntero inteligente fuertemente tipado para la interfaz solicitada (declarado por C++/WinRT o por un tercero), si se admite la interfaz solicitada, de lo contrario nullptr (la autosobrecarga -returning) o false (la boolsobrecarga -returning).

función com_ptr::try_capture

Una versión de com_ptr::capture que no produce un error, sino que devuelve devoluciones true si se realizan correctamente o false si no.

Consulte también la plantilla de función winrt::try_capture.

com_ptr::operador bool

Comprueba si el puntero inteligente hace referencia a una interfaz o un objeto o no. Si el puntero inteligente no hace referencia a una interfaz o un objeto, es lógicamente NULL; de lo contrario, no es null lógicamente.

Sintaxis

explicit operator bool() const noexcept;

Valor devuelto

true Si el puntero inteligente hace referencia a una interfaz u objeto (lógicamente no es nulo), de lo contrario false (lógicamente nulo).

com_ptr::operator* (operador de direccionamiento indirecto)

Devuelve una referencia al destino del com_ptr para que pueda pasarla a una función que espere una referencia al tipo de destino T.

Sintaxis

T& operator*() const noexcept;

Valor devuelto

Una referencia al objetivo del com_ptr.

com_ptr::operator= (operador de asignación)

Asigna un valor al objeto com_ptr .

Sintaxis

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;

Parámetros de plantilla

typename U Tipo al que apunta el valor que se va a asignar.

Parámetros

other Un valor com_ptr que se va a asignar al objeto com_ptr . La T del parámetro debe ser convertible a la T del objeto com_ptr.

Valor devuelto

Referencia al objeto com_ptr .

com_ptr::operador-> (operador de flecha)

Para permitir el acceso a los métodos de la interfaz o del objeto al que se hace referencia, devuelve el puntero sin procesar subyacente. No puede llamar a AddRef ni a Release en el puntero devuelto, pero puede llamar a QueryInterface.

Sintaxis

auto operator->() const noexcept;

Valor devuelto

Puntero a la interfaz u objeto al que hace referencia el objeto com_ptr .

función attach_abi

Adjunta un objeto com_ptr a un puntero sin formato que posee una referencia a su destino; No se agrega una referencia adicional. Si es necesario, puede usar esta función para fusionar referencias.

Sintaxis

void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;

Parámetros

object Un objeto com_ptr para operar.

value Puntero sin formato que posee una referencia a su destino.

función detach_abi

Desasocia un objeto com_ptr de su interfaz sin procesar sin disminuir el recuento de referencias, quizás para devolverlo a un llamador.

Sintaxis

auto detach_abi(winrt::com_ptr<T>& object) noexcept;

Parámetros

object Un objeto com_ptr para operar.

Valor devuelto

Puntero a la interfaz sin formato a la que hace referencia el objeto com_ptr .

operator!= (operador de desigualdad)

Devuelve un valor que indica si los dos parámetros hacen referencia a destinos diferentes.

Sintaxis

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;

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si los dos parámetros apuntan a objetivos diferentes, de lo contrario false.

operador< (operador menor que)

Devuelve un valor que indica si el destino del primer parámetro se produce antes en la memoria que el del segundo parámetro.

Sintaxis

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

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si la dirección de memoria del objetivo del primer parámetro es menor que la del segundo parámetro, de lo contrario false.

operator<= (operador menor o igual a)

Devuelve un valor que indica si el destino del primer parámetro se produce antes en la memoria que, o en la misma ubicación que, del segundo parámetro.

Sintaxis

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

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si la dirección de memoria del objetivo del primer parámetro es menor o igual que la del segundo parámetro, de lo contrario false.

operator== (operador de igualdad)

Devuelve un valor que indica si los dos parámetros hacen referencia a la misma interfaz o objeto.

Sintaxis

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;

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si los dos parámetros apuntan al mismo objetivo, de lo contrario false.

operador> (operador mayor que)

Devuelve un valor que indica si el destino del primer parámetro se produce más adelante en la memoria que el del segundo parámetro.

Sintaxis

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

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si la dirección de memoria del objetivo del primer parámetro es mayor que la del segundo parámetro, de lo contrario false.

operator>= (operador mayor o igual a)

Devuelve un valor que indica si el destino del primer parámetro se produce más adelante en la memoria que, o en la misma ubicación que, el del segundo parámetro.

Sintaxis

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

Parámetros

left right Un valor com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.

Valor devuelto

true Si la dirección de memoria del objetivo del primer parámetro es mayor o igual que la del segundo parámetro, de lo contrario false.

función swap

Intercambia el contenido de los dos parámetros de com_ptr para que apunten entre sí al destino.

Sintaxis

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

Parámetros

left right Un valor com_ptr cuyo puntero se intercambia mutuamente con el del otro parámetro.

Consulte también

• espacio de nombres de winrt
• Consumir APIs utilizando C++/WinRT