Função de retorno de chamada MAPISAVEMAIL (mapi.h)

Artigo
08/24/2023

[O uso dessa função é desencorajado. Ele pode estar alterado ou indisponível nas versões subsequentes do Windows.]

A função MAPISaveMail salva uma mensagem no repositório de mensagens.

Sintaxe

MAPISAVEMAIL Mapisavemail;

ULONG Mapisavemail(
  [in] LHANDLE lhSession,
  [in] ULONG_PTR ulUIParam,
  [in] lpMapiMessage lpMessage,
  [in] FLAGS flFlags,
       ULONG ulReserved,
  [in] LPSTR lpszMessageID
)
{...}

Parâmetros

[in] lhSession

Manipule para uma sessão MAPI simples ou zero. O valor do parâmetro lhSession não deve ser zero se o parâmetro lpszMessageID contiver um identificador de mensagem válido. No entanto, se lpszMessageID não contiver um identificador de mensagem válido e o valor de lhSession for zero, MAPI fará logon no usuário e criará uma sessão que existe apenas durante a chamada. Essa sessão temporária pode ser uma sessão compartilhada existente ou uma nova. Se necessário, a caixa de diálogo de logon será exibida.

[in] ulUIParam

Identificador de janela pai ou zero, indicando que, se uma caixa de diálogo for exibida, ela será modal do aplicativo. Se o parâmetro ulUIParam contiver um identificador de janela pai, ele será do tipo HWND (convertido em um ULONG_PTR). Se nenhuma caixa de diálogo for exibida durante a chamada, ulUIParam será ignorado.

[in] lpMessage

Parâmetro de entrada que aponta para uma estrutura MapiMessage que contém o conteúdo da mensagem a ser salva. O membro lpOriginator é ignorado. Os aplicativos podem ignorar o membro flFlags ou, se a mensagem nunca tiver sido salva, podem definir os sinalizadores MAPI_SENT e MAPI_UNREAD.

[in] flFlags

Máscara de bits de sinalizadores de opção. Os sinalizadores a seguir podem ser definidos.

Valor	Significado
MAPI_LOGON_UI	Uma caixa de diálogo deve ser exibida para solicitar que o usuário faça logon, se necessário. Quando o sinalizador MAPI_LOGON_UI não estiver definido, o aplicativo cliente não exibirá uma caixa de diálogo de logon e retornará um valor de erro se o usuário não estiver conectado. MAPISaveMail ignorará esse sinalizador se o parâmetro lpszMessageID estiver vazio.
MAPI_LONG_MSGID	Espera-se que o identificador de mensagem retornado tenha 512 caracteres. Se esse sinalizador estiver definido, o parâmetro lpszMessageID deverá ser grande o suficiente para acomodar 512 caracteres.
MAPI_NEW_SESSION	Uma tentativa deve ser feita para criar uma nova sessão em vez de adquirir a sessão compartilhada do ambiente. Se o sinalizador MAPI_NEW_SESSION não estiver definido, MAPISaveMail usará uma sessão compartilhada existente.

ulReserved

Reservados; deve ser zero.

[in] lpszMessageID

Ponteiro para o identificador de mensagem a ser substituído pela operação de salvamento ou uma cadeia de caracteres vazia, indicando que uma nova mensagem deve ser criada. A cadeia de caracteres deve ser alocada pelo chamador e deve ser capaz de conter pelo menos 512 caracteres se o parâmetro flFlags estiver definido como MAPI_LONG_MSGID. Se o parâmetro flFlags não estiver definido como MAPI_LONG_MSGID, a cadeia de caracteres do identificador de mensagem poderá conter 64 caracteres.

Valor retornado

Essa função retorna um dos valores a seguir.

Código de retorno	Descrição
MAPI_E_ATTACHMENT_NOT_FOUND	Não foi possível localizar um anexo no caminho especificado. A letra da unidade era inválida, o caminho não foi encontrado nessa unidade ou o arquivo não foi encontrado nesse caminho.
MAPI_E_BAD_RECIPTYPE	O tipo de destinatário no lpMessage era inválido.
MAPI_E_FAILURE	Ocorreu um ou mais erros não especificados ao salvar a mensagem. Nenhuma mensagem foi salva.
MAPI_E_INSUFFICIENT_MEMORY	Não havia memória suficiente para salvar a mensagem. Nenhuma mensagem foi salva.
MAPI_E_INVALID_MESSAGE	Um identificador de mensagem inválido foi passado no parâmetro lpszMessageID ; nenhuma mensagem foi salva.
MAPI_E_INVALID_RECIPS	Um ou mais destinatários da mensagem eram inválidos ou não podiam ser identificados.
MAPI_E_INVALID_SESSION	Um identificador de sessão inválido foi passado no parâmetro lhSession . Nenhuma mensagem foi salva.
MAPI_E_LOGIN_FAILURE	Não havia nenhum logon padrão e o usuário não conseguiu fazer logon com êxito quando a caixa de diálogo de logon foi exibida. Nenhuma mensagem foi salva.
MAPI_E_NOT_SUPPORTED	A operação não era compatível com o sistema de mensagens subjacente.
MAPI_E_USER_ABORT	O usuário cancelou uma das caixas de diálogo. Nenhuma mensagem foi salva.
SUCCESS_SUCCESS	A chamada foi bem-sucedida e a mensagem foi salva.

Comentários

A função MAPISaveMail salva uma mensagem, substituindo opcionalmente uma mensagem existente. Antes de chamar MAPISaveMail, use a função MAPIFindNext para verificar se a mensagem a ser salva é aquela que você deseja salvar. Os elementos da mensagem identificada pelo parâmetro lpszMessageID são substituídos pelos elementos no parâmetro lpMessage . Se lpszMessageID estiver vazio, uma nova mensagem será criada. Todas as mensagens substituídas são salvas em suas pastas apropriadas. Novas mensagens são salvas na pasta apropriada para mensagens de entrada dessa classe.

Nem todos os sistemas de mensagens dão suporte ao armazenamento de mensagens. Se o sistema de mensagens subjacente não oferecer suporte ao armazenamento de mensagens, MAPISaveMail retornará o valor MAPI_E_NOT_SUPPORTED.

Como os identificadores de mensagem são específicos do sistema e opacos e podem ser invalidados a qualquer momento, MAPISaveMail considera um identificador de mensagem válido apenas para a sessão mapi simples atual. MAPISaveMail manipula identificadores de mensagem inválidos retornando o valor MAPI_E_INVALID_MESSAGE.