Implementando um objeto Coletor de Aconselhamento

Aplica-se a: Outlook 2013 | Outlook 2016

Um cliente pode implementar seus próprios objetos de coletor de consultoria ou usar uma função de utilitário, HrAllocAdviseSink. HrAllocAdviseSink cria um objeto coletor de aconselhamento com uma implementação do OnNotify que invoca uma função de retorno de chamada.

Há vantagens e desvantagens em usar HrAllocAdviseSink. Ele pode salvar o trabalho, mas não fornece controle sobre a contagem de referências do objeto de coletor de aconselhamento que ele cria. Portanto, os clientes que precisam controlar cuidadosamente a versão do coletor de consultoria ou que têm interdependencies entre o coletor de aconselhamento e outro objeto cliente devem construir sua própria implementação IMAPIAdviseSink e evitar o uso de HrAllocAdviseSink completamente.

Um cliente que implementa seu próprio coletor de consultoria deve torná-lo um objeto independente não relacionado ou dependente de outros objetos, de modo a eliminar possíveis complicações na contagem de referência e na versão do objeto. No entanto, se você precisar implementar o coletor de aconselhamento como parte de outro objeto ou incluir um ponteiro traseiro para outro objeto como membro de dados, é recomendável que duas contagens de referência separadas sejam mantidas: uma para o objeto referenciado pelo coletor de aconselhamento e uma para o coletor de aconselhamento.

Quando a contagem de referência do objeto referenciado cai para zero, todos os seus métodos podem falhar e sua vtable pode ser destruída, mas a memória do coletor de aconselhamento deve permanecer intacta até que sua contagem de referência também caia para zero. Isso significa que o método release do coletor de aconselhamento deve decrescir sua contagem de referência e terminar de destruir o objeto quando essa contagem atingir zero. Se duas contagens de referência separadas não forem mantidas, seria fácil destruir inadvertidamente o coletor de aconselhamento como parte do processo de liberação do objeto abrangente.

Os clientes que usam HrAllocAdviseSink para implementar um coletor de aconselhamento devem ter o mesmo cuidado para não incluir sua função de retorno de chamada como um método em outro objeto de coletor de aconselhamento. Para clientes C++, é tentador fazer isso e passar esse ponteiro como um parâmetro. Essa é uma estratégia perigosa porque os clientes normalmente liberam um objeto quando sua contagem de referências atinge zero. Liberar a memória do objeto coletor de aconselhamento tornaria o ponteiro inválido.

Dependendo do tipo de evento e da fonte de aconselhamento, seu método OnNotify pode lidar com eventos de várias maneiras. A tabela a seguir oferece sugestões sobre como lidar com alguns dos eventos padrão.

Tipo de evento	Tratamento no OnNotify
Objeto movido	Se o pai original do objeto movido estiver relacionado ao novo pai, atualize o modo de exibição começando com a pasta ou o contêiner do catálogo de endereços mais alto na hierarquia. Se os dois contêineres pai não estiverem relacionados, atualize ambas as exibições.
Nova mensagem	Altere a interface do usuário para informar o usuário sobre a chegada de uma ou mais mensagens novas. Coloque a pasta de recebimento na exibição atual.
Erro	Para todos os objetos, exceto a sessão, registre o erro se necessário e retorne. Para o objeto de sessão, faça logon, se possível.
Pesquisa concluída	Nenhum processamento necessário.

Observação

Os manipuladores de notificação devem ser reentrantes.