IAddrBook::Advise
Aplica-se a: Outlook 2013 | Outlook 2016
Registra um cliente ou provedor de serviços para receber notificações sobre alterações em uma ou mais entradas no catálogo de endereços.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG_PTR lpulConnection
);
Parâmetros
cbEntryID
[in] A contagem de bytes no identificador de entrada apontada pelo parâmetro lpEntryID .
Lpentryid
[in] Um ponteiro para o identificador de entrada do contêiner do catálogo de endereços, usuário de mensagens ou lista de distribuição que gerará uma notificação quando ocorrer uma alteração do tipo ou tipos descritos no parâmetro ulEventMask .
ulEventMask
[in] Um ou mais eventos de notificação que o chamador está registrando para receber. Cada evento está associado a uma estrutura de notificação específica que contém informações sobre a alteração que ocorreu. A tabela a seguir lista os valores válidos para ulEventMask e suas estruturas correspondentes.
| Evento de notificação | Estrutura correspondente |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
|
fnevTableModified |
TABLE_NOTIFICATION |
lpAdviseSink
[in] Um ponteiro para o objeto coletor de aconselhamento a ser chamado quando o evento para o qual a notificação foi solicitada ocorrer.
lpulConnection
[out] Um ponteiro para um número de conexão não zero que representa o registro de notificação.
Valor de retorno
S_OK
O registro de notificação foi bem-sucedido.
MAPI_E_INVALID_ENTRYID
O provedor de catálogo de endereços responsável pelo identificador de entrada passado em lpEntryID não pôde registrar uma notificação para a entrada correspondente.
MAPI_E_NO_SUPPORT
A notificação não é compatível com o provedor de catálogo de endereços responsável pelo objeto identificado pelo identificador de entrada passado no parâmetro lpEntryID .
MAPI_E_UNKNOWN_ENTRYID
O identificador de entrada passado em lpEntryID não pode ser manipulado por nenhum dos provedores de catálogo de endereços no perfil.
Comentários
Clientes e provedores de serviços chamam o método Advise para se registrar para um tipo específico ou tipos de notificação em uma entrada de catálogo de endereços. Os tipos de notificação são indicados pela máscara de evento passada com o parâmetro ulEventMask .
O MAPI encaminha essa chamada de Aconselhamento para o provedor de catálogo de endereços responsável pela entrada, conforme indicado pelo identificador de entrada no parâmetro lpEntryID . O provedor de catálogo de endereços manipula o registro em si ou chama o método de suporte, IMAPISupport::Subscribe, para solicitar que MAPI registre o chamador. Um número de conexão não zero é retornado para representar o registro bem-sucedido.
Sempre que ocorre uma alteração na entrada do tipo indicada pelo registro de notificação, o provedor de catálogo de endereços chama o método IMAPIAdviseSink::OnNotify para o objeto coletor de aconselhamento especificado no parâmetro lpAdviseSink . O método OnNotify inclui uma estrutura NOTIFICATION como um parâmetro de entrada que contém dados para descrever o evento.
Dependendo do provedor do catálogo de endereços, a chamada para OnNotify pode ocorrer imediatamente após a alteração no objeto registrado ou posterior. Em sistemas que dão suporte a vários threads de execução, a chamada para OnNotify pode ocorrer em qualquer thread. Os clientes podem solicitar que essas notificações ocorram em um thread específico chamando a função HrThisThreadAdviseSink para criar o objeto de coletor de aconselhamento que é passado para Aconselhar.
Como um provedor de catálogo de endereços pode liberar o objeto de coletor de aconselhamento passado pelos clientes a qualquer momento após a conclusão bem-sucedida da chamada Desaconselhável e antes de uma chamada IAddrBook::Unadvise para cancelar a notificação, os clientes devem liberar seus objetos de coletor de aconselhamento quando o Advise retornar.
Para obter mais informações sobre o processo de notificação, consulte Notificação de Eventos no MAPI.