IMsgStore::Advise
Aplica-se a: Outlook 2013 | Outlook 2016
Registra para receber a notificação de eventos especificados que afetam o repositório de mensagens.
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 da pasta ou mensagem sobre quais notificações devem ser geradas ou nulas. Se lpEntryID estiver definido como NULL, informe registros para notificações em todo o repositório de mensagens.
ulEventMask
[in] Uma máscara de valores que indica os tipos de eventos de notificação nos quais o chamador está interessado e deve ser incluída no registro. Há uma estrutura notification correspondente associada a cada tipo de evento que contém informações sobre o evento. Veja a seguir valores válidos para o parâmetro ulEventMask :
fnevCriticalError
Registra notificações sobre erros graves, como memória insuficiente.
fnevExtended
Registra para notificações sobre eventos específicos para o provedor de armazenamento de mensagens específico.
fnevNewMail
Registra-se para notificações sobre a chegada de novas mensagens.
fnevObjectCreated
Registra notificações sobre a criação de uma nova pasta ou mensagem.
fnevObjectCopied
Registra notificações sobre uma pasta ou mensagem sendo copiada.
fnevObjectDeleted
Registra notificações sobre uma pasta ou mensagem sendo excluída.
fnevObjectModified
Registra notificações sobre uma pasta ou mensagem sendo modificada.
fnevObjectMoved
Registra notificações sobre uma pasta ou mensagem sendo movida.
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.
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 de conexão não zero que representa a conexão entre o objeto de coletor de aconselhamento do chamador e o repositório de mensagens.
Valor de retorno
S_OK
O registro foi bem-sucedido.
MAPI_E_NO_SUPPORT
O provedor do repositório de mensagens não dá suporte ao registro para notificação por meio do repositório de mensagens.
Comentários
O método IMsgStore::Advise estabelece uma conexão entre o objeto coletor de aconselhamento do chamador e o repositório de mensagens ou um objeto no repositório de mensagens. Essa conexão é usada para enviar notificações ao coletor de aconselhamento quando um ou mais eventos, conforme especificado no parâmetro ulEventMask , ocorrem ao objeto de origem de aconselhamento. Quando o parâmetro lpEntryID aponta para um identificador de entrada válido, a fonte de aconselhamento é o objeto identificado por este identificador de entrada. Quando lpEntryID é NULL, a fonte de aconselhamento é o repositório de mensagens.
Para enviar uma notificação, o provedor do repositório de mensagens ou 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.
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: IMAPISupport::Subscribe, IMAPISupport::Unsubscribe e IMAPISupport::Notify. 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 IUnknown::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 IMsgStore::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 Unadvise tenha sido chamado e concluído.
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 ter certeza de que as notificações ocorrem 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 Aconselhar.
Depois que uma chamada para Aconselhar tiver sido bem-sucedida e antes que a Unadvise seja chamada para cancelar o registro, prepare-se para que o objeto de coletor de aconselhamento seja liberado. 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 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 IMsgStore::Advise para se registrar para notificações em todo o repositório de mensagens. |