IMAPIProp::SaveChanges

S’applique à : Outlook 2013 | Outlook 2016

Rend permanentes toutes les modifications apportées à un objet depuis la dernière opération d’enregistrement.

HRESULT SaveChanges(
  ULONG ulFlags
);

Paramètres

ulFlags

[in] Masque de bits d’indicateurs qui contrôle ce qui arrive à l’objet lorsque la méthode IMAPIProp ::SaveChanges est appelée. Les indicateurs suivants peuvent être définis :

NON_EMS_XP_SAVE

Indique que le message n’a pas été remis à partir d’un Microsoft Exchange Server. Cet indicateur doit être utilisé en combinaison avec la méthode IMAPIFolder ::CreateMessage et l’indicateur ITEMPROC_FORCE pour indiquer à un magasin PST que le message est éligible pour le traitement des règles avant que le magasin de fichiers dossiers personnels (PST) n’informe tout client à l’écoute que le message est arrivé. Ce traitement des règles s’applique uniquement aux nouveaux messages créés avec IMAPIFolder ::CreateMessage sur un serveur qui n’est pas un Exchange Server, auquel cas le Exchange Server aurait déjà traité des règles sur le message.

FORCE_SAVE

Les modifications doivent être écrites dans l’objet, en remplaçant toutes les modifications précédentes apportées à l’objet, et l’objet doit être fermé. L’autorisation de lecture/écriture doit être définie pour que l’opération réussisse. L’indicateur FORCE_SAVE est utilisé après un appel précédent à SaveChanges retourné MAPI_E_OBJECT_CHANGED.

KEEP_OPEN_READONLY

Les modifications doivent être validées et l’objet doit rester ouvert pour lecture. Aucune modification supplémentaire n’est apportée.

KEEP_OPEN_READWRITE

Les modifications doivent être validées et l’objet doit rester ouvert pour l’autorisation de lecture/écriture. Cet indicateur est généralement défini lorsque l’objet a été ouvert pour la première fois pour l’autorisation de lecture/écriture. Les modifications ultérieures apportées à l’objet sont autorisées.

MAPI_DEFERRED_ERRORS

Permet à SaveChanges de revenir correctement, éventuellement avant que les modifications n’aient été entièrement validées.

SPAMFILTER_ONSAVE

Active le filtrage du courrier indésirable sur un message en cours d’enregistrement. La prise en charge du filtrage du courrier indésirable n’est disponible que si le type d’adresse e-mail de l’expéditeur suit le protocole SMTP et que le message est enregistré dans une banque pour un fichier de dossiers personnels (PST).

Valeur renvoyée

S_OK

L’engagement des modifications a réussi.

MAPI_E_NO_ACCESS

SaveChanges ne peut pas conserver l’objet ouvert pour l’autorisation en lecture seule si KEEP_OPEN_READONLY est défini, ni l’autorisation de lecture/écriture si KEEP_OPEN_READWRITE est défini. Aucune modification n’est validée.

MAPI_E_OBJECT_CHANGED

L’objet a changé depuis son ouverture.

MAPI_E_OBJECT_DELETED

L’objet a été supprimé depuis son ouverture.

Remarques

La méthode IMAPIProp ::SaveChanges rend les modifications de propriété permanentes pour les objets qui prennent en charge le modèle de transaction de traitement, tels que les messages, les pièces jointes, les conteneurs de carnets d’adresses et les objets utilisateur de messagerie. Les objets qui ne prennent pas en charge les transactions, telles que les dossiers, les magasins de messages et les sections de profil, rendent les modifications permanentes immédiatement. Aucun appel à SaveChanges n’est nécessaire.

Étant donné que les fournisseurs de services n’ont pas besoin de générer un identificateur d’entrée pour leurs objets tant que toutes les propriétés n’ont pas été enregistrées, la propriété PR_ENTRYID (PidTagEntryId) d’un objet peut ne pas être disponible tant que sa méthode SaveChanges n’a pas été appelée. Certains fournisseurs attendent que l’indicateur KEEP_OPEN_READONLY soit défini sur l’appel SaveChanges . KEEP_OPEN_READONLY indique que les modifications à enregistrer dans l’appel actuel seront les dernières modifications apportées à l’objet.

Certaines implémentations de magasin de messages n’affichent pas les messages nouvellement créés dans un dossier tant qu’un client n’enregistre pas les modifications de message à l’aide de SaveChanges et libère les objets message à l’aide de la méthode IUnknown ::Release . En outre, certaines implémentations d’objets ne peuvent pas générer une propriété PR_ENTRYID pour un objet nouvellement créé tant que SaveChanges n’a pas été appelé, et d’autres ne peuvent le faire qu’après l’appel de SaveChanges à l’aide de KEEP_OPEN_READONLY défini dans ulFlags.

Remarques pour les responsables de l’implémentation

