Méthode IStorage ::Commit (objidl.h)

  • Article

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 non root 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 sur le disque pour un stockage racine en mode direct et retourne un code d’erreur en cas d’échec. Bien que Release vide également les mémoires tampons sur le disque, elle n’a pas la capacité de retourner des codes d’erreur en cas d’échec. Par conséquent, l’appel de Release sans appel préalable à Commit 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 sur l’objet de stockage. Pour obtenir une définition de ces valeurs, consultez l’énumération STGC .

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 être consolidé davantage.
STG_S_MULTIPLEOPENS L’opération de validation a réussi, mais le stockage n’a pas pu être consolidé, car il avait é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 peut avoir été ouvert à l’aide de l’indicateur STGM_NOSCRATCH, ou le stockage peut ne pas être le niveau le plus traité à l’extérieur.
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 la totalité des données à commiter ne sont actuellement pas disponibles.
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 des modifications validées. Par conséquent, l’opération de validation actuelle peut remplacer les modifications précédentes.
STG_E_MEDIUMFULL Il ne reste plus d’espace sur l’appareil à valider.
STG_E_TOOMANYOPENFILES L’opération de validation n’a pas pu être effectuée, car il y a trop de fichiers ouverts.
STG_E_REVERTED L’objet de stockage a été invalidé par une opération de restauration au-dessus de lui dans l’arborescence des transactions.

Remarques

IStorage ::Commit apporte des modifications permanentes à un objet de stockage qui est en mode traité, dans lequel les modifications sont accumulées dans une mémoire tampon et ne sont pas 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 à l’objet de stockage. L’appel de la méthode IStorage ::Commit sur un stockage non racine 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 le périphérique de stockage sous-jacent.

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

L’appel de 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 prendre des mesures 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 case activée 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 approuvé 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 responsable de les réécrire avant d’appeler commit. Le mode d’écriture est nécessaire à 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 de IStorage ::Commit avec STGC_CONSOLIDATE spécifié dans le paramètre grfCommitFlags renvoie la valeur STG_E_INVALIDFLAG.

Configuration requise

Condition requise Valeur
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 fichiers composés

IStorage ::Revert

STGC