IABLogon::Advise
Aplica-se a: Outlook 2013 | Outlook 2016
Registra o chamador para receber a notificação de eventos especificados que afetam um contêiner, usuário de mensagens ou lista de distribuição.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parâmetros
cbEntryID
[in] A contagem de bytes no identificador de entrada apontado pelo parâmetro lpEntryID .
Lpentryid
[in] Um ponteiro para o identificador de entrada do objeto sobre quais notificações devem ser geradas.
ulEventMask
[in] Um bitmask de valores que indicam os tipos de eventos de notificação nos quais o chamador está interessado e deve ser incluído no registro. Há uma estrutura notification correspondente associada a cada tipo de evento que contém informações sobre o evento. A tabela a seguir lista os valores válidos para o parâmetro ulEventMask e as estruturas associadas a cada valor.
| Tipo de evento de notificação | Estrutura notification correspondente |
|---|---|
|
fnevCriticalError |
ERROR_NOTIFICATION |
|
fnevObjectCreated |
OBJECT_NOTIFICATION |
|
fnevObjectDeleted |
OBJECT_NOTIFICATION |
|
fnevObjectModified |
OBJECT_NOTIFICATION |
|
fnevObjectCopied |
OBJECT_NOTIFICATION |
|
fnevObjectMoved |
OBJECT_NOTIFICATION |
lpAdviseSink
[in] Um ponteiro para um objeto coletor de aconselhamento para receber as notificações subsequentes.
lpulConnection
[out] Um ponteiro para um valor 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 identificador de entrada passado no parâmetro lpEntryID não está no formato apropriado.
MAPI_E_NO_SUPPORT
O provedor de catálogo de endereços não dá suporte à notificação, possivelmente porque não permite que alterações sejam feitas em seus objetos.
MAPI_E_UNKNOWN_ENTRYID
O provedor de catálogo de endereços não pode lidar com o identificador de entrada passado em lpEntryID.
Comentários
Os provedores de catálogo de endereços implementam o método IABLogon::Advise para registrar o chamador a ser notificado quando ocorrer uma alteração em um objeto em um de seus contêineres. Os chamadores podem se registrar para notificações sobre usuários de mensagens, listas de distribuição ou contêineres inteiros.
Os clientes normalmente chamam o método IAddrBook::Advise para se registrar em notificações do catálogo de endereços. MAPI então chama o método Advise do provedor de catálogo de endereços responsável pelo objeto representado pelo identificador de entrada em lpEntryID.
Quando ocorre uma alteração no objeto indicado do tipo representado em ulEventMask, uma chamada é feita para o método OnNotify do coletor de aconselhamento apontado por lpAdviseSink. Os dados passados na estrutura NOTIFICATION para a rotina OnNotify descrevem o evento.
Observações para implementadores
Você pode dar suporte à notificação com ou sem ajuda do MAPI. O MAPI tem três métodos de objeto de suporte para ajudar os provedores de serviços a implementar a notificação:
Se você optar por usar os métodos de suporte mapi, chame Assinar quando seu método Desaconselhá-lo e libere o ponteiro lpAdviseSink .
Se você optar por dar suporte à notificação por conta própria, chame o método AddRef do coletor de aconselhamento representado pelo parâmetro lpAdviseSink para manter uma cópia deste ponteiro. Mantenha essa cópia até que o método IABLogon::Unadvise seja chamado para cancelar o registro.
Independentemente de como você dá suporte à notificação, atribua um número de conexão não zero ao registro de notificação e retorne-o no parâmetro lpulConnection . Não libere esse número de conexão até que o método Unadvise tenha sido chamado.
Notas para chamadores
O ponteiro de coletor de aconselhamento que você passa no parâmetro lpAdviseSink para Aconselhar pode apontar para um objeto que você criou ou que o MAPI criou por meio da função HrThisThreadAdviseSink . Talvez você queira usar HrThisThreadAdviseSink se você dá suporte a vários threads de execução e deseja ter certeza de que as chamadas subsequentes para o método OnNotify ocorrem em um momento apropriado em um thread apropriado.
Prepare-se para que seu objeto de coletor de aconselhamento seja liberado a qualquer momento após sua chamada para Aconselhar e antes de sua chamada para Unadvise. Portanto, você deve liberar seu objeto coletor de aconselhamento após o retorno do Advise , a menos que você tenha um uso específico de longo prazo para ele.
Para obter mais informações sobre o processo de notificação, consulte Notificação de Eventos no MAPI. Para obter informações sobre como usar os métodos IMAPISupport para dar suporte à notificação, consulte Notificação de Evento de Suporte. Para obter mais informações sobre multithreading e MAPI, consulte Threading no MAPI.