IXPLogon::SubmitMessage
Aplica-se a: Outlook 2013 | Outlook 2016
Indica que o spooler MAPI tem uma mensagem para o provedor de transporte entregar.
HRESULT SubmitMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
);
Parâmetros
ulFlags
[in] Um bitmask de sinalizadores que controla como a mensagem é enviada. O seguinte sinalizador pode ser definido:
BEGIN_DEFERRED
O spooler MAPI está chamando um provedor de transporte com uma mensagem que foi adiada anteriormente. O identificador de entrada da mensagem é o mesmo de quando foi adiado. A mensagem foi adiada passando seu identificador de entrada de volta para o spooler MAPI usando o método IMAPISupport::SpoolerNotify com o sinalizador NOTIFY_SENTDEFERRED.
Lpmessage
[in] Um ponteiro para um objeto de mensagem (que representa a mensagem a ser entregue) que tem permissão de leitura/gravação, que o provedor de transporte usa para acessar e manipular essa mensagem. Esse objeto permanece válido até que o provedor de transporte retorne de uma chamada subsequente para o método IXPLogon::EndMessage .
lpulMsgRef
[out] Um ponteiro para uma variável na qual o provedor de transporte retorna o valor de referência atribuído a essa mensagem. O spooler MAPI passa esse valor de referência em chamadas subsequentes para esta mensagem. O spooler MAPI inicializa o valor para 0 antes de devolvê-lo ao provedor de transporte.
lpulReturnParm
[out] Um ponteiro para uma variável que corresponde ao valor de erro MAPI_E_WAIT ou MAPI_E_NETWORK_ERROR retornado pelo SubmitMessage.
Valor de retorno
S_OK
A chamada foi bem-sucedida e retornou o valor ou valores esperados.
MAPI_E_BUSY
O provedor de transporte não pode lidar com a mensagem porque está executando outra operação. Um provedor deve usar esse valor retornado para indicar que nenhum processamento ocorreu e que o spooler MAPI não deve chamar EndMessage. O spooler MAPI tentará a chamada SubmitMessage novamente mais tarde.
MAPI_E_CANCEL
Embora o provedor de transporte tenha solicitado que o spooler MAPI reenviasse a mensagem em uma chamada SpoolerNotify anterior, as condições foram alteradas desde então e a mensagem não deve ser ressentida. O spooler MAPI continuará a lidar com outra coisa.
MAPI_E_NETWORK_ERROR
Um erro de rede impediu a conclusão bem-sucedida da operação. O parâmetro lpulReturnParm deve ser definido como o número de segundos que será decorrido antes que o spooler MAPI reenvia a mensagem.
MAPI_E_NOT_ME
O provedor de transporte não pode lidar com essa mensagem. O spooler MAPI deve tentar encontrar outro provedor de transporte para ele. Um provedor deve usar esse valor retornado para indicar que nenhum processamento ocorreu e que o spooler MAPI não deve chamar EndMessage.
MAPI_E_WAIT
Um problema temporário impede que o provedor de transporte manuseie a mensagem. O parâmetro lpulReturnParm deve ser definido como o número de segundos que será decorrido antes que o spooler MAPI reenvia a mensagem.
Comentários
O spooler MAPI chama o método IXPLogon::SubmitMessage quando tem uma mensagem para o provedor de transporte entregar. A mensagem é passada para o provedor de transporte usando o parâmetro lpMessage .
Se o provedor estiver pronto para aceitar a mensagem, ele deverá retornar um valor de referência usando o parâmetro lpulMsgRef , processar o objeto passado e retornar o valor apropriado (geralmente S_OK). Se o provedor não estiver preparado para lidar com a transferência, ele deverá retornar um valor de erro e, opcionalmente, outro valor de retorno MAPI em lpulReturnParm para indicar quanto tempo o spooler MAPI deve aguardar antes de reenviar a mensagem.
A implementação desse método por um provedor de transporte pode fazer o seguinte:
Coloque a mensagem em uma fila interna para aguardar a transmissão, possivelmente copiando a mensagem para o armazenamento local e retornando.
Tente executar a transmissão real e retornar quando a transmissão for concluída, com êxito ou sem sucesso.
Determine se deve enviar a mensagem depois de verificar o recurso envolvido. Nesse caso, se o recurso for gratuito, o provedor poderá bloquear o recurso, preparar a mensagem e enviá-la. Se o recurso estiver ocupado, o provedor poderá preparar a mensagem e adiar o envio para uma hora posterior.
A técnica preferencial para transmissão de mensagens depende do provedor de transporte e do número esperado de processos que competem pelos recursos do sistema.
Durante uma chamada SubmitMessage , o provedor de transporte controla a transferência de dados de mensagem do objeto de mensagem. No entanto, o provedor de transporte deve atribuir um valor de referência à mensagem, à qual retorna um ponteiro em lpulMsgRef, antes de transferir dados. Ele faz isso porque, em qualquer momento durante o processo, o spooler MAPI pode chamar o método IXPLogon::TransportNotify com o sinalizador NOTIFY_CANCEL_MESSAGE definido para sinalizar ao provedor que ele deve liberar quaisquer objetos abertos e interromper a transferência de mensagens.
O provedor de transporte não deve enviar nenhuma propriedade não remessada da mensagem. Quando encontrar tal propriedade, ela deve continuar a processar a próxima propriedade. O provedor deve fazer todos os esforços para não exibir MAPI_P1 informações do destinatário como parte do conteúdo da mensagem transmitida; o provedor deve usar essas informações de destinatário apenas para fins de endereçamento. MAPI_P1 destinatários são destinatários gerados internamente que são usados para reenviar mensagens; elas não devem ser transmitidas. Em vez disso, use os outros destinatários para transmitir informações do destinatário. A finalidade desse arranjo é permitir que os destinatários de reenviação vejam exatamente a mesma tabela de destinatários que os destinatários originais.
Durante uma chamada SubmitMessage , o spooler MAPI processa métodos para objetos abertos durante a transferência da mensagem e processa todos os anexos. Esse processamento pode levar muito tempo. Os provedores de transporte podem chamar o método IMAPISupport::SpoolerYield para o carreador MAPI com frequência durante esse processamento para liberar o tempo da CPU para outras tarefas do sistema.
Todos os destinatários de mensagens estão visíveis na tabela do destinatário da mensagem que o spooler MAPI passou originalmente. O provedor de transporte deve processar apenas os destinatários que ele pode manipular - com base no identificador de entrada, tipo de endereço ou ambos - e que ainda não têm sua propriedade PR_RESPONSIBILITY (PidTagResponsibility) definida como TRUE. Se PR_RESPONSIBILITY já estiver definido como TRUE, outro provedor de transporte tratará esse destinatário. Quando o provedor concluir o processamento suficiente de um destinatário para determinar se ele pode lidar com mensagens para esse destinatário, ele deve definir a propriedade PR_RESPONSIBILITY do destinatário como TRUE na mensagem passada. Normalmente, o provedor faz essa determinação após a conclusão da entrega de mensagens.
Normalmente, o provedor de transporte não retorna de uma chamada SubmitMessage até concluir a transferência de dados de mensagem. Se nenhum erro for retornado, a próxima chamada do spooler MAPI para o provedor será uma chamada para o método IXPLogon::EndMessage .
Se SubmitMessage retornar um erro, o spooler MAPI liberará a mensagem em processo sem salvar alterações. Se o provedor de transporte exigir alterações de mensagem a serem salvas, ele deverá chamar o método IMAPIProp::SaveChanges na mensagem antes de retornar.
No caso de erros que ocorrem devido a problemas de transporte, o spooler MAPI mantém a mensagem, mas atrasa a reenviação da mensagem para o provedor de transporte com base no valor retornado em lpulReturnParm. O provedor de transporte deve preencher esse valor se o valor retornado do SubmitMessage for MAPI_E_WAIT ou MAPI_E_NETWORK_ERROR. Se ocorrer uma condição de erro grave, o provedor de transporte deverá chamar o método IMAPISupport::SpoolerNotify com o sinalizador NOTIFY_CRITICAL_ERROR.