Partager via

modèle de struct winrt ::com_ptr (C++/WinRT)

  • Article

Modèle de pointeur intelligent COM compté par référence. com_ptr représente un pointeur vers le type d’implémentation de classe d’interface ou d’exécution spécifié par le paramètre de modèle. Il gère automatiquement le nombre de références pour sa cible via un pointeur brut privé.

Syntaxe

template <typename T>
struct com_ptr

Paramètres de modèle

typename T Type d’implémentation de l’interface ou de la classe runtime, pointeur vers lequel est représenté le com_ptr. Il s’agit du type de la cible du pointeur intelligent.

Exigences

Kit de développement logiciel (SDK) minimum pris en charge : SDK Windows version 10.0.17134.0 (Windows 10, version 1803)

Namespace : winrt

en-tête : %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (inclus par défaut)

Alias de type membre

Nom de l’alias Type
com_ptr ::type Synonyme d’une représentation définie par l’implémentation du paramètre de modèle typename T.

Constructeurs

Constructeur Description
com_ptr ::com_ptr constructeur Initialise une nouvelle instance du struct com_ptr, éventuellement avec une copie ou un déplacement des données d’entrée.

Fonctions membres

Fonction Description
com_ptr ::as, fonction Retourne l’interface demandée, si elle est prise en charge. Lève si ce n’est pas le cas.
de fonction com_ptr :attach Joint à un pointeur brut qui possède une référence à sa cible ; une référence supplémentaire n’est pas ajoutée.
com_ptr ::capture, fonction Appelle une fonction ou une méthode spécifiée (appelant automatiquement winrt ::check_hresult dessus) et capture le pointeur d’interface qui est sortie de la fonction ou de la méthode en tant que void**.
de fonction com_ptr ::copy_from Copie à partir d’un autre pointeur. Décrémente le nombre de références sur n’importe quelle interface ou objet actuellement référencé, copie le paramètre de pointeur brut et commence à gérer la durée de vie de l’interface ou de l’objet vers lequel il pointe.
com_ptr ::copy_to fonction Copie vers un autre pointeur de l’objet com_ptr. Incrémente le nombre de références sur n’importe quelle interface ou objet actuellement référencé, et copie l’adresse mémoire de l’interface ou de l’objet dans le paramètre.
com_ptr ::d etach, fonction Détache de l’interface ou de l’objet référencé sans décrémenter le nombre de références, peut-être pour le renvoyer à un appelant.
com_ptr ::get, fonction Retourne le pointeur brut sous-jacent si vous devez le passer à une fonction.
de fonction com_ptr ::p ut Retourne l’adresse du pointeur brut sous-jacent ; cette fonction vous aide à appeler des méthodes (telles que des méthodes COM) qui retournent des références en tant que paramètres sortants via un pointeur vers un pointeur.
com_ptr ::p ut_void, fonction Retourne l’adresse du pointeur brut sous-jacent en tant que pointeur vers un pointeur vers void; cette fonction vous aide à appeler des méthodes (telles que des méthodes COM) qui retournent des références en tant que paramètres sortants via un pointeur vers void.
de fonction com_ptr ::try_as Retourne l’interface demandée, si elle est prise en charge. Retourne nullptr, ou false, si ce n’est pas le cas.
fonction com_ptr ::try_capture Une version de com_ptr ::capture qui ne lève pas en cas d’échec, mais retourne plutôt true si elle réussit ou false si ce n’est pas le cas.

Opérateurs membres

Opérateur Description
com_ptr ::operator bool Vérifie si le pointeur intelligent fait référence ou non à une interface ou à un objet.
com_ptr ::operator* (opérateur indirection) Renvoie une référence à la cible du com_ptrafin que vous puissiez le transmettre à une fonction qui attend une référence au type cible T.
com_ptr ::operator= (opérateur d’affectation) Affecte une valeur à l’objet com_ptr.
com_ptr ::operator-> (opérateur de flèche) Pour permettre l’accès aux méthodes de l’interface référencée ou de l’objet, retourne le pointeur brut sous-jacent.

Fonctions gratuites

