ComPtr (clase)

Crea un tipo de puntero inteligente que representa la interfaz especificada por el parámetro de plantilla. ComPtr mantiene automáticamente un recuento de referencias para el puntero de la interfaz subyacente y la libera cuando el recuento de referencias llega a cero.

Sintaxis

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

Parámetros

T
Interfaz que representa ComPtr.

U
Clase para la que ComPtr es de confianza. (La plantilla que usa este parámetro está protegida).

Comentarios

ComPtr<> declara un tipo que representa el puntero de interfaz subyacente. Use ComPtr<> para declarar una variable y luego use el operador de acceso a miembros de flecha (->) para tener acceso a una función miembro de interfaz.

Para obtener más información sobre los punteros inteligentes, consulte la subsección "Punteros inteligentes de COM" del artículo COM Coding Practices (Prácticas de codificación COM).

Miembros

Definiciones de tipos públicas

Nombre	Descripción
InterfaceType	Un sinónimo del tipo especificado por el parámetro de plantilla T .

Constructores públicos

Nombre	Descripción
ComPtr::ComPtr	Inicializa una nueva instancia de la clase ComPtr. Las sobrecargas proporcionan constructores predeterminados, así como de copia, movimiento y conversión.
ComPtr::~ComPtr	Desinicializa una instancia de ComPtr.

Métodos públicos

Nombre	Descripción
ComPtr::As	Devuelve un objeto de ComPtr que representa la interfaz que identificó el parámetro de plantilla especificado.
ComPtr::AsIID	Devuelve un objeto de ComPtr que representa la interfaz que identificó el identificador de plantilla especificado.
ComPtr::AsWeak	Recupera una referencia débil al objeto actual.
ComPtr::Attach	Asocia esta clase ComPtr con el tipo de interfaz que especificó el parámetro de tipo de plantilla actual.
ComPtr::CopyTo	Copia la interfaz actual o especificada asociada a esta clase ComPtr al puntero de salida especificado.
ComPtr::Detach	Desasocia esta clase ComPtr de la interfaz que representa.
ComPtr::Get	Recupera un puntero a la interfaz que está asociada a esta clase ComPtr.
ComPtr::GetAddressOf	Recupera la dirección del miembro de datos ptr_, que contiene un puntero a la interfaz representada por esta clase ComPtr.
ComPtr::ReleaseAndGetAddressOf	Libera la interfaz asociada a esta clase ComPtr y después recupera la dirección del miembro de datos ptr_, que contiene un puntero a la interfaz que se liberó.
ComPtr::Reset	Libera la interfaz asociada a esta clase ComPtr y devuelve el nuevo recuento de referencias.
ComPtr::Swap	Intercambia la interfaz administrada por la clase ComPtr actual con la interfaz administrada por la ComPtr especificada.

Métodos protegidos

Nombre	Descripción
ComPtr::InternalAddRef	Incrementa el recuento de referencias de la interfaz asociada a esta clase ComPtr.
ComPtr::InternalRelease	Realiza una operación de liberación de COM en la interfaz asociada a esta clase ComPtr.

Operadores públicos

Nombre	Descripción
ComPtr::operator&	Recupera la dirección de la clase ComPtr actual.
ComPtr::operator->	Recupera un puntero al tipo especificado por el parámetro de plantilla actual.
ComPtr::operator=	Asigna un valor a la clase ComPtr actual.
ComPtr::operator==	Indica si dos objetos ComPtr son iguales.
ComPtr::operator!=	Indica si dos objetos ComPtr no son iguales.
ComPtr::operator Microsoft::WRL::Details::BoolType	Indica si una clase ComPtr administra o no la duración del objeto de una interfaz.

Miembros de datos protegidos

Nombre	Descripción
ComPtr::ptr_	Contiene un puntero a la interfaz que está asociad y está administrado por esta clase ComPtr.

Jerarquía de herencia

ComPtr

Requisitos

Encabezado: client.h

Espacio de nombres: Microsoft::WRL

ComPtr::~ComPtr

Desinicializa una instancia de ComPtr.

WRL_NOTHROW ~ComPtr();

ComPtr::As

Devuelve un objeto de ComPtr que representa la interfaz que identificó el parámetro de plantilla especificado.

template<typename U>
HRESULT As(
   _Out_ ComPtr<U>* p
) const;

template<typename U>
HRESULT As(
   _Out_ Details::ComPtrRef<ComPtr<U>> p
) const;

Parámetros

U
Interfaz que se va a representar mediante el parámetro p.

p
Objeto ComPtr que representa la interfaz que especificó el parámetro U. El parámetro p no debe hacer referencia al objeto actual ComPtr.

Comentarios

La primera plantilla es el formulario que debe usar en el código. La segunda plantilla es una especialización interna del asistente. Admite características del lenguaje C++, como, por ejemplo, la palabra clave de deducción de tipo auto.

