IAddrBook::Advise
Hace referencia a: Outlook 2013 | Outlook 2016
Registra un cliente o proveedor de servicios para recibir notificaciones sobre los cambios en una o varias entradas de la libreta de direcciones.
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 del contenedor de la libreta de direcciones, el usuario de mensajería o la lista de distribución que generará una notificación cuando se produzca un cambio del tipo o los tipos descritos en el parámetro ulEventMask .
ulEventMask
[in] Uno o varios eventos de notificación que el autor de la llamada está registrando para recibir. Cada evento está asociado a una estructura de notificación determinada que contiene información sobre el cambio que se produjo. En la tabla siguiente se enumeran los valores válidos para ulEventMask y sus estructuras correspondientes.
| Evento de notificación | Estructura correspondiente |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in] Puntero al objeto receptor advise al que se llamará cuando se produzca el evento para el que se ha solicitado la notificación.
lpulConnection
[out] Puntero a un número de conexión 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 proveedor de libreta de direcciones responsable del identificador de entrada pasado en lpEntryID no pudo registrar una notificación para la entrada correspondiente.
MAPI_E_NO_SUPPORT
El proveedor de libreta de direcciones responsable del objeto identificado por el identificador de entrada pasado en el parámetro lpEntryID no admite la notificación.
MAPI_E_UNKNOWN_ENTRYID
Ninguno de los proveedores de libreta de direcciones del perfil puede controlar el identificador de entrada pasado en lpEntryID .
Comentarios
Los clientes y proveedores de servicios llaman al método Advise para registrarse para un tipo determinado o tipos de notificación en una entrada de libreta de direcciones. Los tipos de notificación se indican mediante la máscara de evento que se pasa con el parámetro ulEventMask .
MAPI reenvía esta llamada Advise al proveedor de la libreta de direcciones responsable de la entrada, como indica el identificador de entrada en el parámetro lpEntryID . El proveedor de libreta de direcciones controla el propio registro o llama al método de soporte técnico , IMAPISupport::Subscribe, para solicitar a MAPI que registre al autor de la llamada. Se devuelve un número de conexión distinto de cero para representar el registro correcto.
Cada vez que se produce un cambio en la entrada del tipo indicado por el registro de notificaciones, el proveedor de libreta de direcciones llama al método IMAPIAdviseSink::OnNotify para el objeto receptor advise especificado en el parámetro lpAdviseSink . El método OnNotify incluye una estructura NOTIFICATION como parámetro de entrada que contiene datos para describir el evento.
En función del proveedor de libreta de direcciones, la llamada a OnNotify puede producirse inmediatamente después del cambio en el objeto registrado o en un momento posterior. En sistemas que admiten varios subprocesos de ejecución, la llamada a OnNotify puede producirse en cualquier subproceso. Los clientes pueden solicitar que estas notificaciones se produzcan en un subproceso determinado llamando a la función HrThisThreadAdviseSink para crear el objeto receptor advise que se pasa a Advise.
Dado que un proveedor de libreta de direcciones puede liberar el objeto receptor advise pasado por los clientes en cualquier momento después de la finalización correcta de la llamada Advise y antes de una llamada a IAddrBook::Unadvise para cancelar la notificación, los clientes deben liberar sus objetos receptores de aviso cuando se devuelve Advise .
Para obtener más información sobre el proceso de notificación, vea Notificación de eventos en MAPI.