IDataObject ::GetCanonicalFormatEtc, méthode (objidl.h)

Article
02/29/2024

Fournit une structure FORMATETC potentiellement différente, mais logiquement équivalente. Vous utilisez cette méthode pour déterminer si deux structures FORMATETC différentes retournent les mêmes données, ce qui supprime la nécessité d’un rendu en double.

Syntaxe

HRESULT GetCanonicalFormatEtc(
  [in]  FORMATETC *pformatectIn,
  [out] FORMATETC *pformatetcOut
);

Paramètres

[in] pformatectIn

Pointeur vers la structure FORMATETC qui définit le format, le support et l’appareil cible que l’appelant souhaite utiliser pour récupérer des données dans un appel suivant tel que IDataObject ::GetData. Le membre lié n’est pas significatif dans ce cas et doit être ignoré.

[out] pformatetcOut

Pointeur vers une structure FORMATETC qui contient les informations les plus générales possibles pour un rendu spécifique, ce qui la rend canoniquement équivalente à pformatetcIn. L’appelant doit allouer cette structure et la méthode GetCanonicalFormatEtc doit renseigner les données. Pour récupérer des données dans un appel suivant comme IDataObject ::GetData, l’appelant utilise la valeur spécifiée de pformatetcOut, sauf si la valeur spécifiée est NULL. Cette valeur est NULL si la méthode retourne DATA_S_SAMEFORMATETC. Le membre lié n’est pas significatif dans ce cas et doit être ignoré.

Valeur retournée

Cette méthode peut retourner les valeurs suivantes.

Code de retour	Description
S_OK	La structure FORMATETC retournée est différente de celle qui a été passée.
DATA_S_SAMEFORMATETC	Les structures FORMATETC sont identiques et NULL est retourné dans pformatetcOut.
DV_E_LINDEX	La valeur de lindex n’est pas valide ; Actuellement, seul -1 est pris en charge.
DV_E_FORMATETC	La valeur de pformatetc n’est pas valide.
OLE_E_NOTRUNNING	L’application objet n’est pas en cours d’exécution.
E_UNEXPECTED	Une erreur inattendue s’est produite.
E_INVALIDARG	Le paramètre dwDirection n’est pas valide.
E_OUTOFMEMORY	La mémoire disponible était insuffisante pour cette opération.

Remarques

Si un objet de données peut fournir exactement les mêmes données pour plusieurs structures FORMATETC demandées, GetCanonicalFormatEtc peut fournir un FORMATETC « canonique » ou standard qui offre le même rendu qu’un ensemble de structures FORMATETC plus complexes. Par exemple, il est courant que les données retournées ne soient pas sensibles à l’appareil cible spécifié dans un ensemble de structures FORMATETC similaires.

Remarques aux appelants

Un appel à cette méthode peut déterminer si deux appels à IDataObject ::GetData sur un objet de données, en spécifiant deux structures FORMATETC différentes, produisent réellement les mêmes rendus, éliminant ainsi la nécessité du deuxième appel et améliorant les performances. Si l’appel à GetCanonicalFormatEtc entraîne l’écriture d’un format canonique dans le paramètre pformatetcOut , l’appelant utilise cette structure dans un appel ultérieur à IDataObject ::GetData.

Remarques aux implémenteurs

D’un point de vue conceptuel, il est possible de penser à des structures FORMATETC dans des groupes définis par un FORMATETC canonique qui fournit les mêmes résultats que chacun des membres du groupe. Lors de la construction du FORMATETC canonique, vous devez vous assurer qu’il contient les informations les plus générales possibles qui produisent toujours un rendu spécifique.

Pour les objets de données qui ne fournissent jamais de rendu spécifique à l’appareil, l’implémentation la plus simple de cette méthode consiste à copier le FORMATETC d’entrée dans la sortie FORMATETC, à stocker une valeur NULL dans le membre ptd du FORMATETC de sortie et à retourner DATA_S_SAMEFORMATETC.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	objidl.h

Voir aussi

Idataobject

Partager via