IMAPITable::Advise

Hace referencia a: Outlook 2013 | Outlook 2016

Registra un objeto receptor advise para recibir notificaciones de eventos especificados que afectan a la tabla.

HRESULT Advise(
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR FAR * lpulConnection
);

Parameters

ulEventMask

[in] Valor que indica el tipo de evento que generará la notificación. Solo el siguiente valor es válido:

fnevTableModified

lpAdviseSink

[in] Puntero a un objeto receptor de aviso para recibir las notificaciones posteriores. Este objeto receptor de aviso debe haberse asignado ya.

lpulConnection

[out] Puntero a un valor distinto de cero que representa el registro de notificación correcto.

Valor devuelto

S_OK

El registro de notificación se completó correctamente.

MAPI_E_NO_SUPPORT

La implementación de la tabla no admite cambios en sus filas y columnas o no admite la notificación.

Comentarios

Use el método IMAPITable::Advise para registrar un objeto de tabla implementado en el proveedor para las devoluciones de llamada de notificación. Cada vez que se produce un cambio en el objeto table, el proveedor comprueba qué bit de máscara de eventos se estableció en el parámetro ulEventMask y, por tanto, qué tipo de cambio se produjo. Si se establece un bit, el proveedor llama al método IMAPIAdviseSink::OnNotify para el objeto receptor advise indicado por el parámetro lpAdviseSink para notificar el evento. Los datos pasados en la estructura de notificación a la rutina OnNotify describen el evento.

La llamada a OnNotify puede producirse durante la llamada que cambia el objeto o en cualquier momento siguiente. En sistemas que admiten varios subprocesos de ejecución, la llamada a OnNotify puede producirse en cualquier subproceso. Para obtener una manera de convertir una llamada a OnNotify que podría producirse en un momento inoportuno en uno que sea más seguro de controlar, un proveedor debe usar la función HrThisThreadAdviseSink .

Para proporcionar notificaciones, el proveedor que implementa Advise debe mantener una copia del puntero al objeto receptor lpAdviseSink advise; Para ello, llama al método IUnknown::AddRef para que el receptor advise mantenga su puntero de objeto hasta que se cancele el registro de notificaciones con una llamada al método IMAPITable::Unadvise . La implementación de Advise debe asignar un número de conexión al registro de notificación y llamar a AddRef en este número de conexión antes de devolverlo en el parámetro lpulConnection . Los proveedores de servicios pueden liberar el objeto receptor advise antes de que se cancele el registro, pero no deben liberar el número de conexión hasta que se haya llamado a Unadvise .

Después de que una llamada a Advise se haya realizado correctamente y antes de que se haya llamado a Unadvise , los clientes deben estar preparados para que se libere el objeto receptor de advise. Por lo tanto, un cliente debe liberar su objeto receptor advise después de que advise devuelva a menos que tenga un uso específico a largo plazo para él.

Debido al comportamiento asincrónico de la notificación, las implementaciones que cambian la configuración de columna de tabla pueden recibir notificaciones con información organizada en un orden de columna anterior. Por ejemplo, se podría devolver una fila de tabla para un mensaje que se acaba de eliminar del contenedor. Dicha notificación se envía cuando se ha realizado el cambio de configuración de columna y se envía información sobre ella, pero la vista de tabla de notificaciones no se ha actualizado aún con esa información.

Para obtener más información sobre el proceso de notificación, vea Notificación de eventos en MAPI. Para obtener información específica sobre la notificación de tabla, consulte Acerca de las notificaciones de tabla. Para obtener información sobre el uso de los métodos IMAPISupport para admitir la notificación, vea Supporting Event Notification.

Referencia de MFCMAPI

Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.

Archivo	Función	Comment
ContentsTableListCtrl.cpp	CContestTableListCtrl::NotificationOn	MFCMAPI usa el método IMAPITable::Advise para registrarse en las notificaciones a fin de permitir que la vista de tabla permanezca actualizada.

Vea también

HrThisThreadAdviseSink
IMAPIAdviseSink::OnNotify
IMAPITable::Unadvise
TABLE_NOTIFICATION
IMAPITable: IUnknownMFCMAPI como ejemplo de código