IXPLogon::SubmitMessage
S’applique à : Outlook 2013 | Outlook 2016
Indique que le spouleur MAPI a un message que le fournisseur de transport doit remettre.
HRESULT SubmitMessage(
ULONG ulFlags,
LPMESSAGE lpMessage,
ULONG FAR * lpulMsgRef,
ULONG FAR * lpulReturnParm
);
Paramètres
ulFlags
[in] Masque de bits d’indicateurs qui contrôle la façon dont le message est envoyé. L’indicateur suivant peut être défini :
BEGIN_DEFERRED
Le spouleur MAPI appelle un fournisseur de transport avec un message précédemment différé. L’identificateur d’entrée du message est le même que lorsqu’il a été différé. Le message a été différé en transmettant son identificateur d’entrée au spouleur MAPI à l’aide de la méthode IMAPISupport ::SpoolerNotify avec l’indicateur NOTIFY_SENTDEFERRED.
lpMessage
[in] Pointeur vers un objet message (représentant le message à remettre) qui dispose d’une autorisation de lecture/écriture, que le fournisseur de transport utilise pour accéder à ce message et le manipuler. Cet objet reste valide jusqu’à ce que le fournisseur de transport retourne un appel ultérieur à la méthode IXPLogon ::EndMessage .
lpulMsgRef
[out] Pointeur vers une variable dans laquelle le fournisseur de transport retourne la valeur de référence qu’il a affectée à ce message. Le spouleur MAPI transmet cette valeur de référence dans les appels suivants pour ce message. Le spouleur MAPI initialise la valeur sur 0 avant de la renvoyer au fournisseur de transport.
lpulReturnParm
[out] Pointeur vers une variable qui correspond à la valeur d’erreur MAPI_E_WAIT ou MAPI_E_NETWORK_ERROR retournée par SubmitMessage.
Valeur renvoyée
S_OK
L’appel a réussi et a retourné la ou les valeurs attendues.
MAPI_E_BUSY
Le fournisseur de transport ne peut pas gérer le message, car il effectue une autre opération. Un fournisseur doit utiliser cette valeur de retour pour indiquer qu’aucun traitement n’a eu lieu et que le spouleur MAPI ne doit pas appeler EndMessage. Le spouleur MAPI réessayera l’appel SubmitMessage ultérieurement.
MAPI_E_CANCEL
Bien que le fournisseur de transport ait demandé que le spouleur MAPI renvoie le message sur un appel SpoolerNotify précédent, les conditions ont depuis changé et le message ne doit pas être renvoyé. Le spouleur MAPI va continuer à gérer autre chose.
MAPI_E_NETWORK_ERROR
Une erreur réseau a empêché la réussite de l’opération. Le paramètre lpulReturnParm doit être défini sur le nombre de secondes qui s’écouleront avant que le spouleur MAPI resoumise le message.
MAPI_E_NOT_ME
Le fournisseur de transport ne peut pas gérer ce message. Le spouleur MAPI doit essayer de trouver un autre fournisseur de transport pour celui-ci. Un fournisseur doit utiliser cette valeur de retour pour indiquer qu’aucun traitement n’a eu lieu et que le spouleur MAPI ne doit pas appeler EndMessage.
MAPI_E_WAIT
Un problème temporaire empêche le fournisseur de transport de gérer le message. Le paramètre lpulReturnParm doit être défini sur le nombre de secondes qui s’écouleront avant que le spouleur MAPI resoumise le message.
Remarques
Le spouleur MAPI appelle la méthode IXPLogon ::SubmitMessage lorsqu’il a un message que le fournisseur de transport doit remettre. Le message est transmis au fournisseur de transport à l’aide du paramètre lpMessage .
Si le fournisseur est prêt à accepter le message, il doit retourner une valeur de référence à l’aide du paramètre lpulMsgRef , traiter l’objet passé et retourner la valeur appropriée (généralement S_OK). Si le fournisseur n’est pas prêt à gérer le transfert, il doit retourner une valeur d’erreur et, éventuellement, une autre valeur de retour MAPI dans lpulReturnParm pour indiquer combien de temps le spouleur MAPI doit attendre avant de soumettre à nouveau le message.
L’implémentation de cette méthode par un fournisseur de transport peut effectuer les opérations suivantes :
Placez le message dans une file d’attente interne pour attendre sa transmission, éventuellement en copiant le message dans un stockage local, puis retournez-le.
Essayez d’effectuer la transmission réelle et de retourner une fois la transmission terminée, avec succès ou échec.
Déterminez s’il faut envoyer le message après avoir vérifié la ressource concernée. Dans ce cas, si la ressource est gratuite, le fournisseur peut verrouiller la ressource, préparer le message et l’envoyer. Si la ressource est occupée, le fournisseur peut préparer le message et différer l’envoi à une date ultérieure.
La technique préférée pour la transmission de messages dépend du fournisseur de transport et du nombre attendu de processus en concurrence pour les ressources du système.
Pendant un appel SubmitMessage , le fournisseur de transport contrôle le transfert des données de message à partir de l’objet message. Toutefois, le fournisseur de transport doit affecter une valeur de référence au message, auquel il retourne un pointeur dans lpulMsgRef, avant de transférer des données. Elle le fait, car à tout moment du processus, le spouleur MAPI peut appeler la méthode IXPLogon ::TransportNotify avec l’indicateur NOTIFY_CANCEL_MESSAGE défini pour signaler au fournisseur qu’il doit libérer tous les objets ouverts et arrêter le transfert des messages.
Le fournisseur de transport ne doit pas envoyer de propriétés non transmitables du message. Lorsqu’il trouve une telle propriété, il doit continuer à traiter la propriété suivante. Le fournisseur doit s’efforcer de ne pas afficher les informations de MAPI_P1 destinataire dans le cadre du contenu du message transmis ; le fournisseur doit utiliser ces informations de destinataire uniquement à des fins d’adressage. MAPI_P1 destinataires sont des destinataires générés en interne qui sont utilisés pour renvoyer des messages ; ils ne doivent pas être transmis. Utilisez plutôt les autres destinataires pour transmettre les informations sur les destinataires. L’objectif de cette disposition est de permettre aux destinataires de renvoyer la même table de destinataires que les destinataires d’origine.
Pendant un appel SubmitMessage , le spouleur MAPI traite les méthodes pour les objets qui sont ouverts pendant le transfert du message, et traite toutes les pièces jointes. Ce traitement peut prendre beaucoup de temps. Les fournisseurs de transport peuvent appeler la méthode IMAPISupport ::SpoolerYield pour le spouleur MAPI fréquemment pendant ce traitement afin de libérer du temps processeur pour d’autres tâches système.
Tous les destinataires du message sont visibles dans la table des destinataires du message que le spouleur MAPI a transmis à l’origine. Le fournisseur de transport doit traiter uniquement les destinataires qu’il peut gérer (en fonction de l’identificateur d’entrée, du type d’adresse ou des deux) et dont la propriété PR_RESPONSIBILITY (PidTagResponsibility) n’a pas encore la valeur TRUE. Si PR_RESPONSIBILITY est déjà défini sur TRUE, un autre fournisseur de transport a géré ce destinataire. Lorsque le fournisseur termine le traitement suffisant d’un destinataire pour déterminer s’il peut gérer les messages pour ce destinataire, il doit définir la propriété PR_RESPONSIBILITY de ce destinataire sur TRUE dans le message passé. En règle générale, le fournisseur effectue cette détermination une fois la remise du message terminée.
En règle générale, le fournisseur de transport ne retourne pas à partir d’un appel SubmitMessage tant qu’il n’a pas terminé le transfert des données de message. Si aucune erreur n’est retournée, l’appel suivant du spouleur MAPI au fournisseur est un appel à la méthode IXPLogon ::EndMessage .
Si SubmitMessage retourne une erreur, le spouleur MAPI libère le message en cours sans enregistrer les modifications. Si le fournisseur de transport exige que les modifications de message soient enregistrées, il doit appeler la méthode IMAPIProp ::SaveChanges sur le message avant de retourner.
En cas d’erreurs qui se produisent en raison de problèmes de transport, le spouleur MAPI conserve le message, mais il retarde la soumission du message au fournisseur de transport en fonction de la valeur retournée dans lpulReturnParm. Le fournisseur de transport doit renseigner cette valeur si sa valeur de retour de SubmitMessage est MAPI_E_WAIT ou MAPI_E_NETWORK_ERROR. Si une erreur grave se produit, le fournisseur de transport doit appeler la méthode IMAPISupport ::SpoolerNotify avec l’indicateur NOTIFY_CRITICAL_ERROR.