IMAPISession::Advise
Aplica-se a: Outlook 2013 | Outlook 2016
Registra para receber a notificação de eventos especificados que afetam a sessão.
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 catálogo de endereços ou objeto do repositório de mensagens sobre quais notificações devem ser geradas ou NULL, o que indica que o cliente está se registrando para receber notificações sobre eventos que afetam apenas a sessão.
ulEventMask
[in] Uma máscara de valores que indica os tipos de eventos de notificação nos quais o cliente está interessado e deve ser incluída no registro. Se lpEntryID for NULL, o MAPI registrará automaticamente o cliente em eventos de erro críticos que afetam apenas a sessão. Quando lpEntryID aponta para um identificador de entrada, os seguintes valores são válidos para o parâmetro ulEventMask :
fnevCriticalError
Registra notificações sobre erros graves, como memória insuficiente.
fnevExtended
Registra notificações sobre eventos específicos para um determinado catálogo de endereços ou provedor de repositório de mensagens e sobre o desligamento da sessão.
fnevNewMail
Registra-se para notificações sobre a chegada de novas mensagens.
fnevObjectCreated
Registra notificações sobre a criação de um novo objeto.
fnevObjectCopied
Registra notificações sobre um objeto que está sendo copiado.
fnevObjectDeleted
Registra notificações sobre um objeto que está sendo excluído.
fnevObjectModified
Registra notificações sobre um objeto que está sendo modificado.
fnevObjectMoved
Registra notificações sobre um objeto que está sendo movido.
fnevSearchComplete
Registra notificações sobre a conclusão de uma operação de pesquisa.
lpAdviseSink
[in] Um ponteiro para um objeto coletor de aconselhamento para receber as notificações subsequentes. Esse objeto de coletor de aconselhamento já deve ter sido alocado.
lpulConnection
[out] Um ponteiro para um número não zero que representa a conexão entre o objeto de coletor de aconselhamento do chamador e a sessão.
Valor de retorno
S_OK
O registro foi bem-sucedido.
MAPI_E_INVALID_ENTRYID
O identificador de entrada apontado por lpEntryID não representa um identificador de entrada válido.
MAPI_E_NO_SUPPORT
O provedor de serviços responsável pelo identificador de entrada apontado por lpEntryID não dá suporte ao tipo de eventos especificados no parâmetro ulEventMask ou não dá suporte à notificação.
MAPI_E_UNKNOWN_ENTRYID
O identificador de entrada apontado por lpEntryID não pode ser manipulado por nenhum dos provedores de serviços no perfil.
Comentários
O método IMAPISession::Advise estabelece uma conexão entre o objeto de coletor de aconselhamento do chamador, a sessão e, opcionalmente, um provedor de serviços. Essa conexão é usada para enviar notificações ao coletor de aconselhamento quando um ou mais eventos especificados no parâmetro ulEventMask ocorrem ao objeto apontado por lpEntryID. Quando lpEntryID é NULL, o objeto de destino é a sessão e as notificações são enviadas apenas para erros críticos e eventos estendidos.
Quando lpEntryID aponta para um identificador de entrada válido, o MAPI chama o método Advise do objeto logon que pertence ao provedor de serviços responsável. Por exemplo, se lpEntryID apontar para o identificador de entrada de uma lista de distribuição, o MAPI chamará o método IABLogon::Advise do provedor de catálogo de endereços apropriado.
Para enviar uma notificação, o provedor de serviços ou o MAPI chama o método IMAPIAdviseSink::OnNotify do coletor registrado. Um dos parâmetros para o OnNotify, uma estrutura de notificação, contém informações que descrevem o evento específico.
Notas para chamadores
Em sistemas que dão suporte a vários threads de execução, a chamada para OnNotify também pode ocorrer em qualquer thread a qualquer momento. Se você precisar de garantia de que as notificações ocorrerão apenas em um determinado momento em um thread específico, chame a função HrThisThreadAdviseSink para gerar o objeto de coletor de aconselhamento que você passa para o método Advise .
Para determinar quando um cliente tiver feito logon, registre-se para notificações em seu provedor de serviços chamando Aconselhar com lpEntryID definido como NULL e cbEntryID definidos como 0. Quando o logoff ocorrer, você receberá uma notificação fnevExtended.
Depois que uma chamada para Aconselhar tiver sido bem-sucedida e antes que IMAPISession::Unadvise tenha sido chamada para cancelar o registro, libere seu objeto de coletor de aconselhamento, a menos que você tenha um uso específico de longo prazo para ele.
Para obter uma visão geral do processo de notificação, consulte Notificação de Eventos no MAPI.
Para obter mais informações sobre como lidar com notificações, consulte Tratamento de Notificações.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| BaseDialog.cpp |
CBaseDialog::OnNotificationsOn |
O MFCMAPI usa o método IMAPISession::Advise para se registrar para notificações na sessão. |