IMAPISession::Advise
Hace referencia a: Outlook 2013 | Outlook 2016
Se registra para recibir notificaciones de eventos especificados que afectan a la sesión.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Parameters
cbEntryID
[in] Recuento de bytes en el identificador de entrada al que apunta el parámetro lpEntryID .
lpEntryID
[in] Puntero al identificador de entrada de la libreta de direcciones o el objeto de almacén de mensajes sobre qué notificaciones se deben generar, o NULL, que indica que el cliente se está registrando para recibir notificaciones sobre eventos que afectan solo a la sesión.
ulEventMask
[in] Máscara de valores que indican los tipos de eventos de notificación que el cliente está interesado y que se deben incluir en el registro. Si lpEntryID es NULL, MAPI registra automáticamente el cliente para eventos de error críticos que afectan solo a la sesión. Cuando lpEntryID apunta a un identificador de entrada, los siguientes valores son válidos para el parámetro ulEventMask :
fnevCriticalError
Registra notificaciones sobre errores graves, como memoria insuficiente.
fnevExtended
Se registra para recibir notificaciones sobre eventos específicos de un proveedor de almacén de mensajes o libreta de direcciones determinado y sobre el cierre de sesión.
fnevNewMail
Se registra para recibir notificaciones sobre la llegada de nuevos mensajes.
fnevObjectCreated
Registra las notificaciones sobre la creación de un nuevo objeto.
fnevObjectCopied
Registra las notificaciones sobre un objeto que se va a copiar.
fnevObjectDeleted
Registra las notificaciones sobre un objeto que se va a eliminar.
fnevObjectModified
Registra las notificaciones sobre un objeto que se va a modificar.
fnevObjectMoved
Registra las notificaciones sobre un objeto que se va a mover.
fnevSearchComplete
Registra las notificaciones sobre la finalización de una operación de búsqueda.
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 número distinto de cero que representa la conexión entre el objeto receptor de aviso del autor de la llamada y la sesión.
Valor devuelto
S_OK
El registro se realizó correctamente.
MAPI_E_INVALID_ENTRYID
El identificador de entrada al que apunta lpEntryID no representa un identificador de entrada válido.
MAPI_E_NO_SUPPORT
El proveedor de servicios responsable del identificador de entrada al que apunta lpEntryID no admite el tipo de eventos especificado en el parámetro ulEventMask o no admite la notificación.
MAPI_E_UNKNOWN_ENTRYID
Ninguno de los proveedores de servicios del perfil puede controlar el identificador de entrada al que apunta lpEntryID .
Comentarios
El método IMAPISession::Advise establece una conexión entre el objeto receptor de aviso del autor de la llamada, la sesión y, opcionalmente, un proveedor de servicios. Esta conexión se usa para enviar notificaciones al receptor de aviso cuando se producen uno o varios eventos especificados en el parámetro ulEventMask al objeto al que apunta lpEntryID. Cuando lpEntryID es NULL, el objeto de destino es la sesión y las notificaciones solo se envían para errores críticos y eventos extendidos.
Cuando lpEntryID apunta a un identificador de entrada válido, MAPI llama al método Advise del objeto de inicio de sesión que pertenece al proveedor de servicios responsable. Por ejemplo, si lpEntryID apunta al identificador de entrada de una lista de distribución, MAPI llama al método IABLogon::Advise del proveedor de libreta de direcciones adecuado.
Para enviar una notificación, el proveedor de servicios o MAPI llama al método IMAPIAdviseSink::OnNotify del receptor de aviso registrado. Uno de los parámetros de OnNotify, una estructura de notificación, contiene información que describe el evento específico.
Notas para los llamadores
En sistemas que admiten varios subprocesos de ejecución, la llamada a OnNotify también puede producirse en cualquier subproceso en cualquier momento. Si necesita asegurarse de que las notificaciones se producirán solo en un momento determinado en un subproceso determinado, llame a la función HrThisThreadAdviseSink para generar el objeto receptor de aviso que se pasa al método Advise .
Para determinar cuándo se ha cerrado la sesión de un cliente, regístrese para recibir notificaciones en el proveedor de servicios llamando a Advise con lpEntryID establecido en NULL y cbEntryID establecido en 0. Cuando se produzca el cierre de sesión, recibirá una notificación fnevExtended.
Después de que una llamada a Advise se haya realizado correctamente y antes de que se haya llamado a IMAPISession::Unadvise para cancelar el registro, libere el objeto receptor advise a menos que tenga un uso específico a largo plazo para él.
Para obtener información general sobre el proceso de notificación, vea Notificación de eventos en MAPI.
Para obtener más información sobre el control de notificaciones, vea Control de notificaciones.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
MFCMAPI usa el método IMAPISession::Advise para registrarse para las notificaciones en la sesión. |