IMAPIProp::SaveChanges

Aplica-se a: Outlook 2013 | Outlook 2016

Faz alterações permanentes que foram feitas em um objeto desde a última operação de salvamento.

HRESULT SaveChanges(
  ULONG ulFlags
);

Parâmetros

ulFlags

[in] Um bitmask de sinalizadores que controla o que acontece com o objeto quando o método IMAPIProp::SaveChanges é chamado. Os seguintes sinalizadores podem ser definidos:

NON_EMS_XP_SAVE

Indica que a mensagem não foi entregue de um Microsoft Exchange Server. Esse sinalizador deve ser usado em combinação com o método IMAPIFolder::CreateMessage e o sinalizador ITEMPROC_FORCE para indicar a um repositório PST que a mensagem é qualificada para processamento de regras antes que o repositório PST (arquivo pastas pessoais) notifique qualquer cliente ouvinte que a mensagem tenha chegado. Esse processamento de regras só se aplica a novas mensagens criadas com IMAPIFolder::CreateMessage em um servidor que não é um Exchange Server, nesse caso, o Exchange Server já teria processado regras na mensagem.

FORCE_SAVE

As alterações devem ser gravadas no objeto, substituindo as alterações anteriores feitas no objeto e o objeto deve ser fechado. A permissão de leitura/gravação deve ser definida para que a operação tenha êxito. O sinalizador FORCE_SAVE é usado após uma chamada anterior para SaveChanges retornada MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

As alterações devem ser confirmadas e o objeto deve ser mantido aberto para leitura. Nenhuma alteração adicional será feita.

KEEP_OPEN_READWRITE

As alterações devem ser confirmadas e o objeto deve ser mantido aberto para permissão de leitura/gravação. Esse sinalizador geralmente é definido quando o objeto foi aberto pela primeira vez para permissão de leitura/gravação. Alterações subsequentes no objeto são permitidas.

MAPI_DEFERRED_ERRORS

Permite que SaveChanges retorne com êxito, possivelmente antes que as alterações sejam totalmente confirmadas.

SPAMFILTER_ONSAVE

Habilita a filtragem de spam em uma mensagem que está sendo salva. O suporte à filtragem de spam está disponível somente se o tipo de endereço de email do remetente for SMTP(Simple Mail Transfer Protocol) e a mensagem estiver sendo salva em um repositório de um arquivo de pastas particulares (PST).

Valor de retorno

S_OK

O compromisso das mudanças foi bem-sucedido.

MAPI_E_NO_ACCESS

SaveChanges não poderá manter o objeto aberto para permissão somente leitura se KEEP_OPEN_READONLY estiver definido ou a permissão de leitura/gravação se KEEP_OPEN_READWRITE estiver definido. Nenhuma alteração foi confirmada.

MAPI_E_OBJECT_CHANGED

O objeto foi alterado desde que foi aberto.

MAPI_E_OBJECT_DELETED

O objeto foi excluído desde que foi aberto.

Comentários

O método IMAPIProp::SaveChanges torna as alterações de propriedade permanentes para objetos que dão suporte ao modelo de transação de processamento, como mensagens, anexos, contêineres de catálogo de endereços e objetos de usuário de mensagens. Objetos que não dão suporte a transações, como pastas, repositórios de mensagens e seções de perfil, tornam as alterações permanentes imediatamente. Nenhuma chamada para SaveChanges é necessária.

Como os provedores de serviços não precisam gerar um identificador de entrada para seus objetos até que todas as propriedades tenham sido salvas, a propriedade PR_ENTRYID (PidTagEntryId) de um objeto pode não estar disponível até que seu método SaveChanges tenha sido chamado. Alguns provedores esperam até que o sinalizador KEEP_OPEN_READONLY seja definido na chamada SaveChanges . KEEP_OPEN_READONLY indica que as alterações a serem salvas na chamada atual serão as últimas alterações que serão feitas no objeto.

Algumas implementações do repositório de mensagens não mostram mensagens recém-criadas em uma pasta até que um cliente salve as alterações da mensagem usando SaveChanges e libere os objetos de mensagem usando o método IUnknown::Release . Além disso, algumas implementações de objeto não podem gerar uma propriedade PR_ENTRYID para um objeto recém-criado até que o SaveChanges tenha sido chamado, e alguns só podem fazê-lo depois que SaveChanges tiver sido chamado usando KEEP_OPEN_READONLY definido em ulFlags.

