Método IDataObject::D Advise (objidl.h)

  • Artigo

Chamado por um objeto que dá suporte a um coletor de aconselhamento para criar uma conexão entre um objeto de dados e o coletor de aconselhamento. Isso permite que o coletor de aconselhamento seja notificado sobre alterações nos dados do objeto.

Sintaxe

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

Parâmetros

[in] pformatetc

Um ponteiro para uma estrutura FORMATETC que define o formato, o dispositivo de destino, o aspecto e o meio que serão usados para notificações futuras. Por exemplo, talvez um coletor queira saber somente quando a representação de bitmap dos dados no objeto de dados for alterada. Outro coletor pode estar interessado apenas no formato de metarquivo do mesmo objeto. Cada coletor de consultoria é notificado quando os dados de interesse são alterados. Esses dados são passados de volta para o coletor de avisos quando a notificação ocorre.

[in] advf

Um grupo de sinalizadores para controlar a conexão de consultoria. Os valores possíveis são da enumeração ADVF . No entanto, apenas alguns dos valores possíveis do ADVF são relevantes para esse método. A tabela a seguir descreve brevemente os valores relevantes.

Valor do ADVF Descrição
ADVF_NODATA Solicita que o objeto de dados evite enviar dados com as notificações. Normalmente, os dados são enviados. Esse sinalizador é uma maneira de substituir o comportamento padrão. Quando ADVF_NODATA é usado, o membro tymed da estrutura STGMEDIUM que é passada para OnDataChange geralmente conterá TYMED_NULL. Em seguida, o chamador pode recuperar os dados com uma chamada IDataObject::GetData subsequente.
ADVF_ONLYONCE Faz com que a conexão de consultoria seja destruída após o envio da primeira notificação de alteração. Uma chamada implícita para IDataObject::D Unadvise é feita em nome do chamador para remover a conexão.
ADVF_PRIMEFIRST Solicita uma notificação inicial adicional. A combinação de ADVF_ONLYONCE e ADVF_PRIMEFIRST fornece, de fato, uma chamada IDataObject::GetData assíncrona.
ADVF_DATAONSTOP Quando especificado com ADVF_NODATA, esse sinalizador faz com que uma última notificação com os dados incluídos sejam enviados antes que o objeto de dados seja destruído.

Se usado sem ADVF_NODATA, o DAdvise pode ser implementado de uma das seguintes maneiras:

  • O ADVF_DATAONSTOP pode ser ignorado.
  • O objeto pode se comportar como se ADVF_NODATA fosse especificado.
Uma notificação de alteração é enviada somente no caso de desligamento. As alterações de dados antes do desligamento não fazem com que uma notificação seja enviada.

[in] pAdvSink

Um ponteiro para a interface IAdviseSink no coletor de consultoria que receberá a notificação de alteração.

[out] pdwConnection

Um token que identifica essa conexão. Você pode usar esse token posteriormente para excluir a conexão de consultoria (passando-a para IDataObject::D Unadvise). Se esse valor for 0, a conexão não foi estabelecida.

Retornar valor

Esse método retorna S_OK com êxito. Outros valores possíveis incluem o seguinte.

Código de retorno Descrição
E_NOTIMPL
 Este método não é implementado no objeto de dados.
DV_E_LINDEX
 O valor de lindex não é válido; Atualmente, há suporte apenas para -1.
DV_E_FORMATETC
 O valor de pformatetc não é válido.
OLE_E_ADVISENOTSUPPORTED
 O objeto de dados não é compatível com a notificação de alteração.

Comentários

O DAdvise cria uma conexão de notificação de alteração entre um objeto de dados e o chamador. O chamador fornece um coletor de consultoria para o qual as notificações podem ser enviadas quando os dados do objeto são alterados.

Objetos usados simplesmente para transferência de dados normalmente não dão suporte a notificações de consultoria e retornam OLE_E_ADVISENOTSUPPORTED do DAdvise.

Anotações para chamadores

O objeto que dá suporte ao coletor de consultoria chama DAdvise para configurar a conexão, especificando o formato, aspecto, médio e/ou dispositivo de destino de interesse na estrutura FORMATETC passada. Se o objeto de dados não der suporte a um ou mais atributos solicitados ou ao envio de notificações, ele poderá recusar a conexão retornando OLE_E_ADVISENOTSUPPORTED.

Contêineres de objetos vinculados podem configurar conexões de consultoria diretamente com a origem do link associado ou indiretamente por meio do objeto de link OLE padrão que gerencia a conexão. Connections configurado com a origem do link associado não são excluídos automaticamente. O contêiner deve chamar explicitamente IDataObject::D Unadvise na origem do link associado para excluir uma conexão de consultoria. O objeto de link OLE, manipulado por meio da interface IOleLink , é implementado no manipulador padrão. Connections configurado por meio do objeto de link OLE são destruídos quando o objeto de link é excluído.

O objeto de link padrão OLE cria um "aviso curinga" com a origem do link para que o OLE possa manter a hora da última alteração. Esse aviso é usado especificamente para observar o tempo em que algo mudou. O OLE ignora todos os formatos de dados que podem ter sido alterados, observando apenas a hora da última alteração. Para permitir avisos curinga, defina os membros FORMATETC da seguinte maneira antes de chamar DAdvise:

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

Os sinalizadores de aviso também devem incluir ADVF_NODATA. Os avisos curinga do OLE sempre devem ser aceitos pelos aplicativos.

Anotações aos implementadores

Para simplificar a implementação do DAdvise e dos outros métodos de notificação em IDataObject (DUnadvise e EnumDAdvise) que dá suporte à notificação, o OLE fornece um objeto de titular de consultoria que gerencia o registro e o envio de notificações. Para obter um ponteiro para esse objeto, chame a função auxiliar CreateDataAdviseHolder na primeira invocação de DAdvise. Isso fornece um ponteiro para a interface IDataAdviseHolder do objeto. Em seguida, deducione a chamada para o método IDataAdviseHolder::Advise no titular da consultoria de dados, que cria e gerencia posteriormente a conexão solicitada.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho objidl.h

Confira também

CreateDataAdviseHolder

IAdviseSink::OnDataChange

Idataobject