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. Através de um dos objetos, um cliente ou fornecedor de serviços regista-se para notificação de uma alteração ou erro, denominado evento, que pode ocorrer no outro objeto. Após a ocorrência do evento, o primeiro objeto é notificado da alteração ou erro. O objeto que recebe a notificação chama-se sink de aconselhamento; o objeto responsável pela notificação chama-se origem de aconselhamento.

Existem três tipos de objetos sink de aconselhamento (todos os tipos são objetos MAPI padrão):

• Aconselhe objetos sink.
• O formulário aconselha objetos sink.
• Ver aconselhagem de objetos sink.

Aconselhe que os objetos sink são o tipo mais comum. Normalmente, os sinks de aconselhamento são implementados pelas aplicações cliente para receber notificações do livro de endereços e do arquivo de mensagens e suportar a interface IMAPIAdviseSink: IUnknown . IMAPIAdviseSink contém um único método , IMAPIAdviseSink::OnNotify. Os sinks de recomendação de formulários e vistas são menos comuns; são implementados para receber notificações sobre alterações a formulários personalizados. Os sinks de aconselhamento de formulário suportam a interface IMAPIFormAdviseSink: IUnknown interface e view advise sinks suportam a interface IMAPIViewAdviseSink: IUnknown . Uma vez que a maioria dos clientes implementa objetos de sink de aconselhamento padrão, suponha que as discussões de notificações estão relacionadas com notificações do livro de endereços e do arquivo de mensagens em vez de notificações de formulários. Para obter mais informações sobre as notificações de formulários, veja MapI Forms Notifications and Writing Form Server Code (Notificações de Forms MAPI e Escrever Código do Servidor de Formulários).

Aconselhe que os objetos de origem são implementados pelos fornecedores de serviços e pela MAPI. Nem todos os fornecedores de serviços suportam a notificação de eventos; é opcional, mas vivamente recomendado. Normalmente, os fornecedores do arquivo de mensagens e do livro de endereços suportam notificações de objetos em vários dos respetivos objetos e notificações de tabela nos respetivos conteúdos e tabelas de hierarquia. Os fornecedores de transporte não suportam notificações diretamente; dependem de métodos alternativos de comunicação com clientes.

Ao contrário dos sinks de aconselhamento, aconselhe que os objetos de origem não são um tipo exclusivo de objeto MAPI. Muitos objetos MAPI, como arquivos de mensagens e tabelas, podem assumir a função de origem de aconselhamento. Uma origem de recomendações é qualquer objeto MAPI que faça o seguinte:

• Implementa um método Desconselhe para receber registos de notificação.

• Implementa um método Unadvise para receber cancelamentos de notificações.

• Gera notificações do tipo adequado para os objetos sink de aconselhamento adequados que foram registados ao chamar os respetivos métodos IMAPIAdviseSink::OnNotify .

Os clientes que implementam aconselham os objetos sink a chamar Aconselhar quando pretendem registar-se para uma notificação, na maioria dos casos passando no identificador de entrada do objeto com o qual o registo deve ocorrer, e Anular a utilização quando quiserem cancelar o registo. Os clientes transmitem um parâmetro para Aconselhar que indica qual dos vários tipos de eventos pretende monitorizar. A aconselhagem devolve um número diferente de zero que representa uma ligação bem-sucedida entre o sink de aconselhamento e a origem de aconselhamento.

Antes de chamar Aconselhar, os clientes podem determinar se um fornecedor de arquivo de mensagens suporta notificações ao verificar se o sinalizador STORE_NOTIFY_OK está definido na propriedade PR_STORE_SUPPORT_MASK (PidTagStoreSupportMask) do arquivo de mensagens. Não há forma de os clientes determinarem antecipadamente se um fornecedor de livros de endereços suporta ou não notificações. Os clientes têm de tentar registar-se e, se a tentativa falhar, podem assumir que as notificações não são suportadas.

Quando ocorre um evento para o qual um cliente se registou, a origem de recomendações notifica o sink de aconselhamento ao chamar o respetivo 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 sink de aconselhamento pode executar tarefas em resposta à notificação, como atualizar dados na memória ou atualizar um ecrã.

Os fornecedores de serviços podem implementar o suporte para notificações manualmente ou tirar partido da ajuda fornecida em três métodos IMAPISupport : IMAPISupport::Subscribe, IMAPISupport::Unsubscribe e IMAPISupport::Notify. Os métodos Subscribe e Unsubscribe processam o registo de notificação e a desregistração dos fornecedores; O método Notify processa o envio de notificações quando apropriado.

Para utilizar os métodos de objeto de suporte para o registo de notificação, os fornecedores de serviços chamam IMAPISupport::Subscreva os respetivos métodos de Aconselhamento e transmita para Subscrever o ponteiro de sink de aconselhamento que os clientes passam para Aconselhar. Se um identificador de entrada for transmitido como um parâmetro de entrada para especificar uma origem de aconselhamento, os fornecedores de serviços convertem-no numa chave binária. Subscrever cria um número de ligação exclusivo e é este número que os fornecedores de serviços devolvem aos clientes. Os fornecedores de serviços podem libertar o ponteiro do objeto sink de aconselhamento do cliente em qualquer altura após a conclusão da chamada Desconselhe .

Quando os clientes chamam Unadvise para cancelar um registo, os fornecedores de serviços diminuem a contagem de referências no ponteiro de sink de aconselhamento do cliente ou chamam Anular a subscrição para fazer o mesmo.

Quando é altura de gerar uma notificação, os fornecedores de serviços executam qualquer processamento interno relacionado com a notificação e inicializam uma estrutura DE NOTIFICAÇÃO ao definir todos os membros não utilizados como zero. Esta técnica para inicializar a estrutura DE NOTIFICAÇÃO pode ajudar os clientes a criar implementações OnNotify mais pequenas, rápidas e menos propensas a erros.

A ilustração seguinte mostra a comunicação entre aconselhar objetos sink, aconselhar objetos de origem e MAPI. A MAPI só está envolvida quando a origem de aconselhamento chama os métodos IMAPISupport para suporte de notificação.

Event notification calls

A classe MFCMAPI CAdviseSink (utilizando os ficheiros AdviseSink.h e AdviseSink.cpp) implementa o objeto sink de aconselhamento para todas as chamadas para Aconselhar. Para obter mais informações sobre o MFCMAPI, veja MFCMAPI como um Exemplo de Código e MFCMAPI.