ComPtr — Klasa

  • Artykuł

Tworzy inteligentny typ wskaźnika, który reprezentuje interfejs określony przez parametr szablonu. ComPtr automatycznie utrzymuje liczbę odwołań dla bazowego wskaźnika interfejsu i zwalnia interfejs, gdy liczba odwołań przekroczy zero.

Składnia

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

Parametry

T
Interfejs reprezentowany ComPtr przez obiekt .

U
Klasa, do której obecny ComPtr jest przyjacielem. (Szablon używający tego parametru jest chroniony).

Uwagi

ComPtr<> deklaruje typ reprezentujący podstawowy wskaźnik interfejsu. Użyj ComPtr<> polecenia , aby zadeklarować zmienną, a następnie użyć operatora dostępu do elementu członkowskiego strzałki (->), aby uzyskać dostęp do funkcji składowej interfejsu.

Aby uzyskać więcej informacji na temat inteligentnych wskaźników, zobacz podsekcję "COM Smart Pointers" w artykule Com Coding Practices (Praktyki kodowania COM).

Członkowie

Definicje typów publicznych

Nazwa/nazwisko opis
InterfaceType Synonim typu określonego przez parametr szablonu T .

Konstruktory publiczne

Nazwa/nazwisko opis
ComPtr::ComPtr Inicjuje nowe wystąpienie klasy ComPtr. Przeciążenia zapewniają konstruktory domyślne, kopiowania, przenoszenia i konwersji.
ComPtr::~ComPtr Deinitializuje wystąpienie klasy ComPtr.

Metody publiczne

Nazwa/nazwisko opis
ComPtr::As ComPtr Zwraca obiekt reprezentujący interfejs zidentyfikowany przez określony parametr szablonu.
ComPtr::AsIID ComPtr Zwraca obiekt reprezentujący interfejs zidentyfikowany przez określony identyfikator interfejsu.
ComPtr::AsWeak Pobiera słabe odwołanie do bieżącego obiektu.
ComPtr::Attach Kojarzy to ComPtr z typem interfejsu określonym przez bieżący parametr typu szablonu.
ComPtr::CopyTo Kopiuje bieżący lub określony interfejs skojarzony z tym ComPtr do określonego wskaźnika wyjściowego.
ComPtr::Detach Usuwa skojarzenie tego ComPtr z interfejsu, który reprezentuje.
ComPtr::Get Pobiera wskaźnik do interfejsu skojarzonego z tym ComPtrelementem .
ComPtr::GetAddressOf Pobiera adres ptr_ elementu członkowskiego danych, który zawiera wskaźnik do interfejsu reprezentowanego przez ten ComPtrelement .
ComPtr::ReleaseAndGetAddressOf Zwalnia interfejs skojarzony z tym ComPtr elementem, a następnie pobiera adres ptr_ elementu członkowskiego danych, który zawiera wskaźnik do interfejsu, który został wydany.
ComPtr::Reset Zwalnia interfejs skojarzony z tym ComPtr elementem i zwraca nową liczbę odwołań.
ComPtr::Swap Wymienia interfejs zarządzany przez bieżący ComPtr interfejs za pomocą interfejsu zarządzanego przez określony ComPtrelement .

Metody chronione

Nazwa/nazwisko opis
ComPtr::InternalAddRef Zwiększa liczbę odwołań interfejsu skojarzonego z tym ComPtrelementem .
ComPtr::InternalRelease Wykonuje operację wydania COM na interfejsie skojarzonym z tym ComPtrelementem .

Operatory publiczne

Nazwa/nazwisko opis
ComPtr::operator& Pobiera adres bieżącego ComPtrobiektu .
ComPtr::operator-> Pobiera wskaźnik do typu określonego przez bieżący parametr szablonu.
ComPtr::operator= Przypisuje wartość do bieżącego ComPtrelementu .
ComPtr::operator== Wskazuje, czy dwa ComPtr obiekty są równe.
ComPtr::operator!= Wskazuje, czy dwa ComPtr obiekty nie są równe.
ComPtr::operator Microsoft::WRL::Details::BoolType Wskazuje, czy ComPtr obiekt zarządza okresem istnienia interfejsu.

Chronione składowe danych

Nazwa/nazwisko opis
ComPtr::ptr_ Zawiera wskaźnik do interfejsu skojarzonego z programem i zarządzanego przez ten ComPtrelement .

Hierarchia dziedziczenia

ComPtr

Wymagania

Nagłówka:client.h

Obszaru nazw:Microsoft::WRL

ComPtr::~ComPtr

Deinitializuje wystąpienie klasy ComPtr.

WRL_NOTHROW ~ComPtr();

ComPtr::As

ComPtr Zwraca obiekt reprezentujący interfejs zidentyfikowany przez określony parametr szablonu.

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

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

Parametry

U
Interfejs, który ma być reprezentowany przez parametr p.

