IMSLogon::Advise
Aplica-se a: Outlook 2013 | Outlook 2016
Registra um objeto com um provedor de armazenamento de mensagens para notificações sobre alterações no repositório de mensagens. Em seguida, o repositório de mensagens enviará notificações sobre alterações no objeto registrado.
HRESULT Advise(
ULONG cbEntryID,
LPENTRYID lpEntryID,
ULONG ulEventMask,
LPMAPIADVISESINK lpAdviseSink,
ULONG FAR * lpulConnection
);
Parâmetros
cbEntryID
[in] O tamanho, em bytes, do 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. Esse objeto pode ser uma pasta, uma mensagem ou qualquer outro objeto no repositório de mensagens. Como alternativa, se MAPI definir o parâmetro cbEntryID como 0 e passar nulo para lpEntryID, o coletor de aconselhamento fornecerá notificações sobre alterações em todo o repositório de mensagens.
ulEventMask
[in] Uma máscara de evento dos tipos de eventos de notificação que ocorrem para o objeto sobre o qual o MAPI gerará notificações. A máscara filtra casos específicos. Cada tipo de evento tem uma estrutura associada a ela que contém informações adicionais sobre o evento. A tabela a seguir lista os possíveis tipos de evento junto com suas estruturas correspondentes.
| Tipo de evento de notificação | Estrutura correspondente |
|---|---|
| fnevCriticalError |
ERROR_NOTIFICATION |
| fnevNewMail |
NEWMAIL_NOTIFICATION |
| fnevObjectCreated |
OBJECT_NOTIFICATION |
| fnevObjectDeleted |
OBJECT_NOTIFICATION |
| fnevObjectModified |
OBJECT_NOTIFICATION |
| fnevObjectCopied |
OBJECT_NOTIFICATION |
| fnevObjectMoved |
OBJECT_NOTIFICATION |
| fnevSearchComplete |
OBJECT_NOTIFICATION |
| fnevStatusObjectModified |
STATUS_OBJECT_NOTIFICATION |
lpAdviseSink
[in] Um ponteiro para um objeto coletor de aconselhamento a ser chamado quando ocorrer um evento para o objeto de sessão sobre qual notificação foi solicitada. Esse objeto de coletor de aconselhamento já deve existir.
lpulConnection
[out] Um ponteiro para uma variável que, após um retorno bem-sucedido, contém o número de conexão do registro de notificação. O número de conexão deve não ser zero.
Valor de retorno
S_OK
A chamada foi bem-sucedida e retornou o valor ou valores esperados.
MAPI_E_NO_SUPPORT
A operação não tem suporte por MAPI ou por um ou mais provedores de serviços.
Comentários
Os provedores do repositório de mensagens implementam o método IMSLogon::Advise para registrar um objeto para retornos de chamada de notificação. Sempre que ocorre uma alteração no objeto indicado, o provedor verifica para ver qual bit de máscara de evento foi definido no parâmetro ulEventMask e, portanto, qual tipo de alteração ocorreu. Se um bit for definido, o provedor chamará o método IMAPIAdviseSink::OnNotify para o objeto de coletor de aconselhamento indicado pelo parâmetro lpAdviseSink para relatar o evento. Os dados passados na estrutura de notificação para a rotina OnNotify descrevem o evento.
A chamada para OnNotify pode ocorrer durante a chamada que altera o objeto ou em qualquer momento posterior. Em sistemas que dão suporte a vários threads de execução, a chamada para OnNotify pode ocorrer em qualquer thread. Para lidar com segurança com uma chamada para OnNotify que pode acontecer em um momento inoportuno, um aplicativo cliente deve usar a função HrThisThreadAdviseSink .
Para fornecer notificações, o provedor do repositório de mensagens que implementa o Advise precisa manter uma cópia do ponteiro para o objeto de coletor lpAdviseSink ; para fazer isso, o provedor chama o método IUnknown::AddRef para o coletor de aconselhamento para manter seu ponteiro de objeto até que o registro de notificação seja cancelado com uma chamada para o método IMSLogon::Unadvise . A implementação do Advise deve atribuir um número de conexão ao registro de notificação e chamar AddRef nesse número de conexão antes de devolvê-lo no parâmetro lpulConnection . Os provedores de serviço podem liberar o objeto coletor de aconselhamento antes que o registro seja cancelado, mas eles não devem liberar o número de conexão até que o Unadvise seja chamado.
Depois que uma chamada para Aconselhar tiver sido bem-sucedida e antes da Unadvise ser chamada, os provedores devem estar preparados para que o objeto de coletor de aconselhamento seja liberado. Portanto, um provedor deve liberar seu objeto coletor de aconselhamento após o retorno do Advise, a menos que ele 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.