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

  • Artículo

Plantilla de puntero inteligente COM con recuento de referencias. com_ptr representa un puntero al tipo de implementación de 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 La interfaz o el tipo de implementación de clase en tiempo de ejecución, un puntero al que está representado por el com_ptr. Este es el tipo del destino del puntero inteligente.

Requisitos

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

Namespace: winrt

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

Alias de tipo de miembro

Nombre del alias Tipo
com_ptr::type Sinónimo de una representación definida por la implementación del parámetro de plantilla typename T.

Constructores

Constructor Descripción
com_ptr::com_ptr constructor Inicializa una nueva instancia de la estructura com_ptr, opcionalmente con una copia o movimiento de los datos de entrada.

Funciones miembro

Función Descripción
com_ptr::as de función Devuelve la interfaz solicitada, si se admite. Produce si no lo es.
com_ptr::attach de función Adjunta a un puntero sin procesar que posee una referencia a su destino; no se agrega una referencia adicional.
com_ptr::capture (función) Llama a una función o método especificados (llamando automáticamente a winrt::check_hresult en él) y captura el puntero de interfaz que es el resultado de la función o método como un void**.
de 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.
com_ptr::copy_to función Copia en otro puntero del 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 .
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.
com_ptr::get function Devuelve el puntero sin procesar subyacente si necesita pasarlo a una función.
de función com_ptr::p ut Devuelve la dirección del puntero sin formato subyacente; esta función le ayuda a llamar a métodos (como métodos COM) que devuelven referencias como parámetros out a través de un puntero a un puntero.
com_ptr::p ut_void Devuelve la dirección del puntero sin formato subyacente como puntero a un puntero a void; esta función le ayuda a llamar a métodos (como métodos COM) que devuelven referencias como parámetros out a través de un puntero a un puntero a void.
com_ptr::try_as función Devuelve la interfaz solicitada, si se admite. Devuelve nullptr, o false, si no lo es.
com_ptr::try_capture función Una versión de com_ptr::capture que no produce un error, sino que devuelve true si se ejecuta correctamente o false si no.

Operadores de miembro

