IDataObject ::D Advise, méthode (objidl.h)

Article
08/25/2023

Appelé par un objet prenant en charge un récepteur d’avis pour créer une connexion entre un objet de données et le récepteur de conseil. Cela permet au récepteur d’avis d’être informé des modifications apportées aux données de l’objet.

Syntaxe

HRESULT DAdvise(
  [in]  FORMATETC   *pformatetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvSink,
  [out] DWORD       *pdwConnection
);

Paramètres

[in] pformatetc

Pointeur vers une structure FORMATETC qui définit le format, l’appareil cible, l’aspect et le support qui seront utilisés pour les notifications futures. Par exemple, un récepteur n'a besoin d'être informé que lorsque la représentation de bitmap des données est modifiée dans l'objet de données. Un autre récepteur peut être intéressé seulement par le format de métafichier du même objet. Chaque récepteur de notifications est averti lorsque les données d'intérêt changent. Ces données sont retournées au récepteur de notifications lorsqu'une notification se produit.

[in] advf

Groupe d’indicateurs pour le contrôle de la connexion d’avis. Les valeurs possibles proviennent de l’énumération ADVF . Toutefois, seules quelques-unes des valeurs ADVF possibles sont pertinentes pour cette méthode. Le tableau suivant décrit brièvement les valeurs pertinentes.

Valeur ADVF	Description
ADVF_NODATA	Demande à l’objet de données d’éviter d’envoyer des données avec les notifications. En règle générale, les données sont envoyées. Cet indicateur est un moyen de remplacer le comportement par défaut. Lorsque ADVF_NODATA est utilisé, le membre lié de la structure STGMEDIUM transmis à OnDataChange contient généralement TYMED_NULL. L’appelant peut ensuite récupérer les données avec un appel IDataObject ::GetData suivant.
ADVF_ONLYONCE	Entraîne la destruction de la connexion d’avis après l’envoi de la première notification de modification. Un appel implicite à IDataObject ::D Unadvise est effectué au nom de l’appelant pour supprimer la connexion.
ADVF_PRIMEFIRST	Demande une notification initiale supplémentaire. La combinaison de ADVF_ONLYONCE et de ADVF_PRIMEFIRST fournit, en effet, un appel IDataObject ::GetData asynchrone.
ADVF_DATAONSTOP	Lorsqu’il est spécifié avec ADVF_NODATA, cet indicateur entraîne l’envoi d’une dernière notification avec les données incluses avant la destruction de l’objet de données. S’il est utilisé sans ADVF_NODATA, DAdvise peut être implémenté de l’une des manières suivantes : Le ADVF_DATAONSTOP peut être ignoré. L’objet peut se comporter comme si ADVF_NODATA était spécifié. Une notification de modification est envoyée uniquement dans le cas d’arrêt. Les modifications de données avant l’arrêt n’entraînent pas l’envoi d’une notification.

[in] pAdvSink

Pointeur vers l’interface IAdviseSink sur le récepteur d’avis qui recevra la notification de modification.

[out] pdwConnection

Jeton qui identifie cette connexion. Vous pouvez utiliser ce jeton ultérieurement pour supprimer la connexion de conseil (en le transmettant à IDataObject ::D Unadvise). Si cette valeur est 0, la connexion n’a pas été établie.

Valeur retournée

Cette méthode retourne S_OK en cas de réussite. Les autres valeurs possibles sont les suivantes.

Code de retour	Description
E_NOTIMPL	Cette méthode n'est pas implémentée sur l'objet de données.
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_ADVISENOTSUPPORTED	L'objet de données ne prend pas en charge la notification de modifications.

Remarques

DAdvise crée une connexion de notification de modification entre un objet de données et l’appelant. L’appelant fournit un récepteur d’avis auquel les notifications peuvent être envoyées lorsque les données de l’objet changent.

Les objets utilisés simplement pour le transfert de données ne prennent généralement pas en charge les notifications d’avis et ne retournent OLE_E_ADVISENOTSUPPORTED à partir de DAdvise.

Notes aux appelants

L’objet prenant en charge le récepteur d’avis appelle DAdvise pour configurer la connexion, en spécifiant le format, l’aspect, le support et/ou l’appareil cible d’intérêt dans la structure FORMATETC transmise. Si l’objet de données ne prend pas en charge un ou plusieurs attributs demandés ou l’envoi de notifications, il peut refuser la connexion en retournant OLE_E_ADVISENOTSUPPORTED.

Les conteneurs d’objets liés peuvent configurer des connexions d’avis directement avec la source de lien liée ou indirectement via l’objet de lien OLE standard qui gère la connexion. Connections configurés avec la source de lien lié ne sont pas automatiquement supprimés. Le conteneur doit appeler explicitement IDataObject ::D Unadvise sur la source de lien liée pour supprimer une connexion d’avis. L’objet ole link, manipulé via l’interface IOleLink , est implémenté dans le gestionnaire par défaut. Connections configurés via l’objet de lien OLE sont détruits lorsque l’objet link est supprimé.

L’objet de lien par défaut OLE crée un « avertissement générique » avec la source de lien afin qu’OLE puisse conserver l’heure du dernier changement. Ce conseil est spécifiquement utilisé pour noter l’heure à laquelle quelque chose a changé. OLE ignore tous les formats de données qui peuvent avoir changé, en notant uniquement l’heure de la dernière modification. Pour autoriser les conseils génériques, définissez les membres FORMATETC comme suit avant d’appeler DAdvise :

cf == 0; 
ptd == NULL; 
dwAspect == -1; 
lindex == -1 
tymed == -1;

Les indicateurs de conseil doivent également inclure ADVF_NODATA. Les conseils génériques d’OLE doivent toujours être acceptés par les applications.

Notes aux implémenteurs

Pour simplifier l’implémentation de DAdvise et des autres méthodes de notification dans IDataObject (DUnadvise et EnumDAdvise) qui prennent en charge la notification, OLE fournit un objet de titulaire de conseils qui gère l’inscription et l’envoi de notifications. Pour obtenir un pointeur vers cet objet, appelez la fonction d’assistance CreateDataAdviseHolder lors du premier appel de DAdvise. Cela fournit un pointeur vers l’interface IDataAdviseHolder de l’objet. Ensuite, déléguez l’appel à la méthode IDataAdviseHolder ::Advise dans le titulaire du conseil de données, qui crée, puis gère, la connexion demandée.

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

CreateDataAdviseHolder

IAdviseSink ::OnDataChange

Idataobject