IDataObject ::D Advise, méthode (objidl.h)
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 :
|
[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 |
|---|---|
|
Cette méthode n'est pas implémentée sur l'objet de données. |
|
La valeur de lindex n’est pas valide ; Actuellement, seul -1 est pris en charge. |
|
La valeur de pformatetc n’est pas valide. |
|
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 |