Implementación de un objeto receptor Advise

Hace referencia a: Outlook 2013 | Outlook 2016

Un cliente puede implementar sus propios objetos receptores de aviso o usar una función de utilidad , HrAllocAdviseSink. HrAllocAdviseSink crea un objeto receptor advise con una implementación de OnNotify que invoca una función de devolución de llamada.

El uso de HrAllocAdviseSink tiene ventajas y desventajas. Puede guardar el trabajo, pero no proporciona ningún control sobre el recuento de referencias del objeto receptor de aviso que crea. Por lo tanto, los clientes que necesitan controlar cuidadosamente la versión del receptor de aviso o que tienen interdependencias entre su receptor de aviso y otro objeto de cliente deben construir su propia implementación IMAPIAdviseSink y evitar usar HrAllocAdviseSink por completo.

Un cliente que implemente su propio receptor de avisos debe convertirlo en un objeto independiente que no esté relacionado con ningún otro objeto o que dependa de ellos, con el fin de eliminar posibles complicaciones en el recuento de referencias y la liberación de objetos. Sin embargo, si debe implementar el receptor advise como parte de otro objeto o incluir un puntero atrás a otro objeto como miembro de datos, se recomienda mantener dos recuentos de referencias independientes: uno para el objeto al que hace referencia el receptor de aviso y otro para el receptor de aviso.

Cuando el recuento de referencias del objeto al que se hace referencia cae a cero, todos sus métodos pueden producir un error y su tabla virtual se puede destruir, pero la memoria del receptor advise debe permanecer intacta hasta que su recuento de referencias también cae a cero. Esto significa que el método Release del receptor advise debe reducir su recuento de referencias y terminar de destruir el objeto cuando ese recuento alcanza cero. Si no se mantienen dos recuentos de referencias independientes, sería fácil destruir involuntariamente el receptor de aviso como parte del proceso de liberación del objeto que abarca.

Los clientes que usan HrAllocAdviseSink para implementar un receptor de aviso deben tener el mismo cuidado de no incluir su función de devolución de llamada como método en otro objeto receptor de advise. Para los clientes de C++, es tentador hacerlo y pasar este puntero como parámetro. Se trata de una estrategia peligrosa porque los clientes normalmente liberan un objeto cuando su recuento de referencias alcanza cero. Liberar la memoria del objeto receptor advise haría que este puntero no fuera válido.

En función del tipo de evento y el origen de aviso, el método OnNotify puede controlar los eventos de varias maneras. En la tabla siguiente se ofrecen sugerencias sobre cómo controlar algunos de los eventos estándar.

Tipo de evento	Control en OnNotify
Objeto movido	Si el elemento primario original del objeto movido está relacionado con el nuevo elemento primario, actualice la vista a partir de la carpeta o el contenedor de la libreta de direcciones más alto de la jerarquía. Si los dos contenedores primarios no están relacionados, actualice ambas vistas.
Nuevo mensaje	Cambie la interfaz de usuario para informar al usuario de la llegada de uno o varios mensajes nuevos. Coloque la carpeta de recepción en la vista actual.
Error	Para todos los objetos excepto la sesión, registre el error si es necesario y devuelva. Para el objeto de sesión, cierre la sesión si es posible.
Búsqueda completa	No es necesario ningún procesamiento.

Nota:

Los controladores de notificaciones deben ser reentrantes.