Fonction Description
attach_abi fonction Attache un objet com_ptr à un pointeur brut qui possède une référence à sa cible ; une référence supplémentaire n’est pas ajoutée.
detach_abi fonction Détache un objet com_ptr de son interface brute sans décrémenter le nombre de références, peut-être pour le renvoyer à un appelant.
fonction d’échange Échange le contenu des deux paramètres com_ptr afin qu’ils pointent vers la cible d’un autre.

Opérateurs gratuits

Fonction Description
operator != (opérateur d’inégalité) Retourne une valeur indiquant si les deux paramètres font référence à des cibles différentes.
opérateur< (opérateur inférieur à) Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt en mémoire que celle du deuxième paramètre.
opérateur<= (opérateur inférieur ou égal à) Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt en mémoire que, ou au même emplacement que celui du deuxième paramètre.
operator== (opérateur d’égalité) Retourne une valeur indiquant si les deux paramètres font référence à la même interface et/ou à l’objet.
opérateur> (opérateur supérieur à) Retourne une valeur indiquant si la cible du premier paramètre se produit plus tard dans la mémoire que celle du deuxième paramètre.
opérateur>= (opérateur supérieur ou égal à) Retourne une valeur indiquant si la cible du premier paramètre se produit plus tard dans la mémoire que, ou au même emplacement que celui du deuxième paramètre.

constructeur com_ptr ::com_ptr

Initialise une nouvelle instance du struct com_ptr, éventuellement avec une copie ou un déplacement des données d’entrée.

Le constructeur void* prend un T*, et assume la propriété. winrt ::take_ownership_from_abi_t est un type de marqueur qui rend explicite la responsabilité de libérer ce pointeur est désormais transférée vers le com_ptr. Le refcount n’a pas besoin d’être exactement 1 ; c’est juste dire que la responsabilité est transférée.

Syntaxe

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;

Paramètres de modèle

typename U Le type cible pointé par le pointeur intelligent d’entrée.

Paramètres

other un autre com_ptr qui initialise l’objet com_ptr. Le T du paramètre doit être convertible en Tde l’objet com_ptr.

com_ptr ::as, fonction

Retourne l’interface demandée, si elle est prise en charge. Lève si ce n’est pas le cas. Cette fonction est utile si vous souhaitez interroger une interface que vous n’avez pas besoin de renvoyer à votre appelant.

Pour obtenir des exemples de code, consultez la section instanciation et retour de types et d’interfaces projetés, ainsi que d’autres sections de cette rubrique.

Syntaxe

template <typename To> auto as() const;
template <typename To> void as(To& to) const;

Paramètres de modèle

typename To Type de l’interface demandée.

Paramètres

to Référence à une valeur pour recevoir l’interface demandée.

Valeur de retour

Un com_ptr référençant l’interface demandée, ou un pointeur intelligent fortement typé pour l’interface demandée (déclaré par C++/WinRT ou par un tiers).

com_ptr ::attach, fonction

Joint à un pointeur brut qui possède une référence à sa cible ; une référence supplémentaire n’est pas ajoutée. Si nécessaire, vous pouvez utiliser cette fonction pour fusionner les références.

Syntaxe

void attach(T* value) noexcept;

Paramètres

value pointeur brut qui possède une référence à sa cible.

com_ptr ::capture, fonction

Appelle une fonction ou une méthode spécifiée (appelant automatiquement winrt ::check_hresult dessus) et capture le pointeur d’interface qui est sortie de la fonction ou de la méthode en tant que void**.

Consultez également le modèle de fonction winrt ::capture.

Syntaxe

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

Paramètres de modèle

typename F type d’objet de fonction, tel qu’une fonction libre, ou std ::function.

typename O type d’interface.

typename M type de méthode A.

typename Args types d’arguments Zéro ou plus.

Paramètres

function objet de fonction de type F.

p Pointeur vers un objet de type O.

object A winrt ::com_ptr de type O.

method méthode A (implémentée par O) de type M.

args Zéro ou plus d’arguments de type Args.

Remarques

  • La surcharge capture(F function, Args&&...args) appelle l’objet de fonction.
  • La surcharge capture(O* p, M method, Args&& ...args) appelle la méthode sur le pointeur.
  • La surcharge capture(winrt::com_ptr<O> const& object, M method, Args&&...args) appelle la méthode sur l’objet.