Valor devuelto

S_OK si se realiza correctamente; de lo contrario, devuelve HRESULT que indica el error.

ComPtr::AsIID

Devuelve un objeto de ComPtr que representa la interfaz que identificó el identificador de plantilla especificado.

WRL_NOTHROW HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IUnknown>* p
) const;

Parámetros

riid
Id. de interfaz.

p
Si el objeto tiene una interfaz cuyo identificador es igual a riid, un puntero indirecto doble a la interfaz que especificó el parámetro riid. De lo contrario, devuelve un puntero a IUnknown.

Valor devuelto

S_OK si se realiza correctamente; de lo contrario, devuelve HRESULT que indica el error.

ComPtr::AsWeak

Recupera una referencia débil al objeto actual.

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

Parámetros

pWeakRef
Cuando se completa esta operación, devuelve un puntero a un objeto de referencia débil.

Valor devuelto

S_OK si se realiza correctamente; de lo contrario, un HRESULT que indica el error.

ComPtr::Attach

Asocia esta clase ComPtr con el tipo de interfaz que especificó el parámetro de tipo de plantilla actual.

void Attach(
   _In_opt_ InterfaceType* other
);

Parámetros

other
Tipo de interfaz.

ComPtr::ComPtr

Inicializa una nueva instancia de la clase ComPtr. Las sobrecargas proporcionan constructores predeterminados, así como de copia, movimiento y conversión.

WRL_NOTHROW ComPtr();

WRL_NOTHROW ComPtr(
   decltype(__nullptr)
);

template<class U>
WRL_NOTHROW ComPtr(
   _In_opt_ U *other
);

WRL_NOTHROW ComPtr(
   const ComPtr& other
);

template<class U>
WRL_NOTHROW ComPtr(
   const ComPtr<U> &other,
   typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

WRL_NOTHROW ComPtr(
   _Inout_ ComPtr &&other
);

template<class U>
WRL_NOTHROW ComPtr(
   _Inout_ ComPtr<U>&& other, typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

Parámetros

U
Tipo del parámetro other.

other
Objeto de tipo U.

Valor devuelto

Comentarios

El primer constructor es el constructor predeterminado, que crea implícitamente un objeto vacío. El segundo constructor especifica __nullptr, que crea explícitamente un objeto vacío.

El tercer constructor crea un objeto a partir del objeto especificado por un puntero. Ahora ComPtr posee la memoria a la que apunta y mantiene un recuento de referencias.

Los constructores cuarto y quinto son constructores de copia. El quinto constructor copia un objeto si es convertible al tipo actual.

Los constructores sexto y séptimo son constructores de movimiento. El séptimo constructor mueve un objeto si es convertible al tipo actual.

ComPtr::CopyTo

Copia la interfaz actual o especificada asociada a esta clase ComPtr al puntero especificado.

HRESULT CopyTo(
   _Deref_out_ InterfaceType** ptr
);

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ void** ptr
) const;

template<typename U>
HRESULT CopyTo(
   _Deref_out_ U** ptr
) const;

Parámetros

U
Nombre de tipo.

ptr
Cuando se completa esta operación, se obtiene un puntero a la interfaz solicitada.

riid
Id. de interfaz.

Valor devuelto

S_OK si se ejecuta correctamente; de lo contrario, se obtiene HRESULT, que indica por qué se produjo un error en la operación implícita QueryInterface.

Comentarios

La primera función devuelve una copia de un puntero a la interfaz asociada a este ComPtr. Esta función siempre devuelve el valor S_OK.

La segunda función realiza una operación QueryInterface en la interfaz asociada a esta ComPtr para la interfaz especificada por el parámetro riid.

La tercera función realiza una operación QueryInterface en la interfaz asociada a esta ComPtr para la interfaz subyacente del parámetro U.

ComPtr::Detach

Desasocia esta clase ComPtr de la interfaz que representa.

T* Detach();

Valor devuelto

Puntero a la interfaz representada por este objeto ComPtr.

ComPtr::Get

Recupera un puntero a la interfaz que está asociada a esta clase ComPtr.

T* Get() const;

Valor devuelto

Puntero a la interfaz que está asociada a esta clase ComPtr.

ComPtr::GetAddressOf

Recupera la dirección del miembro de datos ptr_, que contiene un puntero a la interfaz representada por esta clase ComPtr.

T* const* GetAddressOf() const;
T** GetAddressOf();

Valor devuelto

Dirección de una variable.

ComPtr::InternalAddRef

Incrementa el recuento de referencias de la interfaz asociada a esta clase ComPtr.

void InternalAddRef() const;

Comentarios

Este método está protegido.

ComPtr::InternalRelease

Realiza una operación de liberación de COM en la interfaz asociada a esta clase ComPtr.

unsigned long InternalRelease();

Comentarios

Este método está protegido.

ComPtr::operator&

Libera la interfaz asociada a este objeto ComPtr y, a continuación, recupera la dirección del objeto ComPtr.

Details::ComPtrRef<WeakRef> operator&()

const Details::ComPtrRef<const WeakRef> operator&() const

Valor devuelto

Referencia débil a la clase ComPtr actual.

Comentarios

Este método difiere de ComPtr::GetAddressOf en que libera una referencia al puntero de interfaz. Use ComPtr::GetAddressOf cuando necesite la dirección del puntero de interfaz, pero no quiera liberar esa interfaz.

ComPtr::operator->

Recupera un puntero al tipo especificado por el parámetro de plantilla actual.

WRL_NOTHROW Microsoft::WRL::Details::RemoveIUnknown<InterfaceType>* operator->() const;

Valor devuelto

Puntero al tipo especificado por el parámetro de plantilla actual.

Comentarios

Esta función auxiliar elimina la sobrecarga innecesaria que provoca el uso de la macro STDMETHOD. Esta función genera IUnknown tipos private en lugar de virtual.

ComPtr::operator=

Asigna un valor a la clase ComPtr actual.

WRL_NOTHROW ComPtr& operator=(
   decltype(__nullptr)
);
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ T *other
);
template <typename U>
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ U *other
);
WRL_NOTHROW ComPtr& operator=(
   const ComPtr &other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   const ComPtr<U>& other
);
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr &&other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr<U>&& other
);