p
ComPtr Obiekt reprezentujący interfejs określony przez parametr U. Parametr p nie może odwoływać się do bieżącego ComPtr obiektu.

Uwagi

Pierwszy szablon to formularz, którego należy użyć w kodzie. Drugi szablon to wewnętrzna specjalizacja pomocnika. Obsługuje funkcje języka C++, takie jak słowo kluczowe odliczenia auto typu.

Wartość zwracana

S_OK w przypadku powodzenia; w przeciwnym razie element HRESULT wskazujący błąd.

ComPtr::AsIID

ComPtr Zwraca obiekt reprezentujący interfejs zidentyfikowany przez określony identyfikator interfejsu.

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

Parametry

riid
Identyfikator interfejsu.

p
Jeśli obiekt ma interfejs, którego identyfikator jest riidrówny , podwójnie pośredni wskaźnik do interfejsu określonego riid przez parametr . W przeciwnym razie wskaźnik na IUnknown.

Wartość zwracana

S_OK w przypadku powodzenia; w przeciwnym razie element HRESULT wskazujący błąd.

ComPtr::AsWeak

Pobiera słabe odwołanie do bieżącego obiektu.

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

Parametry

pWeakRef
Po zakończeniu tej operacji wskaźnik do słabego obiektu odwołania.

Wartość zwracana

S_OK w przypadku powodzenia; w przeciwnym razie hrESULT wskazujący błąd.

ComPtr::Attach

Kojarzy to ComPtr z typem interfejsu określonym przez bieżący parametr typu szablonu.

void Attach(
   _In_opt_ InterfaceType* other
);

Parametry

other
Typ interfejsu.

ComPtr::ComPtr

Inicjuje nowe wystąpienie klasy ComPtr. Przeciążenia zapewniają konstruktory domyślne, kopiowania, przenoszenia i konwersji.

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

Parametry

U
Typ parametru other .

other
Obiekt typu U.

Wartość zwracana

Uwagi

Pierwszy konstruktor jest konstruktorem domyślnym, który niejawnie tworzy pusty obiekt. Drugi konstruktor określa __nullptr, który jawnie tworzy pusty obiekt.

Trzeci konstruktor tworzy obiekt z obiektu określonego przez wskaźnik. Teraz ComPtr jest właścicielem wskazywanej pamięci i utrzymuje liczbę odwołań do niej.

Czwarte i piąte konstruktory to konstruktory kopiowane. Piąty konstruktor kopiuje obiekt, jeśli jest konwertowany na bieżący typ.

Szóste i siódme konstruktory są konstruktorami przenoszenia. Siódmy konstruktor przenosi obiekt, jeśli jest konwertowany na bieżący typ.

ComPtr::CopyTo

Kopiuje bieżący lub określony interfejs skojarzony z tym ComPtr do określonego wskaźnika.

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;

Parametry

U
Nazwa typu.

ptr
Po zakończeniu tej operacji wskaźnik do żądanego interfejsu.

riid
Identyfikator interfejsu.

Wartość zwracana

S_OK w przypadku powodzenia; w przeciwnym razie element HRESULT wskazujący, dlaczego operacja niejawna QueryInterface nie powiodła się.

Uwagi

Pierwsza funkcja zwraca kopię wskaźnika do interfejsu skojarzonego z tym ComPtrelementem . Ta funkcja zawsze zwraca wartość S_OK.

Druga funkcja wykonuje operację QueryInterface na interfejsie skojarzonym z tym ComPtr dla interfejsu określonego riid przez parametr .

Trzecia funkcja wykonuje operację QueryInterface na interfejsie skojarzonym z tym ComPtr dla podstawowego interfejsu parametru U .

ComPtr::Detach

Usuwa skojarzenie tego ComPtr obiektu z interfejsu, który reprezentuje.

T* Detach();

Wartość zwracana

Wskaźnik do interfejsu reprezentowanego przez ten ComPtr obiekt.

ComPtr::Get

Pobiera wskaźnik do interfejsu skojarzonego z tym ComPtrelementem .

T* Get() const;

Wartość zwracana

Wskaźnik do interfejsu skojarzonego z tym ComPtrelementem .

ComPtr::GetAddressOf

Pobiera adres ptr_ elementu członkowskiego danych, który zawiera wskaźnik do interfejsu reprezentowanego przez ten ComPtrelement .

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

Wartość zwracana

Adres zmiennej.

ComPtr::InternalAddRef

Zwiększa liczbę odwołań interfejsu skojarzonego z tym ComPtrelementem .

void InternalAddRef() const;

Uwagi

Ta metoda jest chroniona.

ComPtr::InternalRelease

Wykonuje operację wydania COM na interfejsie skojarzonym z tym ComPtrelementem .

unsigned long InternalRelease();

Uwagi

Ta metoda jest chroniona.

ComPtr::operator&

Zwalnia interfejs skojarzony z tym ComPtr obiektem, a następnie pobiera adres ComPtr obiektu.