Observações para implementadores

Se você receber o sinalizador KEEP_OPEN_READONLY, terá a opção de deixar o acesso do objeto como leitura/gravação. No entanto, um provedor nunca pode deixar um objeto em um estado somente leitura quando o sinalizador de KEEP_OPEN_READWRITE é passado.

Quando um cliente salva vários anexos em várias mensagens, ele chama o método SaveChanges para cada anexo e cada mensagem. Geralmente, os clientes definem MAPI_DEFERRED_ERRORS para cada uma dessas chamadas, exceto para a última. Você pode retornar erros com a última chamada ou chamadas anteriores. Você pode até ignorar o sinalizador.

Se KEEP_OPEN_READWRITE ou KEEP_OPEN_READONLY estiver configurado junto com MAPI_DEFERRED_ERRORS, você poderá ignorar a solicitação de adiamento de erro. Se MAPI_DEFERRED_ERRORS não estiver definido em ulFlags, um dos erros adiados anteriormente poderá ser retornado para a chamada SaveChanges .

Se um provedor de transporte remoto fornece uma implementação funcional desse método é opcional e depende de outras opções de design em sua implementação. Se você implementar esse método, faça isso de acordo com a documentação aqui. Como objetos de pasta e objetos status não são transacionados, no mínimo, a implementação do SaveChanges por um provedor de transporte remoto deve retornar S_OK sem realmente fazer nenhum trabalho.

Notas para chamadores

Se um cliente passar KEEP_OPEN_READONLY, chamar o método IMAPIProp::SetProps e chamar SaveChanges novamente, a mesma implementação poderá falhar.

Depois de receber MAPI_E_NO_ACCESS de uma chamada na qual você definiu KEEP_OPEN_READWRITE, você continuará a ter permissão de leitura/gravação para o objeto. Você pode chamar SaveChanges novamente, passando o sinalizador KEEP_OPEN_READONLY ou sem sinalizadores com KEEP_OPEN_SUFFIX.

Se um provedor dá suporte ao sinalizador de KEEP_OPEN_READWRITE depende da implementação do provedor.

Para indicar que a única chamada a ser feita no objeto após SaveChanges é IUnknown::Release, não defina sinalizadores para o parâmetro ulFlags . Um erro do SaveChanges indica que ele não pôde tornar as alterações pendentes permanentes. Provedores diferentes lidam com a ausência de sinalizadores na chamada SaveChanges de forma diferente. Alguns provedores tratam esse estado da mesma forma que KEEP_OPEN_READONLY; outros provedores interpretam o mesmo que KEEP_OPEN_READWRITE. Outros provedores ainda desligam o objeto quando não recebem sinalizadores na chamada SaveChanges .

Algumas propriedades, normalmente calculadas, não podem ser processadas até que você chame SaveChanges e, em alguns casos, Release.

Quando você faz alterações em massa, como salvar anexos em várias mensagens, adiar o processamento de erros definindo o sinalizador MAPI_DEFERRED_ERRORS em ulFlags. Se você salvar vários anexos em várias mensagens, faça uma chamada saveChanges para cada anexo e uma chamada SaveChanges para cada mensagem. Defina o sinalizador MAPI_DEFERRED_ERRORS para cada chamada de anexo e para todas as mensagens, exceto para a última.

Se o SaveChanges retornar MAPI_E_OBJECT_CHANGED, marcar se o objeto original foi modificado. Em caso afirmativo, avise o usuário, que pode solicitar que as alterações substituam as alterações anteriores ou salvem o objeto em outro lugar. Se o objeto original tiver sido excluído, avise o usuário para dar a ele a oportunidade de salvar o objeto em outro local.

Você não pode chamar SaveChanges com o sinalizador FORCE_SAVE em um objeto aberto que foi excluído.

Se SaveChanges retornar um erro, o objeto cujas alterações devem ser salvas permanecerá aberto, independentemente dos sinalizadores definidos no parâmetro ulFlags .

Importante

O NON_EMS_XP_SAVE e SPAMFILTER_ONSAVE ulFlags pode não ser definido no arquivo de cabeçalho para download que você tem atualmente, nesse caso, você pode adicioná-lo ao código usando os seguintes valores: #define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

Para obter mais informações, consulte Salvar propriedades MAPI.

Confira também

IMAPIProp::SetProps
Propriedade Canônica PidTagEntryId
IMAPIProp: IUnknownSaving MAPI Properties