IABLogon::Advise
Hace referencia a: Outlook 2013 | Outlook 2016
Registra al autor de la llamada para recibir la notificación de eventos especificados que afectan a un contenedor, un usuario de mensajería o una lista de distribución.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * 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 del objeto sobre qué notificaciones se deben generar.
ulEventMask
[in] Máscara de bits de valores que indican los tipos de eventos de notificación que el autor de la llamada está interesado en y que se deben incluir en el registro. Hay una estructura NOTIFICATION correspondiente asociada a cada tipo de evento que contiene información sobre el evento. En la tabla siguiente se enumeran los valores válidos para el parámetro ulEventMask y las estructuras asociadas a cada valor.
| Tipo de evento de notificación | Estructura NOTIFICATION correspondiente |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in] Puntero a un objeto receptor de aviso para recibir las notificaciones posteriores.
lpulConnection
[out] Puntero a un valor distinto de cero que representa el registro de notificación.
Valor devuelto
S_OK
El registro de notificación se realizó correctamente.
MAPI_E_INVALID_ENTRYID
El identificador de entrada pasado en el parámetro lpEntryID no está en el formato adecuado.
MAPI_E_NO_SUPPORT
El proveedor de libreta de direcciones no admite la notificación, posiblemente porque no permite que se realicen cambios en sus objetos.
MAPI_E_UNKNOWN_ENTRYID
El proveedor de libreta de direcciones no puede controlar el identificador de entrada pasado en lpEntryID.
Comentarios
Los proveedores de libreta de direcciones implementan el método IABLogon::Advise para registrar al autor de la llamada para recibir una notificación cuando se produce un cambio en un objeto de uno de sus contenedores. Los autores de llamadas pueden registrarse para recibir notificaciones relacionadas con usuarios de mensajería, listas de distribución o contenedores completos.
Los clientes suelen llamar al método IAddrBook::Advise para registrarse para recibir notificaciones de libreta de direcciones. A continuación, MAPI llama al método Advise del proveedor de libreta de direcciones responsable del objeto representado por el identificador de entrada en lpEntryID.
Cuando se produce un cambio en el objeto indicado del tipo representado en ulEventMask, se realiza una llamada al método OnNotify del receptor advise al que apunta lpAdviseSink. Los datos pasados en la estructura NOTIFICATION a la rutina OnNotify describen el evento.
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:
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 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 IABLogon::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 al método Unadvise .
Notas para los llamadores
El puntero del receptor advise que se pasa en el parámetro lpAdviseSink a Advise puede apuntar a un objeto que haya creado o que MAPI haya creado a través de la función HrThisThreadAdviseSink . Es posible que quiera usar HrThisThreadAdviseSink si admite varios subprocesos de ejecución y desea asegurarse de que las llamadas posteriores al método OnNotify se producen en un momento adecuado en un subproceso adecuado.
Prepárese para que el objeto receptor de avisos se libere en cualquier momento después de la llamada a Advise y antes de la llamada a Unadvise. Por lo tanto, 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 información sobre cómo usar los métodos IMAPISupport para admitir la notificación, vea Supporting Event Notification. Para obtener más información sobre el multithreading y MAPI, vea Subprocesos en MAPI.