Parámetros

U
Clase.

other
Puntero, referencia o referencia rvalue a un tipo u otro ComPtr.

Valor devuelto

Referencia al ComPtr actual.

Comentarios

La primera versión de este operador asigna un valor vacío al objeto actual ComPtr.

En la segunda versión, si el puntero de interfaz de asignación no es el mismo que el puntero de interfaz actual ComPtr, se asigna el segundo puntero de interfaz ComPtr actual.

En la tercera versión, el puntero de interfaz de asignación se asigna al ComPtr actual.

En la cuarta versión, si el puntero de interfaz del valor de asignación no es el mismo que el puntero de interfaz ComPtr actual, se asigna el segundo puntero de interfaz al ComPtr actual.

La quinta versión es un operador de copia; se asigna una referencia a ComPtr al ComPtr actual.

La sexta versión es un operador de copia que usa la semántica de movimiento; una referencia rvalue a ComPtr si algún tipo es la conversión estática y, a continuación, se asigna al ComPtr actual.

La séptima versión es un operador de copia que usa la semántica de movimiento; una referencia rvalue a ComPtr del tipo U es una conversión estática y, a continuación, se asigna al ComPtr actual.

ComPtr::operator==

Indica si dos objetos ComPtr son iguales.

bool operator==(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator==(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator==(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parámetros

a
Referencia a un objeto ComPtr.

b
Referencia a otro objeto ComPtr.

Valor devuelto

El primer operador produce true si el objeto a es igual al objeto b; de lo contrario, false.

Los operadores segundo y tercero producen true si el objeto a es igual a nullptr; de lo contrario, false.

ComPtr::operator!=

Indica si dos objetos ComPtr no son iguales.

bool operator!=(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator!=(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator!=(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parámetros

a
Referencia a un objeto ComPtr.

b
Referencia a otro objeto ComPtr.

Valor devuelto

El primer operador produce true si el objeto a no es igual al objeto b; de lo contrario, false.

Los operadores segundo y tercero producen true si el objeto a no es igual a nullptr; de lo contrario, false.

ComPtr::operator Microsoft::WRL::Details::BoolType

Indica si una clase ComPtr administra o no la duración del objeto de una interfaz.

WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const;

Valor devuelto

Si una interfaz se asocia a este ComPtr, la dirección del miembro de datos BoolStruct::Member; en caso contrario, nullptr.

ComPtr::ptr_

Contiene un puntero a la interfaz que está asociad y está administrado por esta clase ComPtr.

InterfaceType *ptr_;

Comentarios

ptr_ es un miembro de datos interno protegido.

ComPtr::ReleaseAndGetAddressOf

Libera la interfaz asociada a esta clase ComPtr y después recupera la dirección del miembro de datos ptr_, que contiene un puntero a la interfaz que se liberó.

T** ReleaseAndGetAddressOf();

Valor devuelto

Dirección del miembro de datos ptr_ de este ComPtr.

ComPtr::Reset

Libera la interfaz asociada a esta clase ComPtr y devuelve el nuevo recuento de referencias.

unsigned long Reset();

Valor devuelto

Número de referencias restantes a la interfaz subyacente, si existe.

ComPtr::Swap

Intercambia la interfaz administrada por la clase ComPtr actual con la interfaz administrada por la ComPtr especificada.

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

Parámetros

r
ComPtr.