Notificações de eventos no MAPI

Aplica-se a: Outlook 2013 | Outlook 2016

A notificação de evento é a comunicação de informações entre dois objetos MAPI. Por meio de um dos objetos, um cliente ou provedor de serviços registra para notificação de uma alteração ou erro, chamado de evento, que pode ocorrer no outro objeto. Depois que o evento ocorre, o primeiro objeto é notificado da alteração ou erro. O objeto que recebe a notificação é chamado de coletor de aconselhamento; o objeto responsável pela notificação é chamado de fonte de aconselhamento.

Há três tipos de objetos de coletor de aconselhamento (todos os tipos são objetos MAPI padrão):

• Aconselhar objetos de coletor.
• O formulário aconselha objetos de coletor.
• Exibir objetos de coletor de aconselhamento.

Aconselhar objetos de coletor são o tipo mais comum. Os coletores de aconselhamento normalmente são implementados por aplicativos cliente para receber notificações do catálogo de endereços e do repositório de mensagens e dar suporte à interface IMAPIAdviseSink : IUnknown . IMAPIAdviseSink contém um único método, IMAPIAdviseSink::OnNotify. Os coletores de aviso de forma e exibição são menos comuns; elas são implementadas para receber notificações sobre alterações em formulários personalizados. Os coletores de consultoria de formulário dão suporte à interface IMAPIFormAdviseSink : IUnknown e os coletores de consultoria de exibição dão suporte à interface IMAPIViewAdviseSink : IUnknown . Como a maioria dos clientes implementa objetos de coletor de aconselhamento padrão, suponha que as discussões sobre notificações se relacionam com o catálogo de endereços e notificações do repositório de mensagens em vez de notificações de formulários. Para obter mais informações sobre notificações de formulários, consulte Mapi Forms Notifications and Writing Form Server Code.

Os objetos de origem de consultoria são implementados pelos provedores de serviços e pelo MAPI. Nem todos os provedores de serviço dão suporte à notificação de eventos; ele é opcional, mas altamente recomendado. Os provedores do repositório de mensagens e do catálogo de endereços geralmente dão suporte a notificações de objeto em vários de seus objetos e notificações de tabela em seus conteúdos e tabelas de hierarquia. Os provedores de transporte não dão suporte diretamente às notificações; eles dependem de métodos alternativos de comunicação com clientes.

Ao contrário dos coletores de aconselhamento, os objetos de origem não são um tipo exclusivo de objeto MAPI. Muitos objetos MAPI, como repositórios de mensagens e tabelas, podem assumir a função de fonte de aconselhamento. Uma fonte de aconselhamento é qualquer objeto MAPI que faz o seguinte:

• Implementa um método Advise para receber registros de notificação.

• Implementa um método Unadvise para receber cancelamentos de notificação.

• Gera notificações do tipo apropriado para os objetos de coletor de aconselhamento apropriados registrados chamando seus métodos IMAPIAdviseSink::OnNotify .

Os clientes que implementam objetos de coletor aconselham a chamada Aconselhar quando desejam se registrar para uma notificação, na maioria dos casos passando o identificador de entrada do objeto com o qual o registro deve ocorrer e Unadvise quando desejam cancelar o registro. Os clientes passam um parâmetro para Aconselhar que indica qual dos vários tipos de eventos que eles desejam monitorar. Aconselhar retorna um número não zero que representa uma conexão bem-sucedida entre o coletor de aconselhamento e a fonte de aconselhamento.

Antes de chamar o Advise, os clientes podem determinar se um provedor de repositório de mensagens dá suporte à notificação verificando se o sinalizador de STORE_NOTIFY_OK está definido na propriedade PR_STORE_SUPPORT_MASK do repositório de mensagens (PidTagStoreSupportMask). Não há como os clientes determinarem com antecedência se um provedor de catálogo de endereços dá suporte ou não a notificações. Os clientes devem tentar se registrar e, se a tentativa falhar, eles podem assumir que as notificações não têm suporte.

Quando ocorre um evento para o qual ocorre um cliente registrado, a fonte de consultoria notifica o coletor de aconselhamento chamando seu método IMAPIAdviseSink::OnNotify com uma estrutura de dados de notificação que contém informações sobre o evento. A implementação do OnNotify por um coletor de consultoria pode executar tarefas em resposta à notificação, como atualizar dados na memória ou atualizar uma exibição de tela.

Os provedores de serviços podem implementar suporte para notificações manualmente ou aproveitar a ajuda fornecida em três métodos IMAPISupport : IMAPISupport::Subscribe, IMAPISupport::Unsubscribe e IMAPISupport::Notify. Os métodos Assinar e Cancelar assinatura lidam com registro de notificação e desregistração para provedores; o método Notificar manipula o envio de notificações quando apropriado.

Para usar os métodos de objeto de suporte para registro de notificação, os provedores de serviços chamam IMAPISupport::Subscribe em seus métodos de aconselhamento e passam para Assinar o ponteiro de coletor de aconselhamento que os clientes passam para Aconselhar. Se um identificador de entrada for passado como um parâmetro de entrada para especificar uma origem de aconselhamento, os provedores de serviços o converterão em uma chave binária. A assinatura cria um número de conexão exclusivo e é esse número que os provedores de serviços retornam aos clientes. Os provedores de serviço podem liberar o ponteiro de objeto de coletor de aconselhamento do cliente a qualquer momento após a conclusão da chamada Desaconselhável.

Quando os clientes chamam Unadvise para cancelar um registro, os provedores de serviços decresciam a contagem de referência no ponteiro do coletor de aconselhamento do cliente ou chamam Cancelar assinatura para fazer o mesmo.

Quando é hora de gerar uma notificação, os provedores de serviços executam qualquer processamento interno relacionado à notificação e inicializa uma estrutura NOTIFICATION definindo todos os seus membros não utilizados como zero. Essa técnica para inicializar a estrutura notification pode ajudar os clientes a criar implementações OnNotify menores, mais rápidas e menos propensas a erros.

A ilustração a seguir mostra a comunicação entre objetos de coletor de aconselhamento, objetos de origem e MAPI. O MAPI só está envolvido quando a fonte de aconselhamento chama os métodos IMAPISupport para suporte à notificação.

Event notification calls

A classe CAdviseSink do MFCMAPI (usando os arquivos AdviseSink.h e AdviseSink.cpp) implementa o objeto de coletor de aconselhamento para todas as chamadas para Aconselhar. Para obter mais informações sobre MFCMAPI, consulte MFCMAPI como um exemplo de código e MFCMAPI.