IMsgStore::Advise
Hace referencia a: Outlook 2013 | Outlook 2016
Se registra para recibir la notificación de eventos especificados que afectan al almacén de mensajes.
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 carpeta o mensaje sobre qué notificaciones se deben generar o null. Si lpEntryID se establece en NULL, Advise registra las notificaciones en todo el almacén de mensajes.
ulEventMask
[in] Máscara de valores que indican los tipos de eventos de notificación que el autor de la llamada está interesado y que debe incluirse en el registro. Hay una estructura NOTIFICATION correspondiente asociada a cada tipo de evento que contiene información sobre el evento. Los siguientes son valores válidos para el parámetro ulEventMask :
fnevCriticalError
Registra notificaciones sobre errores graves, como memoria insuficiente.
fnevExtended
Registra las notificaciones sobre eventos específicos del proveedor de almacén de mensajes determinado.
fnevNewMail
Se registra para recibir notificaciones sobre la llegada de nuevos mensajes.
fnevObjectCreated
Registra las notificaciones sobre la creación de una nueva carpeta o mensaje.
fnevObjectCopied
Registra las notificaciones sobre una carpeta o mensaje que se va a copiar.
fnevObjectDeleted
Registra las notificaciones sobre una carpeta o mensaje que se va a eliminar.
fnevObjectModified
Registra las notificaciones sobre una carpeta o mensaje que se va a modificar.
fnevObjectMoved
Registra las notificaciones sobre una carpeta o un mensaje 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.
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 de conexión distinto de cero que representa la conexión entre el objeto receptor advise del autor de la llamada y el almacén de mensajes.
Valor devuelto
S_OK
El registro se realizó correctamente.
MAPI_E_NO_SUPPORT
El proveedor del almacén de mensajes no admite el registro para la notificación a través del almacén de mensajes.
Comentarios
El método IMsgStore::Advise establece una conexión entre el objeto receptor advise del autor de la llamada y el almacén de mensajes o un objeto del almacén de mensajes. Esta conexión se usa para enviar notificaciones al receptor de aviso cuando se producen uno o varios eventos, como se especifica en el parámetro ulEventMask , en el objeto de origen advise. Cuando el parámetro lpEntryID apunta a un identificador de entrada válido, el origen de aviso es el objeto identificado por este identificador de entrada. Cuando lpEntryID es NULL, el origen de aviso es el almacén de mensajes.
Para enviar una notificación, el proveedor del almacén de mensajes 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 a los implementadores
Puede admitir la notificación con o sin la ayuda de MAPI. MAPI tiene tres métodos de objeto de soporte técnico para ayudar a los proveedores de servicios a implementar la notificación: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe y IMAPISupport::Notify. Si decide usar los métodos de compatibilidad con MAPI, llame a Subscribe cuando se llame al método Advise y libere el puntero lpAdviseSink .
Si decide admitir la notificación usted mismo, llame al método IUnknown::AddRef del receptor advise representado por el parámetro lpAdviseSink para mantener una copia de este puntero. Mantenga esta copia hasta que se llame al método IMsgStore::Unadvise para cancelar el registro.
Independientemente de cómo admita la notificación, asigne un número de conexión distinto de cero al registro de notificación y devuélvelo en el parámetro lpulConnection . No libere este número de conexión hasta que se haya llamado a Unadvise y se haya completado.
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 debe estar seguro de que las notificaciones solo se producen en un momento determinado en un subproceso determinado, llame a la función HrThisThreadAdviseSink para generar el objeto receptor de aviso que se pasa a Advise.
Después de que una llamada a Advise se haya realizado correctamente y antes de que se haya llamado a Unadvise para cancelar el registro, prepárese para que se libere el objeto receptor de aviso. Debe liberar el 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.
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 IMsgStore::Advise para registrarse para recibir notificaciones en todo el almacén de mensajes. |