Notificações de eventos no MAPI

Aplica-se a: Outlook 2013 | Outlook 2016

A notificação de eventos é a comunicação de informações entre dois objetos MAPI. Por meio de um dos objetos, um cliente ou provedor de serviços se 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 sobre a alteração ou o 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 aviso (todos os tipos são objetos MAPI padrão):

• Aconselhar objetos coletores.
• Formar aconselhar objetos coletores.
• Exibir objetos coletores.

Aconselhar objetos coletor são o tipo mais comum. Os coletores de aviso geralmente 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 visualização são menos comuns; Eles são implementados para receber notificações sobre alterações em formulários personalizados. Os coletores de aviso de formulário dão suporte ao IMAPIFormAdviseSink : IUnknown interface e os coletores de aviso de exibição dão suporte ao IMAPIViewAdviseSink : IUnknown interface. Como a maioria dos clientes implementa objetos de coletor de aviso padrão, suponha que as discussões sobre notificações estejam relacionadas ao catálogo de endereços e às 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 Notificações de formulários MAPI e Escrevendo código de servidor de formulário.

Objetos de origem de aviso são implementados por provedores de serviços e por MAPI. Nem todos os provedores de serviços dão suporte à notificação de eventos; É opcional, mas altamente recomendável. Os provedores de repositório de mensagens e 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 seu conteúdo e tabelas hierárquicas. Os provedores de transporte não suportam notificações diretamente; eles contam com métodos alternativos de comunicação com os clientes.

Ao contrário dos coletores de aconselhamento, os objetos de origem de aviso 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 origem de aviso é 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 coletor de aviso apropriados que foram registrados chamando seus métodos IMAPIAdviseSink::OnNotify .

Os clientes que implementam objetos coletor de aviso chamam Advise 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 o Advise que indica qual dos vários tipos de eventos eles desejam monitorar. Advise retorna um número diferente de zero que representa uma conexão bem-sucedida entre o coletor de aviso e a origem do aviso.

Antes de chamar o Conselho, 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 (PidTagStoreSupportMask) do repositório de mensagens. Não há como os clientes determinarem com antecedência se um provedor de catálogo de endereços dá suporte a notificações ou não. Os clientes devem tentar se registrar e, se a tentativa falhar, eles poderão presumir que as notificações não têm suporte.

Quando ocorre um evento para o qual um cliente foi registrado, a origem de aviso notifica o coletor de aviso 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 de um coletor de aviso 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 o 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 de assinatura e cancelamento de assinatura lidam com o registro de notificação e cancelamento de registro para provedores; o método Notify lida com 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 Advise e passam para Subscribe o ponteiro de coletor de aviso que os clientes passam para o Advise. Se um identificador de entrada for passado como um parâmetro de entrada para especificar uma fonte de aviso, os provedores de serviço 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ços podem liberar o ponteiro do objeto coletor de aviso do cliente a qualquer momento após a conclusão da chamada de aconselhamento .

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

Quando é hora de gerar uma notificação, os provedores de serviços executam qualquer processamento interno relacionado à notificação e inicializam 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 de aviso e MAPI. O MAPI está envolvido somente quando a origem de aviso chama os métodos IMAPISupport para suporte de notificação.

Event notification calls

de

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