Implementando um objeto de coletor do Advise

Aplica-se a: Outlook 2013 | Outlook 2016

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

Há vantagens e desvantagens em usar HrAllocAdviseSink. Isso pode economizar trabalho, mas não fornece controle sobre a contagem de referência do objeto coletor de aviso que ele cria. Portanto, os clientes que precisam controlar cuidadosamente a liberação do coletor de aviso ou que têm interdependências entre o coletor de aviso 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 aviso deve torná-lo um objeto independente, não relacionado ou dependente de outros objetos, para eliminar possíveis complicações na contagem de referências e na liberação do objeto. No entanto, se você precisar implementar o coletor de aviso como parte de outro objeto ou incluir um ponteiro de retorno para outro objeto como um membro de dados, é recomendável que duas contagens de referência separadas sejam mantidas: uma para o objeto referenciado pelo coletor de aviso e outra 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 aviso 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 aviso deve diminuir sua contagem de referência e terminar de destruir o objeto quando essa contagem chegar a zero. Se duas contagens de referência separadas não forem mantidas, será fácil destruir inadvertidamente o coletor de aviso como parte do processo Release do objeto abrangente.

Os clientes que usam HrAllocAdviseSink para implementar um coletor de aviso 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 o ponteiro this como um parâmetro. Essa é uma estratégia perigosa porque os clientes normalmente liberam um objeto quando sua contagem de referência atinge zero. Liberar a memória para o objeto coletor de aviso tornaria este ponteiro inválido.

Dependendo do tipo de evento e da origem do aviso, 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.