IDataAdviseHolder ::Advise, méthode (objidl.h)

Article
03/04/2024

Crée une connexion entre un récepteur d’avis et un objet de données pour recevoir des notifications.

Syntaxe

HRESULT Advise(
  [in]  IDataObject *pDataObject,
  [in]  FORMATETC   *pFetc,
  [in]  DWORD       advf,
  [in]  IAdviseSink *pAdvise,
  [out] DWORD       *pdwConnection
);

Paramètres

[in] pDataObject

Pointeur vers l’interface IDataObject sur l’objet de données pour lequel des notifications sont demandées. Si les données de cet objet changent, une notification est envoyée aux récepteurs d’avis qui ont demandé la notification.

[in] pFetc

Pointeur vers une structure FORMATETC qui contient le format, le support et l’appareil cible spécifiés qui est d’intérêt pour le récepteur de conseil demandant la notification. 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 qui contrôlent 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 ; une description plus détaillée se trouve dans la description de l’énumération ADVF .

Valeur	Signification
ADVF_NODATA	Demande qu’aucune donnée ne soit envoyée avec la notification.
ADVF_ONLYONCE	Entraîne la destruction de la connexion de conseil après l’envoi de la première notification. Un appel implicite à IDataAdviseHolder ::Unadvise est effectué au nom de l’appelant pour supprimer la connexion.
ADVF_PRIMEFIRST	Provoque l’envoi d’une notification initiale, que les données soient ou non modifiées par rapport à leur état actuel.
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. Lorsque ADVF_NODATA n’est pas spécifié, cet indicateur n’a aucun effet.

[in] pAdvise

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

[out] pdwConnection

Pointeur vers une variable qui reçoit un jeton qui identifie cette connexion. L’objet appelant peut supprimer ultérieurement la connexion d’avis en passant ce jeton à IDataAdviseHolder ::Unadvise. Si cette valeur est nulle, la connexion n'a pas été établie.

Valeur retournée

Cette méthode retourne S_OK en cas de réussite.

Remarques

Grâce à la connexion établie à l’aide de cette méthode, le récepteur d’avis peut recevoir des notifications ultérieures dans un appel à IAdviseSink ::OnDataChange.

Un objet émet un appel à IDataObject ::D Advise pour demander une notification sur les modifications apportées au format, au moyen ou à l’appareil cible qui vous intéresse. Ces données sont spécifiées dans le paramètre pFormatetc . La méthode DAdvise est généralement implémentée pour appeler IDataAdviseHolder ::Advise afin de déléguer la tâche de configuration et de suivi d’une connexion au titulaire de l’avis. Lorsque le format, le moyen ou l’appareil cible en question change, l’objet de données appelle IDataAdviseHolder ::SendOnDataChange pour envoyer les notifications nécessaires.

La connexion établie peut être supprimée en transmettant la valeur dans pdwConnection dans un appel à IDataAdviseHolder ::Unadvise.

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

IDataAdviseHolder

IDataObject ::D Advise

Partager via