Notificación de eventos auxiliar
Hace referencia a: Outlook 2013 | Outlook 2016
Dado que la compatibilidad con la notificación de eventos puede ser complicada, MAPI proporciona tres métodos de objeto de soporte técnico que implementan las partes más difíciles del proceso. Estos métodos funcionan como una unidad y un proveedor debe usar los tres o ninguno de ellos.
Los métodos de compatibilidad mapi usan claves de notificación para administrar las conexiones entre los receptores de aviso y los objetos que generan las notificaciones. Una clave de notificación es una estructura NOTIFKEY que contiene datos binarios que identifican un objeto entre procesos. Normalmente, una clave de notificación se copia del identificador de entrada a largo plazo del objeto de origen advise. Si el cliente ha proporcionado un identificador de entrada en la llamada a Advise, puede usarlo para la clave de notificación. Si el parámetro lpEntryID de Advise es NULL, use el identificador de entrada del objeto contenedor más externo posible, como el almacén de mensajes.
Para usar los métodos de soporte técnico, llame a IMAPISupport::Subscribe cada vez que un cliente llame al método Advise para registrarse para una notificación. Asigne una estructura NOTIFKEY y cree una clave de notificación única para el objeto de origen advise. Por ejemplo, un proveedor de almacén de mensajes al que se le pide que notifique a un cliente cuando se recibe un mensaje en una carpeta determinada crea una clave de notificación para esa carpeta. Pase un puntero a la estructura NOTIFKEY en la llamada a Subscribe junto con un puntero al receptor de aviso del cliente. Subscribe llama al método IUnknown::AddRef del receptor advise para incrementar su recuento de referencias y MAPI conserva el puntero hasta que se cancela el registro.
Puede pasar la marca NOTIFY_SYNC a Suscribirse para solicitar que Notify se comporte sincrónicamente y no devuelva hasta que haya realizado todas las llamadas a los métodos IMAPIAdviseSink::OnNotify de receptores de aviso registrados. Establezca esta marca solo para su propio uso interno. No lo establezca cuando responda a una llamada de aviso del cliente. La notificación de eventos entre clientes y proveedores siempre es asincrónica. Es decir, MAPI garantiza que la llamada durante la que se produce un evento volverá al cliente antes de realizar cualquiera de las llamadas a OnNotify .
Si establece la marca de NOTIFY_SYNC, no realice ningún cambio en ninguno de los objetos receptores advise y no pase un receptor de notificación contenedor creado por HrThisThreadAdviseSink a Subscribe. HrThisThreadAdviseSink crea una versión segura para subprocesos de un receptor de avisos que se usará solo con notificación asincrónica.
Si un receptor de aviso registrado para la notificación sincrónica devuelve desde OnNotify con la marca de CALLBACK_DISCONTINUE establecida, IMAPISupport::Notify establece la marca de NOTIFY_CANCELED y devuelve sin realizar ninguna llamada a OnNotify.
Una vez que se haya devuelto Subscribe , ya no tendrá que conservar la copia del receptor de avisos del cliente. Llame a su método IUnknown::Release para liberarlo. Subscribe devuelve un número de conexión distinto de cero que debe devolver al cliente. El número de conexión representa el vínculo entre el origen de aviso y el receptor de aviso. Sigue siendo válido hasta que el cliente realiza una llamada correcta a Unadvise.
Cuando el cliente está listo para cancelar un registro, llama al método Unadvise . Pase el número de conexión de la llamada unadvise a IMAPISupport::Unsubscribe. Cancelar suscripción llama al método IUnknown::Release del receptor de aviso. Al igual que con Advise y Unadvise, las llamadas a Subscribe y Unsubscribe deben emparejarse. Debe realizar una llamada a Cancelar suscripción por cada llamada que se realice a Suscribirse. Sin embargo, no es necesario llamar a Subscribe cada vez que se llama al método Advise . Por el contrario, puede llamarlo para configurar notificaciones internas.
Cuando se produce un evento, asigne una o varias estructuras NOTIFICATION del tipo adecuado para el evento y llame a IMAPISupport::Notify. La notificación genera una notificación para cada receptor de aviso registrado. Debe establecer todos los miembros sin usar de la estructura NOTIFICATION 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.
Tenga en cuenta que es necesaria una estructura NOTIFICATION independiente para cada evento, incluso para varios eventos del mismo tipo. Por ejemplo, si se registran tres clientes para la notificación de tabla en una tabla determinada y se agregan cinco filas a la tabla, debe crear cinco estructuras OBJECT_NOTIFICATION para la llamada notify . Una notificación por lotes como esta resulta en un mejor rendimiento que llamar a Notificar cinco veces. Para cada llamada Notify , MAPI llama al método IMAPIAdviseSink::OnNotify de cada receptor de aviso registrado. Si no hay receptores de aviso registrados, MAPI omite la llamada.
Los proveedores de servicios que envían notificaciones por lotes deben ordenarlas para que se puedan interpretar desde la primera notificación hasta la última. Esta ordenación es especialmente necesaria cuando un lote de notificaciones contiene una serie de eventos, como TABLE_ROW_ADDED con un evento que hace referencia a una fila anterior que se agregó en otro evento en el mismo lote.