Si vous recevez l’indicateur KEEP_OPEN_READONLY, vous avez la possibilité de laisser l’accès de l’objet en lecture/écriture. Toutefois, un fournisseur ne peut jamais laisser un objet en lecture seule lorsque l’indicateur KEEP_OPEN_READWRITE est passé.

Lorsqu’un client enregistre plusieurs pièces jointes dans plusieurs messages, il appelle la méthode SaveChanges pour chaque pièce jointe et chaque message. Souvent, les clients définissent MAPI_DEFERRED_ERRORS pour chacun de ces appels, à l’exception du dernier. Vous pouvez retourner des erreurs avec le dernier appel ou des appels antérieurs. Vous pouvez même ignorer l’indicateur.

Si KEEP_OPEN_READWRITE ou KEEP_OPEN_READONLY est défini avec MAPI_DEFERRED_ERRORS, vous pouvez ignorer la demande de report d’erreur. Si MAPI_DEFERRED_ERRORS n’est pas défini dans ulFlags, l’une des erreurs précédemment différées peut être retournée pour l’appel SaveChanges .

Le fait qu’un fournisseur de transport distant fournisse une implémentation fonctionnelle de cette méthode est facultatif et dépend d’autres choix de conception dans votre implémentation. Si vous implémentez cette méthode, procédez comme indiqué dans la documentation ici. Étant donné que les objets de dossier et les objets status ne sont pas traités, l’implémentation de SaveChanges d’un fournisseur de transport distant doit au minimum retourner S_OK sans effectuer réellement de travail.

Remarques pour les appelants

Si un client passe KEEP_OPEN_READONLY, appelle la méthode IMAPIProp ::SetProps , puis appelle à nouveau SaveChanges , la même implémentation peut échouer.

Après avoir reçu MAPI_E_NO_ACCESS d’un appel dans lequel vous avez défini KEEP_OPEN_READWRITE, vous continuez à disposer de l’autorisation de lecture/écriture sur l’objet. Vous pouvez appeler à nouveau SaveChanges en passant l’indicateur KEEP_OPEN_READONLY ou aucun indicateur avec KEEP_OPEN_SUFFIX.

Le fait qu’un fournisseur prenne en charge l’indicateur KEEP_OPEN_READWRITE dépend de l’implémentation du fournisseur.

Pour indiquer que le seul appel à effectuer sur l’objet après SaveChanges est IUnknown ::Release, ne définissez aucun indicateur pour le paramètre ulFlags . Une erreur de SaveChanges indique qu’il n’a pas pu rendre les modifications en attente permanentes. Différents fournisseurs gèrent l’absence d’indicateurs sur l’appel SaveChanges différemment. Certains fournisseurs traitent cet état de la même façon que KEEP_OPEN_READONLY ; les autres fournisseurs l’interprètent comme KEEP_OPEN_READWRITE. D’autres fournisseurs arrêtent l’objet lorsqu’ils ne reçoivent pas d’indicateurs sur l’appel SaveChanges .

Certaines propriétés, généralement calculées, ne peuvent pas être traitées tant que vous n’avez pas appelé SaveChanges et, dans certains cas, Release.

Lorsque vous apportez des modifications en bloc, telles que l’enregistrement de pièces jointes dans plusieurs messages, reportez le traitement des erreurs en définissant l’indicateur MAPI_DEFERRED_ERRORS dans ulFlags. Si vous enregistrez plusieurs pièces jointes dans plusieurs messages, effectuez un appel SaveChanges à chaque pièce jointe et un appel SaveChanges à chaque message. Définissez l’indicateur MAPI_DEFERRED_ERRORS pour chaque appel de pièce jointe et pour tous les messages, à l’exception du dernier.

Si SaveChanges renvoie MAPI_E_OBJECT_CHANGED, case activée si l’objet d’origine a été modifié. Si c’est le cas, avertissez l’utilisateur, qui peut soit demander que les modifications remplacent les modifications précédentes, soit enregistrer l’objet ailleurs. Si l’objet d’origine a été supprimé, avertissez l’utilisateur de lui donner la possibilité d’enregistrer l’objet dans un autre emplacement.

Vous ne pouvez pas appeler SaveChanges avec l’indicateur FORCE_SAVE sur un objet ouvert qui a été supprimé.

Si SaveChanges renvoie une erreur, l’objet dont les modifications ont été enregistrées reste ouvert, quels que soient les indicateurs définis dans le paramètre ulFlags .

Importante

Les NON_EMS_XP_SAVE ulFlags et SPAMFILTER_ONSAVE peuvent ne pas être définis dans le fichier d’en-tête téléchargeable que vous avez actuellement, auquel cas vous pouvez l’ajouter à votre code à l’aide des valeurs suivantes : #define SPAMFILTER_ONSAVE ((ULONG) 0x00000080)>#define NON_EMS_XP_SAVE ((ULONG) 0x00001000)

Pour plus d’informations, consultez Enregistrement des propriétés MAPI.

Voir aussi

IMAPIProp::SetProps
Propriété canonique PidTagEntryId
IMAPIProp : IUnknownSaving MAPI Properties