ComPtr — Klasa
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).
Elementy członkowskie
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 ComPtr elementem . |
ComPtr::GetAddressOf |
Pobiera adres ptr_ elementu członkowskiego danych, który zawiera wskaźnik do interfejsu reprezentowanego przez ten ComPtr element . |
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 ComPtr element . |
Metody chronione
Nazwa/nazwisko | opis |
---|---|
ComPtr::InternalAddRef |
Zwiększa liczbę odwołań interfejsu skojarzonego z tym ComPtr elementem . |
ComPtr::InternalRelease |
Wykonuje operację wydania COM na interfejsie skojarzonym z tym ComPtr elementem . |
Operatory publiczne
Nazwa/nazwisko | opis |
---|---|
ComPtr::operator& |
Pobiera adres bieżącego ComPtr obiektu . |
ComPtr::operator-> |
Pobiera wskaźnik do typu określonego przez bieżący parametr szablonu. |
ComPtr::operator= |
Przypisuje wartość do bieżącego ComPtr elementu . |
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 ComPtr element . |
Hierarchia dziedziczenia
ComPtr
Wymagania
Nagłówek: client.h
Przestrzeń 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 riid
ró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 ComPtr
elementem . 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 ComPtr
elementem .
T* Get() const;
Wartość zwracana
Wskaźnik do interfejsu skojarzonego z tym ComPtr
elementem .
ComPtr::GetAddressOf
Pobiera adres ptr_
elementu członkowskiego danych, który zawiera wskaźnik do interfejsu reprezentowanego przez ten ComPtr
element .
T* const* GetAddressOf() const;
T** GetAddressOf();
Wartość zwracana
Adres zmiennej.
ComPtr::InternalAddRef
Zwiększa liczbę odwołań interfejsu skojarzonego z tym ComPtr
elementem .
void InternalAddRef() const;
Uwagi
Ta metoda jest chroniona.
ComPtr::InternalRelease
Wykonuje operację wydania COM na interfejsie skojarzonym z tym ComPtr
elementem .
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 ComPtr
elementu .
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 ComPtr
elementu .
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 ComPtr
elementu .
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 ComPtr
elementu .
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 ComPtr
elementu .
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 ComPtr
elementu .
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 true
b
; 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 ComPtr
elementem , 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 ComPtr
element .
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 ComPtr
elementu .
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 ComPtr
element .
void Swap(
_Inout_ ComPtr&& r
);
void Swap(
_Inout_ ComPtr& r
);
Parametry
r
Klasa ComPtr
.