Toutes les surcharges passent (à l’appelant) tous les arguments supplémentaires que vous fournissez. Toutes les surcharges transmettent également les deux arguments supplémentaires requis par ces appels , en particulier, un REFIID (l’ID de la cible du winrt ::com_ptr), et un void** (adresse d’un pointeur vers la cible du winrt ::com_ptr).

Exemple

winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);

fonction com_ptr ::copy_from

Copie à partir d’un autre pointeur. Décrémente le nombre de références sur n’importe quelle interface ou objet actuellement référencé, copie le paramètre de pointeur brut et commence à gérer la durée de vie de l’interface ou de l’objet vers lequel il pointe.

Syntaxe

void copy_from(T* other) noexcept;

Paramètres

other Pointeur brut vers une cible dont la durée de vie doit être gérée par l’objet com_ptr.

fonction com_ptr ::copy_to

Copie vers un autre pointeur de l’objet com_ptr. Incrémente le nombre de références sur n’importe quelle interface ou objet actuellement référencé, et copie l’adresse mémoire de l’interface ou de l’objet dans le paramètre. Cette fonction vous permet de transmettre une référence à la même interface sans appeler QueryInterface.

Syntaxe

void copy_to(T** other) const noexcept;

Paramètres

other'adresse d’un pointeur brut ; dans laquelle copier le pointeur vers la cible de l’objet com_ptr.

fonction com_ptr ::d etach

Détache de l’interface ou de l’objet référencé sans décrémenter le nombre de références, peut-être pour le renvoyer à un appelant.

Syntaxe

T* detach() noexcept;

Valeur de retour

Pointeur vers l’interface ou l’objet référencé par l’objet com_ptr.

com_ptr ::get, fonction

Retourne le pointeur brut sous-jacent si vous devez le passer à une fonction. Vous pouvez appeler AddRef, Releaseou QueryInterface sur le pointeur retourné.

Syntaxe

T* get() const noexcept;

Valeur de retour

Pointeur vers l’interface ou l’objet référencé par l’objet com_ptr.

fonction com_ptr ::p ut

Retourne l’adresse du pointeur brut sous-jacent ; cette fonction vous aide à appeler des méthodes (telles que des méthodes COM) qui retournent des références en tant que paramètres sortants via un pointeur vers un pointeur. Si l’objet com_ptr a déjà une cible, affectez nullptr à l’objet com_ptr avant d’appeler cette fonction, sinon la fonction s’affirme.

Syntaxe

T** put() noexcept;

Valeur de retour

Adresse du pointeur brut sous-jacent.

fonction com_ptr ::p ut_void

Retourne l’adresse du pointeur brut sous-jacent en tant que pointeur vers un pointeur vers void; cette fonction vous aide à appeler des méthodes (telles que des méthodes COM) qui retournent des références en tant que paramètres sortants via un pointeur vers void. Si l’objet com_ptr a déjà une cible, affectez nullptr à l’objet com_ptr avant d’appeler cette fonction, sinon la fonction s’affirme.

Syntaxe

void** put_void() noexcept;

Valeur de retour

Adresse du pointeur brut sous-jacent en tant que pointeur vers un pointeur vers void.

fonction com_ptr ::try_as

Retourne l’interface demandée, si elle est prise en charge. Retourne nullptr (surcharge de retour de auto) ou false (surcharge de retour de bool), si ce n’est pas le cas. Cette fonction est utile si vous souhaitez interroger une interface que vous n’avez pas besoin de renvoyer à votre appelant.

Syntaxe

template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;

Paramètres de modèle

typename To Type de l’interface demandée.

Paramètres

to Référence à une valeur pour recevoir l’interface demandée.

Valeur de retour

Un com_ptr référençant l’interface demandée ou un pointeur intelligent fortement typé pour l’interface demandée (déclaré par C++/WinRT ou par un tiers), si l’interface demandée est prise en charge, sinon nullptr (la surcharge auto-retour) ou false (surcharge de retour de bool).

fonction com_ptr ::try_capture

Une version de com_ptr ::capture qui ne lève pas en cas d’échec, mais retourne plutôt true si elle réussit ou false si ce n’est pas le cas.

Consultez également le modèle de fonction winrt ::try_capture.

com_ptr ::operator bool

