Fonction de rappel MAPIREADMAIL (mapi.h)

Article
08/24/2023

[L’utilisation de cette fonction est déconseillée. Il peut être modifié ou indisponible dans les versions ultérieures de Windows.]

La fonction MAPIReadMail récupère un message à lire.

Syntaxe

MAPIREADMAIL Mapireadmail;

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

Paramètres

[in] lhSession

Gérer vers une session MAPI simple. La valeur du paramètre lhSession doit représenter une session valide ; il ne peut pas être égal à zéro.

[in] ulUIParam

Handle de fenêtre parente ou zéro, indiquant que si une boîte de dialogue est affichée, elle est modale de l’application. Si le paramètre ulUIParam contient un handle de fenêtre parent, il est de type HWND (cast en ULONG_PTR). Si aucune boîte de dialogue n’est affichée pendant l’appel, ulUIParam est ignoré.

[in] lpszMessageID

Pointeur vers une chaîne d’identificateur de message pour le message à lire. La chaîne est allouée par l’appelant.

[in] flFlags

Masque de bits des indicateurs d’option. Les indicateurs suivants peuvent être définis.

Valeur	Signification
MAPI_BODY_AS_FILE	MAPIReadMail doit écrire le texte du message dans un fichier temporaire et l’ajouter en tant que première pièce jointe dans la liste des pièces jointes.
MAPI_ENVELOPE_ONLY	MAPIReadMail doit lire uniquement l’en-tête de message. Les pièces jointes ne sont pas copiées dans des fichiers temporaires, et ni les noms de fichiers temporaires ni le texte du message n’est écrit. La définition de cet indicateur améliore les performances.
MAPI_PEEK	MAPIReadMail ne marque pas le message comme lu. Le marquage d’un message comme lu affecte son apparence dans l’interface utilisateur et génère un accusé de réception de lecture. Si le système de messagerie ne prend pas en charge cet indicateur, MAPIReadMail marque toujours le message comme lu. Si MAPIReadMail rencontre une erreur, le message n’est pas lu.
MAPI_SUPPRESS_ATTACH	MAPIReadMail ne doit pas copier les pièces jointes de fichiers, mais doit écrire le texte du message dans la structure MapiMessage . MAPIReadMail ignore cet indicateur si l’application appelante a défini l’indicateur MAPI_ENVELOPE_ONLY. La définition de l’indicateur MAPI_SUPPRESS_ATTACH améliore les performances.

ulReserved

Réservés au; doit être égal à zéro.

lppMessage

Valeur retournée

Cette fonction retourne l’une des valeurs suivantes.

Code de retour	Description
MAPI_E_ATTACHMENT_WRITE_FAILURE	Impossible d’écrire une pièce jointe dans un fichier temporaire. Vérifiez les autorisations d’annuaire.
MAPI_E_DISK_FULL	Une pièce jointe n’a pas pu être écrite dans un fichier temporaire, car il n’y avait pas suffisamment d’espace sur le disque.
MAPI_E_FAILURE	Une ou plusieurs erreurs non spécifiées se sont produites lors de la lecture du message.
MAPI_E_INSUFFICIENT_MEMORY	La mémoire était insuffisante pour lire le message.
MAPI_E_INVALID_MESSAGE	Un identificateur de message non valide a été passé dans le paramètre lpszMessageID .
MAPI_E_INVALID_SESSION	Un handle de session non valide a été passé dans le paramètre lhSession . Aucun message n’a été récupéré.
MAPI_E_TOO_MANY_FILES	Le message contient trop de pièces jointes. Impossible de lire le message.
MAPI_E_TOO_MANY_RECIPIENTS	Il y avait trop de destinataires du message. Impossible de lire le message.
SUCCESS_SUCCESS	L’appel a réussi et le message a été lu.

Notes

La fonction MAPIReadMail retourne un message, en cassant le contenu du message dans les mêmes paramètres et structures que ceux utilisés dans la fonction MAPISendMail . MAPIReadMail remplit un bloc de mémoire avec la structure MapiMessage contenant des éléments de message, tels que l’objet, la classe de message, l’heure de remise et l’expéditeur. Les pièces jointes sont enregistrées dans des fichiers temporaires et les noms sont retournés à l’appelant dans la structure de message. Les destinataires, les pièces jointes et le contenu sont copiés à partir du message avant que MAPIReadMail ne retourne à l’appelant, de sorte que les modifications apportées ultérieurement aux fichiers n’affectent pas le contenu du message.

Un indicateur est fourni pour spécifier que seules les informations d’enveloppe doivent être retournées à partir de l’appel. Un autre indicateur (dans la structure MapiMessage ) spécifie si le message est marqué comme envoyé ou non envoyé.

L’appelant est chargé de libérer la structure MapiMessage en appelant la fonction MAPIFreeBuffer et en supprimant tous les fichiers associés aux pièces jointes incluses dans le message.

Avant d’appeler MAPIReadMail, utilisez la fonction MAPIFindNext pour vérifier que le message à lire est celui que vous souhaitez lire. Étant donné que les identificateurs de message sont spécifiques au système et opaques et peuvent être invalidés à tout moment, MAPIReadMail considère qu’un identificateur de message est valide uniquement pour la session MAPI simple en cours.