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 interfaz o clase en tiempo de ejecución especificado por el parámetro de plantilla. 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, 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)
Espacio de nombres: winrt
Encabezado: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (incluido de forma predeterminada)
Alias de tipo de miembro
| Nombre de alias | Tipo |
|---|---|
| com_ptr::type | Sinónimo de una representación definida por la implementación del typename T parámetro de plantilla. |
Constructores
| Constructor | Descripción |
|---|---|
| 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. |
Funciones miembro
| Función | Descripción |
|---|---|
| com_ptr::as (función) | Devuelve la interfaz solicitada, si se admite. Produce si no lo es. |
| función com_ptr::attach | 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 se genera desde la función o método como .void** |
| función com_ptr::copy_from | Copia desde otro puntero. Disminuye el recuento de referencias en cualquier interfaz u objeto a la 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. |
| 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 la que se hace referencia actualmente y copia la dirección de memoria de esa interfaz o objeto en el parámetro . |
| función com_ptr::d etach | Se desasocia de la interfaz o el 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 (función) | Devuelve el puntero sin procesar subyacente si necesita pasarlo a una función. |
| función com_ptr::p ut | Devuelve la dirección del puntero sin procesar subyacente; esta función 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. |
| función com_ptr::p ut_void | Devuelve la dirección del puntero sin procesar 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. |
| función com_ptr::try_as | Devuelve la interfaz solicitada, si se admite. Devuelve nullptr, o false, si no lo es. |
| función com_ptr::try_capture | Una versión de com_ptr::capture que no produce un error, sino que devuelve si true es correcta 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. |
| com_ptr::operator* (operador de direccionamiento indirecto) | Devuelve una referencia al destino del com_ptr para 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 formato subyacente. |
Funciones gratuitas
| Función | Descripción |
|---|---|
| Función attach_abi | Adjunta un objeto com_ptr a un puntero sin procesar que posee una referencia a su destino; no se agrega una referencia adicional. |
| 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. |
| swap (función) | Intercambia el contenido de los dos parámetros com_ptr para que apunten entre sí. |
Operadores gratuitos
| Función | Descripción |
|---|---|
| operator!= (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. |
| 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. |
| 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. |
| operator>= (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, 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 void* constructor 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 recuento de referencias no tiene que ser exactamente 1; sólo dice que se está transfiriendo 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 Tipo de destino al que apunta el puntero inteligente de entrada.
Parámetros
other Otro com_ptr que inicializa el objeto com_ptr . El parámetro T debe ser convertible al T del objetocom_ptr.
com_ptr::as (función)
Devuelve la interfaz solicitada, si se admite. Produce si no es así. 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, vea 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 Tipo de la interfaz solicitada.
Parámetros
to 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 declarada por C++/WinRT o por un tercero).
com_ptr::attach (función)
Adjunta 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(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 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 .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 Tipo de objeto de función, como una función libre o std::function.
typename O 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 Método (implementado por O) de tipo M.
args Cero o más argumentos de tipo Args.
Comentarios
- 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 tales invocaciones, específicamente 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 al que se hace referencia actualmente, copia el parámetro de puntero sin formato 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 administrarse mediante 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 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 de un puntero sin formato; en la que se copia el puntero al destino del objeto com_ptr .
función com_ptr::d etach
Se desasocia de la interfaz o del 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 formato 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; 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ígnelo nullptr al objeto com_ptr antes de llamar a esta función; de lo contrario, la función se validará.
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ígnelo nullptr al objeto com_ptr antes de llamar a esta función; de lo contrario, la función se validará.
Sintaxis
void** put_void() noexcept;
Valor devuelto
Dirección del puntero sin formato subyacente como puntero a un puntero que se va a anular.
función com_ptr::try_as
Devuelve la interfaz solicitada, si se admite. Devuelve nullptr (la autosobrecarga -returns) o false (la boolsobrecarga -returns), 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 Tipo de la 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 (declarada por C++/WinRT o por un tercero), si se admite la interfaz solicitada, de lo contrario nullptr (la autosobrecarga -devolviendo) o false (la boolsobrecarga de devolución).
función com_ptr::try_capture
Una versión de com_ptr::capture que no se inicia en caso de error, sino que devuelve si true es correcta 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. Si el puntero inteligente no hace referencia a una interfaz u 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 null), de lo contrario false (lógicamente null).
com_ptr::operator* (operador de direccionamiento indirecto)
Devuelve una referencia al destino del com_ptr para 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 com_ptr que se va a asignar al objeto com_ptr . El parámetro T debe poder convertirse en el T del objetocom_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 formato 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 u objeto al que hace referencia el objeto com_ptr .
Función attach_abi
Asocia 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 Objeto com_ptr en el que 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 autor de 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 procesar 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
leftright Valor de com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.
Valor devuelto
true es si los dos parámetros apuntan a destinos diferentes; de lo contrario false, es .
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
leftright 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
leftright 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 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
leftright Valor de com_ptr cuya dirección de memoria del destino se va a comparar con la del otro parámetro.
Valor devuelto
true es si los dos parámetros apuntan al mismo destino; de lo contrario false, es .
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
leftright 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 que la del segundo parámetro; de lo contrario false, .
operator>= (operador greater-than-or-equal-to)
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, 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
leftright 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
leftright Valor com_ptr cuyo puntero se va a intercambiar mutuamente con el del otro parámetro.
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de