IXPLogon::StartMessage
Aplica-se a: Outlook 2013 | Outlook 2016
Inicia a transferência de uma mensagem de entrada do provedor de transporte para o spooler MAPI.
HRESULT StartMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef
);
Parâmetros
ulFlags
[in] Reservados; deve ser zero.
Lpmessage
[in] Um ponteiro para um objeto de mensagem (que representa a mensagem de entrada) que tem permissão de leitura/gravação, que é usado pelo provedor de transporte para acessar e manipular essa mensagem. Esse objeto permanece válido até que o provedor de transporte retorne da chamada para IXPLogon::StartMessage.
lpulMsgRef
[out] Um ponteiro para um valor de referência atribuído à mensagem. O spooler MAPI inicializa esse valor para 1 antes de retornar o ponteiro para o provedor de transporte.
Valor de retorno
S_OK
A chamada foi bem-sucedida e retornou o valor ou valores esperados.
Comentários
O spooler MAPI chama o método IXPLogon::StartMessage para iniciar a transferência de uma mensagem de entrada do provedor de transporte para o spooler MAPI. Antes que o provedor de transporte comece a usar a mensagem apontada por lpMessage, ele deve armazenar uma referência de mensagem no parâmetro lpulMsgRef para uso potencial por uma chamada para o método IXPLogon::TransportNotify .
Durante uma chamada StartMessage , o spooler MAPI processa métodos para objetos abertos durante a transferência da mensagem e também processa todos os anexos. Esse processamento pode levar muito tempo. Os provedores de transporte podem chamar a função de retorno de chamada IMAPISupport::SpoolerYield para o spooler MAPI com frequência durante esse processamento para liberar a hora da CPU para outras tarefas do sistema.
Todos os destinatários na tabela de destinatário que o provedor de transporte cria para a mensagem devem conter todas as propriedades de endereçamento necessárias. Se necessário, o provedor pode construir um destinatário personalizado para representar um destinatário específico. No entanto, se o provedor puder produzir uma entrada de destinatário que inclua mais informações, ele deverá fazê-lo. Por exemplo, se um provedor de transporte tiver informações suficientes sobre o formato de destinatário de um provedor de catálogo de endereços que pode criar um identificador de entrada válido para um destinatário para esse formato, ele deverá criar o identificador de entrada.
Se quaisquer propriedades nãotransmittáveis forem recebidas, o provedor de transporte não deverá armazená-las na nova mensagem. No entanto, o provedor de transporte deve armazenar todas as propriedades transmitíveis que recebe na nova mensagem.
Se a mensagem de entrada for um relatório de entrega ou um relatório não detalhado e o provedor de transporte não puder usar o método IMAPISupport::StatusRecips para gerar o relatório da mensagem original, o provedor deverá preencher a mensagem com as propriedades apropriadas. No entanto, o provedor de transporte não pode definir a propriedade PR_ENTRYID da mensagem (PidTagEntryId).
Para salvar a mensagem de entrada no repositório de mensagens MAPI apropriado após o processamento, o provedor de transporte chama o método IMAPIProp::SaveChanges . Se o provedor de transporte não tiver nenhuma mensagem para passar para o spooler MAPI, ele poderá parar a mensagem de entrada retornando da chamada StartMessage sem chamar SaveChanges.
Todos os objetos abertos pelo provedor de transporte durante uma chamada StartMessage devem ser liberados antes de retornar. No entanto, o provedor não deve liberar o objeto de mensagem que o spooler MAPI originalmente passou no parâmetro lpMessage .
Se StartMessage retornar um erro, a mensagem em processo será liberada sem ter alterações salvas e será perdida. Nesse caso, o provedor de transporte deve passar o sinalizador NOTIFY_CRITICAL_ERROR com uma chamada para o método IMAPISupport::SpoolerNotify e chamar o método IXPLogon::P oll para notificar o spooler MAPI de que ele está em uma condição de erro grave.
Para obter mais informações, consulte Interação com o Spooler MAPI.