Metodo IDataObject::D Advise (objidl.h)

  • Articolo

Chiamato da un oggetto che supporta un sink consigliato per creare una connessione tra un oggetto dati e il sink di consigli. Ciò consente al sink di consigliare di ricevere una notifica delle modifiche nei dati dell'oggetto.

Sintassi

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

Parametri

[in] pformatetc

Puntatore a una struttura FORMATETC che definisce il formato, il dispositivo di destinazione, l'aspetto e il supporto che verranno usati per le notifiche future. Ad esempio, è possibile che un sink desideri sapere solo quando la rappresentazione bitmap dei dati dell'oggetto dati viene modificata. Un altro sink potrebbe essere interessato solo al formato di metafile dello stesso oggetto. Ogni sink di notifica viene notificato quando i dati di interesse vengono modificati. Questi dati vengono passati nuovamente al sink di notifica quando si verifica la notifica.

[in] advf

Gruppo di flag per controllare la connessione consultiva. I valori possibili provengono dall'enumerazione ADVF . Tuttavia, solo alcuni dei possibili valori ADVF sono rilevanti per questo metodo. La tabella seguente descrive brevemente i valori pertinenti.

Valore ADVF Descrizione
ADVF_NODATA Chiede all'oggetto dati di evitare l'invio di dati con le notifiche. In genere, i dati vengono inviati. Questo flag è un modo per eseguire l'override del comportamento predefinito. Quando viene usato ADVF_NODATA, il membro tymed della struttura STGMEDIUM passato a OnDataChange in genere conterrà TYMED_NULL. Il chiamante può quindi recuperare i dati con una chiamata IDataObject::GetData.
ADVF_ONLYONCE Causa l'eliminazione della connessione consultiva dopo l'invio della prima notifica di modifica. Viene effettuata una chiamata implicita a IDataObject::D Unadvise per conto del chiamante per rimuovere la connessione.
ADVF_PRIMEFIRST Richiede una notifica iniziale aggiuntiva. La combinazione di ADVF_ONLYONCE e ADVF_PRIMEFIRST fornisce, in effetti, una chiamata IDataObject::GetData.
ADVF_DATAONSTOP Se specificato con ADVF_NODATA, questo flag causa l'invio di un'ultima notifica con i dati inclusi prima dell'eliminazione dell'oggetto dati.

Se usato senza ADVF_NODATA, DAdvise può essere implementato in uno dei modi seguenti:

  • Il ADVF_DATAONSTOP può essere ignorato.
  • L'oggetto può comportarsi come se ADVF_NODATA specificato.
Una notifica di modifica viene inviata solo nel caso di arresto. Le modifiche ai dati prima dell'arresto non causano l'invio di una notifica.

[in] pAdvSink

Puntatore all'interfaccia IAdviseSink nel sink di consulenza che riceverà la notifica delle modifiche.

[out] pdwConnection

Token che identifica questa connessione. È possibile usare questo token in un secondo momento per eliminare la connessione consultiva (passandola a IDataObject::D Unadvise). Se questo valore è 0, la connessione non è stata stabilita.

Valore restituito

Questo metodo restituisce S_OK se l'operazione ha esito positivo. Altri valori possibili includono quanto segue.

Codice restituito Descrizione
E_NOTIMPL
 Questo metodo non è implementato nell'oggetto dati.
DV_E_LINDEX
 Il valore per lindex non è valido; attualmente è supportato solo -1.
DV_E_FORMATETC
 Il valore per pformatetc non è valido.
OLE_E_ADVISENOTSUPPORTED
 L'oggetto dati non supporta la notifica delle modifiche.

Commenti

DAdvise crea una connessione di notifica di modifica tra un oggetto dati e il chiamante. Il chiamante fornisce un sink di consulenza a cui è possibile inviare le notifiche quando cambiano i dati dell'oggetto.

Gli oggetti usati semplicemente per il trasferimento dei dati in genere non supportano notifiche di consulenza e restituiscono OLE_E_ADVISENOTSUPPORTED da DAdvise.

Note ai chiamanti

L'oggetto che supporta il sink consigliato chiama DAdvise per configurare la connessione, specificando il formato, l'aspetto, il medio e/o il dispositivo di destinazione di interesse nella struttura FORMATETC passato. Se l'oggetto dati non supporta uno o più degli attributi richiesti o l'invio di notifiche, può rifiutare la connessione restituendo OLE_E_ADVISENOTSUPPORTED.

I contenitori di oggetti collegati possono configurare connessioni di consulenza direttamente con l'origine collegamento associata o indirettamente tramite l'oggetto di collegamento OLE standard che gestisce la connessione. Connections configurato con l'origine del collegamento associato non vengono eliminati automaticamente. Il contenitore deve chiamare in modo esplicito IDataObject::D Unadvise sull'origine del collegamento associato per eliminare una connessione consultiva. L'oggetto collegamento OLE, modificato tramite l'interfaccia IOleLink , viene implementato nel gestore predefinito. Connections configurato tramite l'oggetto collegamento OLE vengono eliminati quando l'oggetto link viene eliminato.

L'oggetto collegamento predefinito OLE crea un "avviso jolly" con l'origine collegamento in modo che OLE possa mantenere l'ora dell'ultima modifica. Questo consiglio viene usato specificamente per notare l'ora in cui qualsiasi cosa è cambiata. OLE ignora tutti i formati di dati che potrebbero essere stati modificati, notando solo l'ora dell'ultima modifica. Per consentire consigli jolly, impostare i membri FORMATETC come indicato di seguito prima di chiamare DAdvise:

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

I flag di consulenza devono includere anche ADVF_NODATA. I caratteri jolly consigliano sempre da OLE di essere accettati dalle applicazioni.

Note per gli implementatori

Per semplificare l'implementazione di DAdvise e degli altri metodi di notifica in IDataObject (DUnadvise e EnumDAdvise) che supporta la notifica, OLE fornisce un oggetto di consulenza che gestisce la registrazione e l'invio di notifiche. Per ottenere un puntatore a questo oggetto, chiamare la funzione helper CreateDataAdviseHolder nella prima chiamata di DAdvise. In questo modo viene fornito un puntatore all'interfaccia IDataAdviseHolder dell'oggetto. Delegare quindi la chiamata al metodo IDataAdviseHolder::Advise nel titolare del consiglio dati, che crea e gestisce successivamente la connessione richiesta.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione objidl.h

Vedi anche

CreateDataAdviseHolder

IAdviseSink::OnDataChange

Idataobject