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

Modèle de pointeur intelligent COM comptabilisé 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é.

Syntax

template <typename T>
struct com_ptr

Paramètres de modèle

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

Spécifications

Sdk minimum pris en charge : Windows SDK version 10.0.17134.0 (Windows 10, version 1803)

Espace de noms : winrt

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

Alias de type de membre

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

Constructeurs

Constructeur Description
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.

Fonctions Membre

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.
fonction com_ptr::attach Attache un pointeur brut qui possède une référence à sa cible ; une référence supplémentaire n’est pas ajoutée.
fonction com_ptr::capture Appelle une fonction ou une méthode spécifiée (appelant automatiquement winrt::check_hresult dessus) et capture le pointeur d’interface qui est généré à partir de la fonction ou de la méthode en tant que void**.
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 pointé par celui-ci.
fonction com_ptr::copy_to Copie vers un autre pointeur à partir 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.
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 retourner à un appelant.
com_ptr::get, fonction Retourne le pointeur brut sous-jacent si vous devez le passer à une fonction.
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.
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 un pointeur vers void.
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 Version de com_ptr::capture qui ne lève pas en cas d’échec, mais retourne à la place une valeur retournée true si elle réussit ou false non.

Opérateurs membres

Opérateur Description
com_ptr::operator bool Vérifie si le pointeur intelligent fait référence à une interface ou un objet.
com_ptr::operator* (opérateur indirection) Retourne une référence à la cible du com_ptr afin que vous puissiez la transmettre à une fonction qui attend une référence au type T cible.
com_ptr::operator= (opérateur d’assignation) 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 propriétaire d’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 retourner à un appelant.
swap, fonction Échange le contenu des deux paramètres com_ptr afin qu’ils pointent vers la cible de l’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.
operator<= (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.
operator>= (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.

Syntax

com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) 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 Type cible vers lequel pointe le pointeur intelligent d’entrée.

Paramètres

other Une autre com_ptr qui initialise l’objet com_ptr . Le T du paramètre doit être convertible en T de 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 transmettre à votre appelant.

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

Syntax

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 retournée

Un com_ptr faisant référence à 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

Attache 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 (appel 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.

Syntax

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.

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

Paramètres

function Objet de fonction de type F.

p Pointeur vers un objet de type O.

objectWinrt::com_ptr de type O.

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

args Zéro ou plusieurs arguments de type Args.

Remarques

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

Toutes les surcharges passent (à l’appel) tous les arguments supplémentaires que vous fournissez. Toutes les surcharges passent également les deux arguments supplémentaires requis par ces appels, en particulier un REFIID (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 pointé vers celui-ci.

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 .

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.

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 transmettre à une fonction. Vous pouvez appeler AddRef, Release ou 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-lui 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.

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 un pointeur vers void. Si l’objet com_ptr a déjà une cible, affectez-lui 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 autode retour) ou false ( boolsurcharge -retour), si ce n’est pas le cas. Cette fonction est utile si vous souhaitez interroger une interface que vous n’avez pas besoin de transmettre à votre appelant.

Syntax

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 retournée

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 (surcharge autode retour) ou false ( boolsurcharge de retour).

fonction com_ptr:try_capture

Une version de com_ptr::capture qui ne lève pas en cas d’échec, mais retourne à la place retourne true si elle réussit ou false non.

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

com_ptr::operator bool

Vérifie si le pointeur intelligent référence 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 référence une interface ou un objet (logiquement non null), sinon false (logiquement null).

com_ptr::operator* (opérateur indirection)

Retourne une référence à la cible du com_ptr afin 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 .

Syntax

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 Type pointé par la valeur affectée.

Paramètres

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

Valeur retournée

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 Release 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 .

attach_abi, fonction

Attache un objet com_ptr à un pointeur brut propriétaire d’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 propriétaire d’une référence à sa cible.

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 retourner à un appelant.

Syntaxe

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

Paramètres

object Objet com_ptr à utiliser.

Valeur retournée

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

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

Valeur retournée

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

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

Valeur retournée

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

operator<= (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

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

Valeur retournée

true si l’adresse mémoire de la cible 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

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

Valeur retournée

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

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

Valeur retournée

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

operator>= (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

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

Valeur retournée

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 de l’autre.

Syntaxe

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

Paramètres

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

Voir aussi