IMSLogon::Advise
Hace referencia a: Outlook 2013 | Outlook 2016
Registra un objeto con un proveedor de almacén de mensajes para recibir notificaciones sobre los cambios en el almacén de mensajes. A continuación, el almacén de mensajes enviará notificaciones sobre los cambios en el objeto registrado.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parameters
cbEntryID
[in] Tamaño, en bytes, del identificador de entrada al que apunta el parámetro lpEntryID .
lpEntryID
[in] Puntero al identificador de entrada del objeto sobre qué notificaciones se deben generar. Este objeto puede ser una carpeta, un mensaje o cualquier otro objeto del almacén de mensajes. Como alternativa, si MAPI establece el parámetro cbEntryID en 0 y pasa null para lpEntryID, el receptor advise proporciona notificaciones sobre los cambios en todo el almacén de mensajes.
ulEventMask
[in] Máscara de eventos de los tipos de eventos de notificación que se producen para el objeto sobre el que MAPI generará notificaciones. La máscara filtra casos específicos. Cada tipo de evento tiene una estructura asociada que contiene información adicional sobre el evento. En la tabla siguiente se enumeran los posibles tipos de eventos junto con sus estructuras correspondientes.
| Tipo de evento de notificación | Estructura correspondiente |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevNewMail |
NEWMAIL_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
| fnevSearchComplete |
OBJECT_NOTIFICATION |
| fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[in] Puntero a un objeto receptor de aviso al que se va a llamar cuando se produce un evento para el objeto de sesión sobre qué notificación se ha solicitado. Este objeto receptor de aviso ya debe existir.
lpulConnection
[out] Puntero a una variable que, tras una devolución correcta, contiene el número de conexión para el registro de notificación. El número de conexión debe ser distinto de cero.
Valor devuelto
S_OK
La llamada se ha realizado correctamente y devuelva el valor esperado o los valores.
MAPI_E_NO_SUPPORT
Mapi o uno o varios proveedores de servicios no admiten la operación.
Comentarios
Los proveedores de almacén de mensajes implementan el método IMSLogon::Advise para registrar un objeto para las devoluciones de llamada de notificación. Cada vez que se produce un cambio en el objeto indicado, el proveedor comprueba qué bit de máscara de eventos se estableció en el parámetro ulEventMask y, por lo 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 posterior. En sistemas que admiten varios subprocesos de ejecución, la llamada a OnNotify puede producirse en cualquier subproceso. Para controlar de forma segura una llamada a OnNotify que puede producirse en un momento inoportuno, una aplicación cliente debe usar la función HrThisThreadAdviseSink .
Para proporcionar notificaciones, el proveedor de almacén de mensajes que implementa Advise debe mantener una copia del puntero al objeto receptor lpAdviseSink advise; Para ello, el proveedor 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 IMSLogon::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 .
Una vez que se ha realizado correctamente una llamada a Advise y antes de llamar a Unadvise , los proveedores deben estar preparados para que se libere el objeto receptor de aviso. Por lo tanto, un proveedor debe liberar su objeto receptor advise después de que se devuelva Advise , a menos que tenga un uso específico a largo plazo para él.
Para obtener más información sobre el proceso de notificación, vea Notificación de eventos en MAPI.