IMAPIAdviseSink::OnNotify

Artigo
04/04/2023

Aplica-se a: Outlook 2013 | Outlook 2016

Responde a uma notificação executando uma ou mais tarefas. As tarefas executadas dependem do tipo de evento e do objeto que gera a notificação.

ULONG OnNotify(
  ULONG cNotif,
  LPNOTIFICATION lpNotifications
);

Parâmetros

cNotif

[in] A contagem de estruturas notification apontadas pelo parâmetro lpNotifications .

lpNotifications

[in] Um ponteiro para uma ou mais estruturas notification que fornecem informações sobre os eventos ocorridos.

Valor de retorno

S_OK

A notificação foi processada com êxito.

Comentários

O processo de notificação começa quando um cliente ou MAPI faz uma chamada para o método Desaconselhável de um provedor de serviços para se registrar para receber uma notificação de um tipo específico para um objeto específico. Um dos parâmetros para o método Advise é um ponteiro para um objeto de coletor de consultoria que implementa a interface IMAPIAdviseSink . Quando ocorre um evento ao objeto de destino que corresponde à notificação registrada, o provedor de serviços, direta ou indiretamente por meio do MAPI, chama o método OnNotify do coletor de aconselhamento.

A chamada para OnNotify pode ocorrer durante a chamada MAPI que está causando o evento ou em algum momento posterior. Em sistemas que dão suporte a vários threads de execução, o OnNotify pode ser chamado no mesmo thread que foi usado para registro ou em um thread diferente. Os clientes podem garantir que a chamada OnNotify seja feita no mesmo thread usado para chamar Aconselhar criando o coletor de aconselhamento que eles passam para Aconselhar com a função HrThisThreadAdviseSink .

O parâmetro lpNotifications aponta para uma ou mais estruturas notification que descrevem o que foi alterado durante o evento. Há um tipo diferente de estrutura NOTIFICATION para cada tipo de evento.

A tabela a seguir lista os valores usados para representar os possíveis tipos de eventos e as estruturas associadas a cada valor:

Tipo de evento de notificação	Estrutura correspondente
fnevCriticalError	ERROR_NOTIFICATION
fnevNewMail	NEWMAIL_NOTIFICATION
fnevObjectCreated	OBJECT_NOTIFICATION
fnevObjectDeleted	OBJECT_NOTIFICATION
fnevObjectModified	OBJECT_NOTIFICATION
fnevObjectCopied	OBJECT_NOTIFICATION
fnevSearchComplete	OBJECT_NOTIFICATION
fnevTableModified	TABLE_NOTIFICATION
fnevStatusObjectModified	STATUS_OBJECT_NOTIFICATION
fnevExtended	EXTENDED_NOTIFICATION

Para obter mais informações sobre como configurar e parar notificações, confira as entradas de referência para os métodos Advise e Unadvise para qualquer uma das seguintes interfaces: IABLogon, IAddrBook, IMAPIForm, IMAPISession, IMAPITable, IMsgStore e IMSLogon.

Para obter informações gerais sobre o processo de notificação, consulte Notificação de Eventos no MAPI.

Observações para implementadores

A implementação do OnNotify normalmente consiste em um ou mais blocos de código para cada tipo de notificação que você espera receber. Nesses blocos de código, execute todas as tarefas que você considerar necessárias como resposta à notificação. Por exemplo, suponha que você se registre para receber notificações fnevObjectModified em uma pasta incluída em uma exibição de caixa de diálogo. No bloco de código que você inclui em seu método OnNotify para lidar com notificações fnevObjectModified , você pode enviar uma mensagem do Windows para a caixa de diálogo para solicitar uma exibição atualizada.

Não modifique ou libere a estrutura NOTIFICATION passada para OnNotify. Os dados na estrutura são válidos somente até que o OnNotify retorne.

Notas para chamadores

Quando ocorrem alterações em vários objetos, você pode notificar um coletor de aconselhamento registrado em uma única chamada para OnNotify ou em várias chamadas, dependendo das restrições de memória. Isso é verdade, independentemente de as alterações serem resultado de uma chamada de método ou várias. Por exemplo, uma chamada para IMAPIFolder::CopyMessages pode afetar várias mensagens e pastas. Como provedor de armazenamento de mensagens, você pode fazer uma chamada para OnNotify com um tipo de evento fnevObjectModified para a pasta de destino ou muitas chamadas, uma para cada mensagem de efeito. Da mesma forma, se um cliente fizer chamadas repetidas para IMAPIFolder::CreateMessage, essas chamadas poderão ser combinadas em um evento fnevObjectModified para a pasta ou separadas em eventos individuais fnevObjectCreated para cada nova mensagem.

Para obter mais informações sobre como e quando gerar notificações, consulte Notificação de Eventos no MAPI e Notificação de Evento de Suporte.