winrt::com_ptr, modèle de struct (C++/WinRT)
Modèle de pointeur intelligent COM compté en référence. com_ptr représente un pointeur vers le type d’implémentation de l’interface ou de la classe runtime 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 Interface, ou type d’implémentation de classe runtime, pointeur vers lequel est représenté par le com_ptr. Il s’agit du type de cible du pointeur intelligent.
Configuration requise
Kit de développement logiciel (SDK) minimum pris en charge : Kit de développement logiciel (SDK) Windows version 10.0.17134.0 (Windows 10, version 1803)
Espace de noms : winrt
En-tête : %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (inclus par défaut)
Alias de type membre
| Nom d'alias | Type |
|---|---|
| com_ptr::type | Synonyme d’une représentation définie par l’implémentation du paramètre de typename T modèle. |
Constructeurs
| Constructeur | Description |
|---|---|
| constructeur com_ptr::com_ptr | Initialise une nouvelle instance du struct de com_ptr, éventuellement avec une copie ou un déplacement des données d’entrée. |
Fonctions Membre
| Fonction | Description |
|---|---|
| fonction com_ptr::as | Retourne l’interface demandée, si elle est prise en charge. Lève si ce n’est pas le cas. |
| com_ptr::attach, fonction | S’attache à un pointeur brut qui possède une référence à sa cible ; aucune référence supplémentaire n’est ajoutée. |
| fonction com_ptr::capture | Appelle une fonction ou une méthode spécifiée (appelant automatiquement winrt::check_hresult ) et capture le pointeur d’interface qui est généré par la fonction ou la méthode en tant void**que . |
| fonction com_ptr::copy_from | Copie à partir d’un autre pointeur. Décrémente le nombre de références sur toute 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 renvoyer à 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 les méthodes COM) qui retournent des références en tant que paramètres de sortie 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 les méthodes COM) qui retournent des références en tant que paramètres sortants via un pointeur vers un pointeur vers void. |
| com_ptr::try_as, fonction | Retourne l’interface demandée, si elle est prise en charge. Retourne nullptrou , si falsece 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 à la place retourne si true elle réussit ou false si ce n’est pas le cas. |
Opérateurs membres
| Opérateur | Description |
|---|---|
| bool com_ptr::operator | Vérifie si le pointeur intelligent 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 passer à 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 ou de l’objet référencé, 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 ; aucune référence supplémentaire n’est 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. |
| 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 à l’opérateur) | Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt dans la 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 dans la mémoire 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 objet. |
| opérateur> (supérieur à l’opérateur) | 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 ou au même emplacement que celui du deuxième paramètre. |
constructeur com_ptr::com_ptr
Initialise une nouvelle instance du struct de com_ptr, éventuellement avec une copie ou un déplacement des données d’entrée.
Le void* constructeur 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 maintenant transféré vers le com_ptr. Le nombre de références 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 Type cible pointé vers 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 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 rechercher 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 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).
com_ptr::attach, fonction
S’attache à un pointeur brut qui possède une référence à sa cible ; aucune référence supplémentaire n’est 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 (en 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**.
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.
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.
Notes
- 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’appelant) 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 (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);
com_ptr::copy_from, fonction
Copie à partir d’un autre pointeur. Décrémente le nombre de références sur une interface ou un 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 .
com_ptr::copy_to, fonction
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 cette interface ou l’adresse mémoire de cet 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 lequel 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 retourner à un appelant.
Syntaxe
T* detach() noexcept;
Valeur renvoyée
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, Release ou QueryInterface sur le pointeur retourné.
Syntaxe
T* get() const noexcept;
Valeur renvoyée
Pointeur vers l’interface ou l’objet référencé par l’objet com_ptr .
com_ptr::p ut, fonction
Retourne l’adresse du pointeur brut sous-jacent ; cette fonction vous aide à appeler des méthodes (telles que les 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-le nullptr à l’objet com_ptr avant d’appeler cette fonction. Sinon, la fonction s’affirmera.
Syntaxe
T** put() noexcept;
Valeur renvoyée
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 permet d’appeler des méthodes (telles que les 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-le nullptr à l’objet com_ptr avant d’appeler cette fonction. Sinon, la fonction s’affirmera.
Syntaxe
void** put_void() noexcept;
Valeur renvoyée
Adresse du pointeur brut sous-jacent en tant que pointeur vers un pointeur vers void.
com_ptr::try_as, fonction
Retourne l’interface demandée, si elle est prise en charge. Retourne nullptr (la autosurcharge -retournant) ou false (la surcharge -retournant), si ce n’est pas le boolcas. Cette fonction est utile si vous souhaitez rechercher 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 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 auto-retournant) ou false (surcharge bool-retour).
com_ptr::try_capture, fonction
Version de com_ptr::capture qui ne lève pas en cas d’échec, mais retourne à la place des retours true en cas de réussite 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 fait pas référence à une interface ou à un objet, il est logiquement null ; sinon, elle n’est logiquement pas null.
Syntaxe
explicit operator bool() const noexcept;
Valeur renvoyée
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 d’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 cible T.
Syntaxe
T& operator*() const noexcept;
Valeur renvoyée
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 Type pointé vers la valeur affectée.
Paramètres
other Valeur com_ptr à affecter à l’objet com_ptr . Le T du paramètre doit être convertible en Tde 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 ou de l’objet référencé, retourne le pointeur brut sous-jacent. Vous ne pouvez pas appeler AddRef ni Release sur le pointeur retourné, mais vous pouvez appeler QueryInterface.
Syntaxe
auto operator->() const noexcept;
Valeur renvoyée
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 qui possède une référence à sa cible ; aucune référence supplémentaire n’est 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 sur lequel opérer.
value Pointeur brut qui possède 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 renvoyer à un appelant.
Syntaxe
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
Paramètres
object Objet com_ptr sur lequel opérer.
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 à l’opérateur)
Retourne une valeur indiquant si la cible du premier paramètre se produit plus tôt 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 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 dans la mémoire 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 du premier paramètre cible 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 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> (supérieur à l’opérateur)
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 du premier paramètre cible 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 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 du premier paramètre cible 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 vers l’échange mutuel avec celui de l’autre paramètre.
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour