Método IDataAdviseHolder::Advise (objidl.h)

Cria uma conexão entre um coletor de consultoria e um objeto de dados para receber notificações.

Sintaxe

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

Parâmetros

[in] pDataObject

Um ponteiro para a interface IDataObject no objeto de dados para o qual as notificações são solicitadas. Se os dados nesse objeto forem alterados, uma notificação será enviada aos coletores de aviso que solicitaram a notificação.

[in] pFetc

Um ponteiro para uma estrutura FORMATETC que contém o formato, o meio e o dispositivo de destino especificados que é de interesse para o coletor de aviso solicitando notificação. 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 que controlam 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; uma descrição mais detalhada pode ser encontrada na descrição da enumeração ADVF .

Valor	Significado
ADVF_NODATA	Solicita que nenhum dado seja enviado junto com a notificação.
ADVF_ONLYONCE	Faz com que a conexão de consultoria seja destruída após o envio da primeira notificação. Uma chamada implícita para IDataAdviseHolder::Unadvise é feita em nome do chamador para remover a conexão.
ADVF_PRIMEFIRST	Faz com que uma notificação inicial seja enviada independentemente de os dados tiverem sido alterados do estado atual.
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. Quando ADVF_NODATA não é especificado, esse sinalizador não tem efeito.

[in] pAdvise

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

[out] pdwConnection

Um ponteiro para uma variável que recebe um token que identifica essa conexão. O objeto de chamada pode excluir posteriormente a conexão de consultoria passando esse token para IDataAdviseHolder::Unadvise. Se esse valor for zero, a conexão não terá sido estabelecida.

Retornar valor

Esse método retorna S_OK com êxito.

Comentários

Por meio da conexão estabelecida por meio desse método, o coletor de consultoria pode receber notificações futuras em uma chamada para IAdviseSink::OnDataChange.

Um objeto emite uma chamada para IDataObject::D Vise para solicitar notificação sobre alterações no formato, dispositivo médio ou de destino de interesse. Esses dados são especificados no parâmetro pFormatetc . O método DAdvise geralmente é implementado para chamar IDataAdviseHolder::Advise para delegar a tarefa de configurar e rastrear uma conexão com o titular da consultoria. Quando o formato, o dispositivo médio ou de destino em questão é alterado, o objeto de dados chama IDataAdviseHolder::SendOnDataChange para enviar as notificações necessárias.

A conexão estabelecida pode ser excluída passando o valor em pdwConnection em uma chamada para IDataAdviseHolder::Unadvise.

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

IDataAdviseHolder

IDataObject::D Advise