Notificación de eventos de MAPI

Hace referencia a: Outlook 2013 | Outlook 2016

La notificación de eventos es la comunicación de información entre dos objetos MAPI. A través de uno de los objetos, un cliente o proveedor de servicios se registra para notificar un cambio o error, denominado evento, que puede tener lugar en el otro objeto. Una vez que se produce el evento, se notifica al primer objeto el cambio o el error. El objeto que recibe la notificación se denomina receptor de aviso; el objeto responsable de la notificación se denomina origen de aviso.

Hay tres tipos de objetos receptores de aviso (todos los tipos son objetos MAPI estándar):

• Aconsejar objetos receptores.
• Objetos receptores de aviso de formulario.
• Ver objetos receptores de aviso.

Los objetos receptores Advise son el tipo más común. Las aplicaciones cliente suelen implementar receptores de aviso para recibir notificaciones de libreta de direcciones y almacén de mensajes y admitir la interfaz IMAPIAdviseSink: IUnknown . IMAPIAdviseSink contiene un único método, IMAPIAdviseSink::OnNotify. Los receptores de aviso de formularios y vistas son menos comunes; se implementan para recibir notificaciones sobre los cambios en formularios personalizados. Los receptores de avisos de formulario admiten la interfaz IMAPIFormAdviseSink: IUnknown y los receptores de aviso de vista admiten la interfaz IMAPIViewAdviseSink : IUnknown . Dado que la mayoría de los clientes implementan objetos receptores de aviso estándar, suponga que las discusiones de las notificaciones se relacionan con las notificaciones de la libreta de direcciones y del almacén de mensajes en lugar de las notificaciones de formularios. Para obtener más información sobre las notificaciones de formularios, vea MAPI Forms Notificaciones y Escritura de código del servidor de formularios.

Los proveedores de servicios y MAPI implementan los objetos de origen de advise. No todos los proveedores de servicios admiten la notificación de eventos; es opcional, pero se recomienda encarecidamente. Los proveedores de almacén de mensajes y libreta de direcciones suelen admitir notificaciones de objetos en varios de sus objetos y notificaciones de tabla en sus tablas de contenido y jerarquía. Los proveedores de transporte no admiten notificaciones directamente; se basan en métodos alternativos de comunicación con clientes.

A diferencia de los receptores de aviso, los objetos de origen de aviso no son un tipo único de objeto MAPI. Muchos objetos MAPI, como almacenes de mensajes y tablas, pueden asumir el rol de origen de aviso. Un origen de aviso es cualquier objeto MAPI que haga lo siguiente:

• Implementa un método Advise para recibir registros de notificaciones.

• Implementa un método Unadvise para recibir cancelaciones de notificaciones.

• Genera notificaciones del tipo adecuado para los objetos receptores de aviso adecuados que se han registrado llamando a sus métodos IMAPIAdviseSink::OnNotify .

Los clientes que implementan objetos de receptor de aviso llaman a Advise cuando quieren registrarse para una notificación, en la mayoría de los casos pasando el identificador de entrada del objeto con el que debe producirse el registro y Unadvise cuando quieren cancelar el registro. Los clientes pasan un parámetro a Advise que indica cuál de los varios tipos de eventos desea supervisar. Advise devuelve un número distinto de cero que representa una conexión correcta entre el receptor de aviso y el origen de aviso.

Antes de llamar a Advise, los clientes pueden determinar si un proveedor de almacén de mensajes admite la notificación comprobando que la marca de STORE_NOTIFY_OK está establecida en la propiedad PR_STORE_SUPPORT_MASK del almacén de mensajes (PidTagStoreSupportMask). No hay forma de que los clientes determinen con antelación si un proveedor de libreta de direcciones admite o no notificaciones. Los clientes deben intentar registrarse y, si se produce un error en el intento, pueden suponer que las notificaciones no son compatibles.

Cuando se produce un evento para el que se ha registrado un cliente, el origen de aviso notifica al receptor de aviso llamando a su método IMAPIAdviseSink::OnNotify con una estructura de datos de notificación que contiene información sobre el evento. La implementación de OnNotify de un receptor de avisos puede realizar tareas en respuesta a la notificación, como actualizar datos en la memoria o actualizar una pantalla.

Los proveedores de servicios pueden implementar la compatibilidad con las notificaciones manualmente o aprovechar la ayuda proporcionada en tres métodos IMAPISupport : IMAPISupport::Subscribe, IMAPISupport::Unsubscribe y IMAPISupport::Notify. Los métodos Subscribe y Unsubscribe controlan el registro y la cancelación de registro de notificaciones para los proveedores; El método Notify controla el envío de notificaciones cuando corresponda.

Para usar los métodos de objeto de soporte técnico para el registro de notificaciones, los proveedores de servicios llaman a IMAPISupport::Subscribe en sus métodos Advise y pasan a Subscribe el puntero del receptor de aviso que los clientes pasan a Advise. Si se pasa un identificador de entrada como parámetro de entrada para especificar un origen de aviso, los proveedores de servicios lo convierten en una clave binaria. Subscribe crea un número de conexión único y es este número el que los proveedores de servicios devuelven a los clientes. Los proveedores de servicios pueden liberar el puntero de objeto receptor de aviso del cliente en cualquier momento después de que se haya completado la llamada a Advise .

Cuando los clientes llaman a Unadvise para cancelar un registro, los proveedores de servicios reducen el recuento de referencias en el puntero receptor de aviso del cliente o llaman a Cancelar suscripción para hacer lo mismo.

Cuando es el momento de generar una notificación, los proveedores de servicios realizan cualquier procesamiento interno relacionado con la notificación e inicializa una estructura NOTIFICATION estableciendo todos sus miembros sin usar en cero. Esta técnica para inicializar la estructura NOTIFICATION puede ayudar a los clientes a crear implementaciones de OnNotify más pequeñas, más rápidas y menos propensas a errores.

En la ilustración siguiente se muestra la comunicación entre los objetos receptores advise, los objetos de origen advise y MAPI. MAPI solo está implicado cuando el origen de aviso llama a los métodos IMAPISupport para la compatibilidad con notificaciones.

Llamadas de notificación de eventos

La clase CAdviseSink de MFCMAPI (mediante los archivos AdviseSink.h y AdviseSink.cpp) implementa el objeto receptor advise para todas las llamadas a Advise. Para obtener más información sobre MFCMAPI, vea MFCMAPI como ejemplo de código y MFCMAPI.