Método IDataObject::D Advise (objidl.h)
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:
|
[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 |
|---|---|
|
Este método não é implementado no objeto de dados. |
|
O valor de lindex não é válido; Atualmente, há suporte apenas para -1. |
|
O valor de pformatetc não é válido. |
|
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 |