IStorage::Commit, méthode (objidl.h)

La méthode Commit garantit que toutes les modifications apportées à un objet de stockage ouvert en mode transactionné sont reflétées dans le stockage parent. Pour les objets de stockage nonroot en mode direct, cette méthode n’a aucun effet. Pour un stockage racine, il reflète les modifications apportées à l’appareil réel ; par exemple, un fichier sur disque. Pour un objet de stockage racine ouvert en mode direct, appelez toujours la méthode IStorage::Commit avant Release. IStorage::Commit vide toutes les mémoires tampons de mémoire sur le disque pour un stockage racine en mode direct et retourne un code d’erreur en cas d’échec. Bien que la mise en production vide également les mémoires tampons sur le disque, elle n’a aucune capacité de retourner les codes d’erreur en cas d’échec. Par conséquent, l’appel de la mise en production sans l’appel de la validation entraîne des résultats indéterminés.

Syntaxe

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

Paramètres

[in] grfCommitFlags

Contrôle la façon dont les modifications sont validées dans l’objet de stockage. Consultez l’énumération STGC pour obtenir une définition de ces valeurs.

Valeur retournée

Cette méthode peut retourner l’une de ces valeurs.

Code de retour Description
S_OK Les modifications apportées à l’objet de stockage ont été validées avec succès au niveau parent. Si STGC_CONSOLIDATE a été spécifié, le stockage a été correctement consolidé ou le stockage était déjà trop compact pour consolider davantage.
STG_S_MULTIPLEOPENS L’opération de validation a réussi, mais le stockage n’a pas pu être consolidé, car il a été ouvert plusieurs fois à l’aide de l’indicateur STGM_NOSNAPSHOT.
STG_S_CANNOTCONSOLIDATE L’opération de validation a réussi, mais le stockage n’a pas pu être consolidé en raison d’un mode de stockage incorrect. Pour les fichiers composés, le stockage a peut-être été ouvert à l’aide de l’indicateur de STGM_NOSCRATCH, ou le stockage peut ne pas être le niveau transactionné le plus externe.
STG_S_CONSOLIDATIONFAILED L’opération de validation a réussi, mais le stockage n’a pas pu être consolidé en raison d’une erreur interne (par exemple, un échec d’allocation de mémoire).
E_PENDING Stockage asynchrone uniquement : une partie ou l’ensemble des données à validées n’est actuellement pas disponible.
STG_E_INVALIDFLAG La valeur du paramètre grfCommitFlags n’est pas valide.
STG_E_INVALIDPARAMETER L’un des paramètres n’était pas valide.
STG_E_NOTCURRENT Une autre instance ouverte de l’objet de stockage a validé les modifications. Par conséquent, l’opération de validation actuelle peut remplacer les modifications précédentes.
STG_E_MEDIUMFULL Aucun espace laissé sur l’appareil à valider.
STG_E_TOOMANYOPENFILES L’opération de validation n’a pas pu être terminée, car il existe trop de fichiers ouverts.
STG_E_REVERTED L’objet de stockage a été invalidé par une opération de restauration au-dessus de celle-ci dans l’arborescence des transactions.

Remarques

IStorage::Commit apporte des modifications permanentes à un objet de stockage en mode transactionné, dans lequel les modifications sont accumulées dans une mémoire tampon et non reflétées dans l’objet de stockage tant qu’il n’y a pas d’appel à cette méthode. L’alternative consiste à ouvrir un objet en mode direct, dans lequel les modifications sont immédiatement reflétées dans l’objet de stockage. Un objet ouvert en mode direct ne nécessite pas d’appeler IStorage::Commit pour apporter des modifications permanentes dans l’objet de stockage. L’appel de la méthode IStorage::Commit sur un stockage nonroot ouvert en mode direct n’a aucun effet. L’ouverture d’un objet de stockage racine en mode direct garantit que les modifications apportées aux mémoires tampons sont écrites sur l’appareil de stockage sous-jacent.

L’opération de validation publie les modifications actuelles dans cet objet de stockage et ses enfants au niveau suivant dans la hiérarchie de stockage. Pour annuler les modifications actuelles avant de les valider, appelez IStorage::Rétablir la restauration vers la dernière version validée.

L’appel d’IStorage::Commit n’a aucun effet sur les éléments imbriqués actuellement ouverts de cet objet de stockage. Ils restent valides et peuvent être utilisés. Toutefois, la méthode IStorage::Commit ne valide pas automatiquement les modifications apportées à ces éléments imbriqués. L’opération de validation publie uniquement les modifications connues au niveau supérieur suivant dans la hiérarchie de stockage. Par conséquent, les transactions aux niveaux imbriqués doivent être validées sur cet objet de stockage avant de pouvoir être validées à des niveaux plus élevés.

Dans les opérations de validation, vous devez effectuer des étapes pour vous assurer que les données sont protégées pendant le processus de validation :

  • Lors de la validation des modifications apportées aux objets de stockage racine, l’appelant doit vérifier la valeur de retour pour déterminer si l’opération a été effectuée correctement, et si ce n’est pas le cas, que l’ancien contenu validé de l’IStorage est toujours intact et peut être restauré.
  • Si cet objet de stockage a été ouvert avec certains de ses éléments exclus, l’appelant est chargé de les réécrire avant d’appeler la validation. Le mode d’écriture est requis sur l’ouverture du stockage pour que la validation réussisse.
  • À moins d’interdire plusieurs enregistreurs simultanés sur le même objet de stockage, une application appelant cette méthode doit spécifier au moins STGC_ONLYIFCURRENT dans le paramètre grfCommitFlags pour empêcher les modifications apportées par un enregistreur de remplacer par inadvertance les modifications apportées par un autre.
Si l’indicateur STGC_CONSOLIDATE n’est pas pris en charge par une implémentation de stockage, l’appel d’IStorage::Commit avec STGC_CONSOLIDATE spécifié dans le paramètre grfCommitFlags retourne la valeur STG_E_INVALIDFLAG.

Configuration requise

   
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau | Applications UWP]
Plateforme cible Windows
En-tête objidl.h
Bibliothèque Uuid.lib
DLL Ole32.dll

Voir aussi

IStorage - Implémentation de fichier composé

IStorage::Revert

STGC