IMAPITable::Advise

Aplica-se a: Outlook 2013 | Outlook 2016

Registra um objeto coletor de aconselhamento para receber a notificação de eventos especificados que afetam a tabela.

HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

Parâmetros

ulEventMask

[in] Valor que indica o tipo de evento que gerará a notificação. Somente o valor a seguir é válido:

fnevTableModified

lpAdviseSink

[in] Ponteiro para um objeto coletor de aconselhamento para receber as notificações subsequentes. Esse objeto de coletor de aconselhamento já deve ter sido alocado.

lpulConnection

[out] Ponteiro para um valor não zero que representa o registro de notificação bem-sucedido.

Valor de retorno

S_OK

O registro de notificação foi concluído com êxito.

MAPI_E_NO_SUPPORT

A implementação da tabela não dá suporte a alterações em suas linhas e colunas ou não dá suporte à notificação.

Comentários

Use o método IMAPITable::Advise para registrar um objeto de tabela implementado no provedor para retornos de chamada de notificação. Sempre que ocorre uma alteração no objeto de tabela, o provedor verifica para ver qual bit de máscara de evento foi definido no parâmetro ulEventMask e, portanto, qual tipo de alteração ocorreu. Se um bit for definido, o provedor chamará o método IMAPIAdviseSink::OnNotify para o objeto de coletor de aconselhamento indicado pelo parâmetro lpAdviseSink para relatar o evento. Os dados passados na estrutura de notificação para a rotina OnNotify descrevem o evento.

A chamada para OnNotify pode ocorrer durante a chamada que altera o objeto ou a qualquer momento a seguir. Em sistemas que dão suporte a vários threads de execução, a chamada para OnNotify pode ocorrer em qualquer thread. Para uma maneira de transformar uma chamada para OnNotify que pode acontecer em um momento inoportuno em uma que seja mais segura de lidar, um provedor deve usar a função HrThisThreadAdviseSink .

Para fornecer notificações, o provedor que implementa o Advise precisa manter uma cópia do ponteiro para o objeto de coletor lpAdviseSink ; para fazer isso, ele chama o método IUnknown::AddRef para o coletor de aconselhamento para manter seu ponteiro de objeto até que o registro de notificação seja cancelado com uma chamada para o método IMAPITable::Unadvise . A implementação do Advise deve atribuir um número de conexão ao registro de notificação e chamar AddRef nesse número de conexão antes de devolvê-lo no parâmetro lpulConnection . Os provedores de serviço podem liberar o objeto coletor de aconselhamento antes que o registro seja cancelado, mas eles não devem liberar o número de conexão até que o Unadvise seja chamado.

Depois que uma chamada para Aconselhar tiver sido bem-sucedida e antes de Unadvise ser chamada, os clientes devem estar preparados para que o objeto de coletor de aconselhamento seja liberado. Portanto, um cliente deve liberar seu objeto de coletor de aconselhamento depois que o Advise retornar, a menos que ele tenha um uso específico de longo prazo para ele.

Devido ao comportamento assíncrono da notificação, implementações que alteram as configurações da coluna da tabela podem receber notificações com informações organizadas em uma ordem de coluna anterior. Por exemplo, uma linha de tabela pode ser retornada para uma mensagem que acabou de ser excluída do contêiner. Essa notificação é enviada quando a alteração de configuração de coluna foi feita e informações sobre ela enviadas, mas o modo de exibição da tabela de notificação ainda não foi atualizado com essas informações.

Para obter mais informações sobre o processo de notificação, consulte Notificação de Eventos no MAPI. Para obter informações específicas sobre a notificação de tabela, consulte Sobre Notificações de Tabela. Para obter informações sobre como usar os métodos IMAPISupport para dar suporte à notificação, consulte Notificação de Evento de Suporte.

Referência do MFCMAPI

Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.

Arquivo	Função	Comentário
ContentsTableListCtrl.cpp	CContestTableListCtrl::NotificationOn	O MFCMAPI usa o método IMAPITable::Advise para se registrar para notificações para permitir que a exibição da tabela permaneça atual.

Confira também

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable : IUnknownMFCMAPI como um exemplo de código