Operador Descripción
com_ptr::operator bool Comprueba si el puntero inteligente hace referencia a una interfaz o un objeto o no.
com_ptr::operator* (operador de direccionamiento indirecto) Devuelve una referencia al destino de com_ptrpara que pueda pasarla a una función que espera una referencia al tipo de destino T.
com_ptr::operator= (operador de asignación) Asigna un valor al objeto com_ptr.
com_ptr::operator-> (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.

Funciones gratuitas

Función Descripción
attach_abi función Asocia un objeto com_ptr a un puntero sin procesar que posee una referencia a su destino; no se agrega una referencia adicional.
detach_abi de función Desasocia un objeto com_ptr de su interfaz sin procesar sin disminuir el recuento de referencias, quizás para devolverlo a un autor de la llamada.
función de intercambio Intercambia el contenido de los dos parámetros com_ptr para que apunten entre sí.

Operadores gratuitos

Función Descripción
operador != (operador de desigualdad) Devuelve un valor que indica si los dos parámetros hacen referencia a destinos diferentes.
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.
operador<= (operador menor o igual que) 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.
operator== (operador de igualdad) Devuelve un valor que indica si los dos parámetros hacen referencia a la misma interfaz o objeto.
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.
operador>= (operador mayor o igual que) 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.

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 constructor void* toma un T*y asume la propiedad. winrt::take_ownership_from_abi_t es un tipo de marcador que hace explícito la responsabilidad de liberar este puntero ahora se transfiere 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 Otro com_ptr que inicializa el objeto com_ptr. El T del parámetro debe convertirse en el Tdel 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 proyectadosy 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 Tipo de la interfaz solicitada.

Parámetros

to Una referencia a un valor para recibir la interfaz solicitada.

Valor devuelto

Un com_ptr hacer referencia a la interfaz solicitada o un puntero inteligente fuertemente tipado para la interfaz solicitada (ya sea 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 procesar que posee una referencia a su destino.

com_ptr::capture (función)

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

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 A.

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 winrt::com_ptr de tipo O.

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

args Cero o más argumentos de tipo Args.

Observaciones

  • La sobrecarga capture(F function, Args&&...args) invoca el objeto de función.
  • La sobrecarga capture(O* p, M method, Args&& ...args) invoca el método en el puntero.
  • La sobrecarga de capture(winrt::com_ptr<O> const& object, M method, Args&&...args) 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 tales invocaciones, en concreto, un REFIID (el identificador del destino del winrt::com_ptr) y un void** (la dirección de un puntero al destino del 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 procesar a un destino cuya duración debe administrar el objeto com_ptr.

función com_ptr::copy_to

Copia en otro puntero del 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 le permite entregar una referencia a la misma interfaz sin llamar a QueryInterface.

Sintaxis

void copy_to(T** other) const noexcept;

Parámetros

other dirección del puntero sin procesar; en el que se va a 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 o al 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, Releaseo QueryInterface en el puntero devuelto.

Sintaxis

T* get() const noexcept;

Valor devuelto

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

función com_ptr::p ut

Devuelve la dirección del puntero sin formato subyacente; esta función le ayuda a llamar a métodos (como métodos COM) que devuelven referencias como parámetros out a través de un puntero a un puntero. Si el objeto com_ptr ya tiene un destino, asígnele nullptr al objeto com_ptr antes de llamar a esta función; de lo contrario, la función se declarará.

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; esta función le ayuda a llamar a métodos (como métodos COM) que devuelven referencias como parámetros out a través de un puntero a un puntero a void. Si el objeto com_ptr ya tiene un destino, asígnele nullptr al objeto com_ptr antes de llamar a esta función; de lo contrario, la función se declarará.

Sintaxis

void** put_void() noexcept;

Valor devuelto

Dirección del puntero sin formato subyacente como puntero a un puntero para void.

función com_ptr::try_as

Devuelve la interfaz solicitada, si se admite. Devuelve nullptr (la sobrecarga de devolución de auto) o false (la sobrecarga de devolución de bool), si no lo está. 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 Tipo de la interfaz solicitada.

Parámetros

to Una referencia a un valor para recibir la interfaz solicitada.

Valor devuelto

Un com_ptr hacer referencia a la interfaz solicitada o a un puntero inteligente fuertemente tipado para la interfaz solicitada (declarada por C++/WinRT o por un tercero), si se admite la interfaz solicitada, de lo contrario, nullptr (la sobrecarga de devolución de auto) o false (la sobrecarga de devolución de bool).

función com_ptr::try_capture

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

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

com_ptr::operator 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 o objeto (lógicamente no null), de lo contrario, false (lógicamente NULL).

com_ptr::operator* (operador de direccionamiento indirecto)

Devuelve una referencia al destino de com_ptrpara que pueda pasarla a una función que espera una referencia al tipo de destino T.

Sintaxis

T& operator*() const noexcept;

Valor devuelto

Referencia al destino 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 valor de com_ptr que se va a asignar al objeto com_ptr. El T del parámetro debe convertirse en el Tdel objeto com_ptr .

Valor devuelto

Referencia al objeto com_ptr.

com_ptr::operator-> (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 Release en el puntero devuelto, pero puede llamar a QueryInterface.

Sintaxis

auto operator->() const noexcept;

Valor devuelto

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

función attach_abi

Asocia un objeto com_ptr 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_abi(winrt::com_ptr<T>& object, T* value) noexcept;

Parámetros

object objeto com_ptr en el que operar.

value puntero sin procesar 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 autor de la llamada.

Sintaxis

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

Parámetros

object objeto com_ptr en el que 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 de 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 destinos 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 de 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 primer parámetro del destino es menor que la del segundo parámetro; de lo contrario, false.

operator<= (operador menor o igual que)

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 de 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 primer parámetro de destino 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 de 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 destino; 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 de 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 primer parámetro de destino es mayor que la del segundo parámetro; de lo contrario, false.

operator>= (operador mayor que o igual que)

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 de 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 primer parámetro del destino 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 com_ptr para que apunten entre sí.

Sintaxis

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

Parámetros

left right valor de com_ptr cuyo puntero se va a intercambiar mutuamente con el del otro parámetro.

Consulte también