Vérifie si le pointeur intelligent fait référence ou non à une interface ou à un objet. Si le pointeur intelligent ne référence pas une interface ou un objet, il est logiquement null ; sinon, il n’est pas logiquement null.

Syntaxe

explicit operator bool() const noexcept;

Valeur de retour

true si le pointeur intelligent fait référence à une interface ou à un objet (logiquement non null), sinon false (logiquement null).

com_ptr ::operator* (opérateur indirection)

Renvoie une référence à la cible du com_ptrafin que vous puissiez le transmettre à une fonction qui attend une référence au type cible T.

Syntaxe

T& operator*() const noexcept;

Valeur de retour

Référence à la cible du com_ptr.

com_ptr ::operator= (opérateur d’affectation)

Affecte une valeur à l’objet com_ptr.

Syntaxe

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;

Paramètres de modèle

typename U Le type pointé par la valeur affectée.

Paramètres

other valeur de com_ptr à affecter à l’objet com_ptr. Le T du paramètre doit être convertible en Tde l’objet com_ptr.

Valeur de retour

Référence à l’objet com_ptr.

com_ptr ::operator-> (opérateur de flèche)

Pour permettre l’accès aux méthodes de l’interface référencée ou de l’objet, retourne le pointeur brut sous-jacent. Vous n’appelez peut-être pas AddRef ni version sur le pointeur retourné, mais vous pouvez appeler QueryInterface.

Syntaxe

auto operator->() const noexcept;

Valeur de retour

Pointeur vers l’interface ou l’objet référencé par l’objet com_ptr.

fonction attach_abi

Attache un objet com_ptr à un pointeur brut qui possède une référence à sa cible ; une référence supplémentaire n’est pas ajoutée. Si nécessaire, vous pouvez utiliser cette fonction pour fusionner les références.

Syntaxe

void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;

Paramètres

object objet com_ptr à utiliser.

value pointeur brut qui possède une référence à sa cible.

fonction detach_abi

Détache un objet com_ptr de son interface brute sans décrémenter le nombre de références, peut-être pour le renvoyer à un appelant.

Syntaxe

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

Paramètres

object objet com_ptr à utiliser.

Valeur de retour

Pointeur vers l’interface brute référencée par l’objet com_ptr.

operator != (opérateur d’inégalité)

Retourne une valeur indiquant si les deux paramètres font référence à des cibles différentes.

Syntaxe

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;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si les deux paramètres pointent vers des cibles différentes, sinon false.

opérateur< (opérateur inférieur à)

Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt en mémoire que celle du deuxième paramètre.

Syntaxe

template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si l’adresse mémoire de la cible du premier paramètre est inférieure à celle du deuxième paramètre, sinon false.

opérateur<= (opérateur inférieur ou égal à)

Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt en mémoire que, ou au même emplacement que celui du deuxième paramètre.

Syntaxe

template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si l’adresse mémoire du premier paramètre est inférieure ou égale à celle du deuxième paramètre, sinon false.

operator== (opérateur d’égalité)

Retourne une valeur indiquant si les deux paramètres font référence à la même interface et/ou à l’objet.

Syntaxe

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;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si les deux paramètres pointent vers la même cible, sinon false.

opérateur> (opérateur supérieur à)

Retourne une valeur indiquant si la cible du premier paramètre se produit plus tard dans la mémoire que celle du deuxième paramètre.

Syntaxe

template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si l’adresse mémoire de la cible du premier paramètre est supérieure à celle du deuxième paramètre, sinon false.

opérateur>= (opérateur supérieur ou égal à)

Retourne une valeur indiquant si la cible du premier paramètre se produit plus tard dans la mémoire que, ou au même emplacement que celui du deuxième paramètre.

Syntaxe

template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;

Paramètres

left right Valeur de com_ptr dont l’adresse mémoire de la cible doit être comparée à celle de l’autre paramètre.

Valeur de retour

true si l’adresse mémoire de la cible du premier paramètre est supérieure ou égale à celle du deuxième paramètre, sinon false.

swap, fonction

Échange le contenu des deux paramètres com_ptr afin qu’ils pointent vers la cible d’un autre.

Syntaxe

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

Paramètres

left right Valeur com_ptr dont le pointeur doit s’échanger mutuellement avec celui de l’autre paramètre.

Voir aussi