Details::ComPtrRef<WeakRef> operator&()

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

Wartość zwracana

Słabe odwołanie do bieżącego ComPtr.

Uwagi

Ta metoda różni się od ComPtr::GetAddressOf tego, że ta metoda zwalnia odwołanie do wskaźnika interfejsu. Użyj ComPtr::GetAddressOf polecenia , jeśli potrzebujesz adresu wskaźnika interfejsu, ale nie chcesz zwalniać tego interfejsu.

ComPtr::operator->

Pobiera wskaźnik do typu określonego przez bieżący parametr szablonu.

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

Wartość zwracana

Wskaźnik do typu określonego przez nazwę bieżącego typu szablonu.

Uwagi

Ta funkcja pomocnika usuwa niepotrzebne obciążenie spowodowane użyciem makra STDMETHOD. Ta funkcja tworzy IUnknown typy private zamiast virtual.

ComPtr::operator=

Przypisuje wartość do bieżącego ComPtrelementu .

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

Parametry

U
Klasa.

other
Wskaźnik, odwołanie lub odwołanie rvalue do typu lub innego ComPtr.

Wartość zwracana

Odwołanie do bieżącego ComPtr.

Uwagi

Pierwsza wersja tego operatora przypisuje pustą wartość do bieżącego ComPtrelementu .

W drugiej wersji, jeśli wskaźnik interfejsu przypisywania nie jest taki sam jak bieżący ComPtr wskaźnik interfejsu, drugi wskaźnik interfejsu jest przypisany do bieżącego ComPtr.

W trzeciej wersji wskaźnik interfejsu przypisywania jest przypisywany do bieżącego ComPtrelementu .

Jeśli w czwartej wersji wskaźnik interfejsu wartości przypisywanej nie jest taki sam jak bieżący ComPtr wskaźnik interfejsu, drugi wskaźnik interfejsu jest przypisany do bieżącego ComPtrelementu .

Piąta wersja jest operatorem kopiowania; odwołanie do a ComPtr jest przypisane do bieżącego ComPtr.

Szósta wersja to operator kopiowania, który używa semantyki przenoszenia; odwołanie rvalue do elementu ComPtr , jeśli jakikolwiek typ jest rzutowany statycznie, a następnie przypisany do bieżącego ComPtrelementu .

Siódmym wersją jest operator kopiowania, który używa semantyki przenoszenia; odwołanie rvalue do ComPtr typu U jest rzutowane statycznie, a następnie przypisane do bieżącego ComPtrelementu .

ComPtr::operator==

Wskazuje, czy dwa ComPtr obiekty są równe.

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

Parametry

a
Odwołanie do ComPtr obiektu.

b
Odwołanie do innego ComPtr obiektu.

Wartość zwracana

Pierwszy operator zwraca wartość true , jeśli obiekt a jest równy obiektowi b; w przeciwnym razie false.

Drugie i trzecie operatory dają wartość true , jeśli obiekt a jest równy nullptr; w przeciwnym razie false.

ComPtr::operator!=

Wskazuje, czy dwa ComPtr obiekty nie są równe.

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

Parametry

a
Odwołanie do ComPtr obiektu.

b
Odwołanie do innego ComPtr obiektu.

Wartość zwracana

Pierwszy operator zwraca wartość, jeśli obiekt a nie jest równy obiektowi trueb; w przeciwnym razie false.

Drugie i trzecie operatory dają wartość true , jeśli obiekt a nie jest równy nullptr; w przeciwnym razie false.

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

Wskazuje, czy ComPtr obiekt zarządza okresem istnienia interfejsu.

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

Wartość zwracana

Jeśli interfejs jest skojarzony z tym ComPtrelementem , adres BoolStruct::Member elementu członkowskiego danych; w przeciwnym razie nullptr.

ComPtr::ptr_

Zawiera wskaźnik do interfejsu skojarzonego z programem i zarządzanego przez ten ComPtrelement .

InterfaceType *ptr_;

Uwagi

ptr_ jest wewnętrznym, chronionym elementem członkowskim danych.

ComPtr::ReleaseAndGetAddressOf

Zwalnia interfejs skojarzony z tym ComPtr elementem, a następnie pobiera adres ptr_ elementu członkowskiego danych, który zawiera wskaźnik do interfejsu, który został wydany.

T** ReleaseAndGetAddressOf();

Wartość zwracana

Adres ptr_ elementu członkowskiego danych tego ComPtrelementu .

ComPtr::Reset

Zwalnia interfejs skojarzony z tym ComPtr elementem i zwraca nową liczbę odwołań.

unsigned long Reset();

Wartość zwracana

Liczba odwołań pozostałych do podstawowego interfejsu, jeśli istnieje.

ComPtr::Swap

Wymienia interfejs zarządzany przez bieżący ComPtr interfejs za pomocą interfejsu zarządzanego przez określony ComPtrelement .

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

Parametry

r
Klasa ComPtr.