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

Artigo
03/09/2023

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

A função MAPIReadMail recupera uma mensagem para leitura.

Sintaxe

MAPIREADMAIL Mapireadmail;

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

Parâmetros

[in] lhSession

Manipule para uma sessão MAPI simples. O valor do parâmetro lhSession deve representar uma sessão válida; não pode ser zero.

[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] lpszMessageID

Ponteiro para uma cadeia de caracteres de identificador de mensagem para que a mensagem seja lida. A cadeia de caracteres é alocada pelo chamador.

[in] flFlags

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

Valor	Significado
MAPI_BODY_AS_FILE	MAPIReadMail deve gravar o texto da mensagem em um arquivo temporário e adicioná-lo como o primeiro anexo na lista de anexos.
MAPI_ENVELOPE_ONLY	MAPIReadMail deve ler somente o cabeçalho da mensagem. Os anexos de arquivo não são copiados para arquivos temporários e nem nomes de arquivo temporários nem texto de mensagem são gravados. Definir esse sinalizador melhora o desempenho.
MAPI_PEEK	MAPIReadMail não marca a mensagem como lida. Marcar uma mensagem como lida afeta sua aparência na interface do usuário e gera um recibo de leitura. Se o sistema de mensagens não der suporte a esse sinalizador, MAPIReadMail sempre marcará a mensagem como lida. Se MAPIReadMail encontrar um erro, ele deixará a mensagem não lida.
MAPI_SUPPRESS_ATTACH	MAPIReadMail não deve copiar anexos de arquivo, mas deve gravar texto de mensagem na estrutura MapiMessage . MAPIReadMail ignorará esse sinalizador se o aplicativo de chamada tiver definido o sinalizador MAPI_ENVELOPE_ONLY. Definir o sinalizador MAPI_SUPPRESS_ATTACH melhora o desempenho.

ulReserved

Reservados; deve ser zero.

lppMessage

Valor retornado

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

Código de retorno	Descrição
MAPI_E_ATTACHMENT_WRITE_FAILURE	Não foi possível gravar um anexo em um arquivo temporário. Verifique as permissões de diretório.
MAPI_E_DISK_FULL	Não foi possível gravar um anexo em um arquivo temporário porque não havia espaço suficiente no disco.
MAPI_E_FAILURE	Ocorreu um ou mais erros não especificados durante a leitura da mensagem.
MAPI_E_INSUFFICIENT_MEMORY	Não havia memória suficiente para ler a mensagem.
MAPI_E_INVALID_MESSAGE	Um identificador de mensagem inválido foi passado no parâmetro lpszMessageID .
MAPI_E_INVALID_SESSION	Um identificador de sessão inválido foi passado no parâmetro lhSession . Nenhuma mensagem foi recuperada.
MAPI_E_TOO_MANY_FILES	Havia muitos anexos de arquivo na mensagem. A mensagem não pôde ser lida.
MAPI_E_TOO_MANY_RECIPIENTS	Havia muitos destinatários da mensagem. A mensagem não pôde ser lida.
SUCCESS_SUCCESS	A chamada foi bem-sucedida e a mensagem foi lida.

Comentários

A função MAPIReadMail retorna uma mensagem, dividindo o conteúdo da mensagem nos mesmos parâmetros e estruturas usados na função MAPISendMail . MAPIReadMail preenche um bloco de memória com a estrutura MapiMessage que contém elementos de mensagem, como o assunto, a classe de mensagem, o tempo de entrega e o remetente. Os anexos de arquivo são salvos em arquivos temporários e os nomes são retornados ao chamador na estrutura da mensagem. Destinatários, anexos e conteúdo são copiados da mensagem antes que MAPIReadMail retorne ao chamador, portanto, alterações posteriores nos arquivos não afetam o conteúdo da mensagem.

Um sinalizador é fornecido para especificar que apenas as informações do envelope devem ser retornadas da chamada. Outro sinalizador (na estrutura MapiMessage ) especifica se a mensagem está marcada como enviada ou não.

O chamador é responsável por liberar a estrutura MapiMessage chamando a função MAPIFreeBuffer e excluindo todos os arquivos associados aos anexos incluídos na mensagem.

Antes de chamar MAPIReadMail, use a função MAPIFindNext para verificar se a mensagem a ser lida é a que você deseja ler. Como os identificadores de mensagem são específicos do sistema e opacos e podem ser invalidados a qualquer momento, MAPIReadMail considera um identificador de mensagem válido apenas para a sessão mapi simples atual.