Notificações de eventos de suporte
Aplica-se a: Outlook 2013 | Outlook 2016
Como o suporte à notificação de evento pode ser complicado, o MAPI fornece três métodos de objeto de suporte que implementam as partes mais difíceis do processo. Esses métodos funcionam como uma unidade e um provedor deve usar todos os três ou nenhum deles.
Os métodos de suporte mapi usam chaves de notificação para gerenciar as conexões entre os coletores de aconselhamento e os objetos que geram as notificações. Uma chave de notificação é uma estrutura NOTIFKEY que contém dados binários que identifica um objeto entre processos. Normalmente, uma chave de notificação é copiada do identificador de entrada de longo prazo do objeto de origem de aconselhamento. Se o cliente tiver fornecido um identificador de entrada na chamada para Aconselhar, você poderá usá-lo para a chave de notificação. Se o parâmetro lpEntryID para Aconselhar for NULL, use o identificador de entrada do objeto de contêiner mais externo possível, como o repositório de mensagens.
Para usar os métodos de suporte, chame IMAPISupport::Subscribe sempre que um cliente chamar seu método Desaconselhável para registrar uma notificação. Aloque uma estrutura NOTIFKEY e crie uma chave de notificação exclusiva para seu objeto de origem de aconselhamento. Por exemplo, um provedor de armazenamento de mensagens que é solicitado a notificar um cliente quando uma mensagem é recebida em uma pasta específica cria uma chave de notificação para essa pasta. Passe um ponteiro para a estrutura NOTIFKEY na chamada para Assinar junto com um ponteiro para o coletor de aconselhamento do cliente. A assinatura chama o método IUnknown::AddRef do coletor de aconselhamento para incrementar sua contagem de referências e a MAPI mantém o ponteiro até que o registro seja cancelado.
Você pode passar o sinalizador NOTIFY_SYNC para Assinar para solicitar que Notificar se comporte de forma síncrona e não retorne até que ele tenha feito todas as chamadas para os métodos IMAPIAdviseSink::OnNotify de coletores de aconselhamento registrados. Defina esse sinalizador apenas para seu próprio uso interno. Não defina quando você responder a uma chamada de Aconselhamento do cliente. A notificação de eventos entre clientes e provedores é sempre assíncrona. Ou seja, o MAPI garante que a chamada durante a qual um evento acontece retornará ao cliente antes que qualquer uma das chamadas onNotify seja feita.
Se você definir o sinalizador NOTIFY_SYNC, não faça alterações em nenhum dos objetos de coletor de aconselhamento e não passe um coletor de conselhos de wrapper criado por HrThisThreadAdviseSink para Assinar. HrThisThreadAdviseSink cria uma versão com segurança de thread de um coletor de aconselhamento a ser usado apenas com notificação assíncrona.
Se um coletor de aconselhamento registrado para notificação síncrona retornar do OnNotify com o conjunto de sinalizadores CALLBACK_DISCONTINUE, IMAPISupport::Notify definirá o sinalizador NOTIFY_CANCELED e retornará sem fazer chamadas para OnNotify.
Depois que a assinatura for retornada, você não precisará mais manter a cópia do coletor de aconselhamento do cliente. Chame seu método IUnknown::Release para liberá-lo. A assinatura retorna um número de conexão não zero que você deve retornar ao cliente. O número de conexão representa o link entre a origem do conselho e o coletor de aconselhamento. Ele permanece válido até que o cliente faça uma chamada bem-sucedida para Unadvise.
Quando o cliente estiver pronto para cancelar um registro, ele chama o método Unadvise . Passe o número de conexão da chamada Unadvise para IMAPISupport::Cancelar assinatura. Cancelar assinatura chama o método IUnknown::Release do coletor de aconselhamento. Assim como no Advise e no Unadvise, as chamadas para Assinar e Cancelar assinatura devem ser emparelhadas. Você deve fazer uma chamada para Cancelar assinatura para cada chamada feita para Assinar. No entanto, você não precisa chamar Assinar toda vez que seu método Desaconselhá-lo . Por outro lado, você pode chamá-lo para configurar notificações internas.
Quando ocorrer um evento, aloque uma ou mais estruturas de NOTIFICAÇÃO do tipo apropriado para o evento e chame IMAPISupport::Notify. Notificar gera uma notificação para cada coletor de aconselhamento registrado. Você deve definir todos os membros não utilizados da estrutura NOTIFICATION 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.
Observe que uma estrutura de NOTIFICAÇÃO separada é necessária para cada evento, mesmo para vários eventos do mesmo tipo. Por exemplo, se três clientes estiverem registrados para notificação de tabela em uma tabela específica e cinco linhas forem adicionadas à tabela, você deverá criar cinco estruturas OBJECT_NOTIFICATION para a chamada Notificar . Uma notificação em lote como essa resulta em um desempenho melhor do que chamar Notificar cinco vezes. Para cada chamada notificar , MAPI chama o método IMAPIAdviseSink::OnNotify de cada coletor de aconselhamento registrado. Se não houver coletores de aconselhamento registrados, o MAPI ignorará a chamada.
Os provedores de serviço que enviam notificações em lote devem encomendá-las para que possam ser interpretadas da primeira notificação até a última. Essa ordenação é especialmente necessária quando um lote de notificação contém uma série de eventos, como TABLE_ROW_ADDED com um evento que se refere a uma linha anterior que foi adicionada em outro evento no mesmo lote.