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

  • Artículo

El método Commit garantiza que los cambios realizados en un objeto de almacenamiento abierto en modo transaccionado se reflejan en el almacenamiento primario. En el caso de los objetos de almacenamiento que no son raíz en modo directo, este método no tiene ningún efecto. Para un almacenamiento raíz, refleja los cambios en el dispositivo real; por ejemplo, un archivo en el disco. Para un objeto de almacenamiento raíz abierto en modo directo, llame siempre al método IStorage::Commit antes de Release. IStorage::Commit vacía todos los búferes de memoria en el disco para un almacenamiento raíz en modo directo y devolverá un código de error tras un error. Aunque Release también vacía los búferes de memoria en el disco, no tiene capacidad para devolver ningún código de error tras un error. Por lo tanto, llamar a Release sin llamar primero a Commit provoca resultados indeterminados.

Sintaxis

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

Parámetros

[in] grfCommitFlags

Controla cómo se confirman los cambios en el objeto de almacenamiento. Consulte la enumeración STGC para obtener una definición de estos valores.

Valor devuelto

Este método puede devolver uno de estos valores.

Código devuelto Descripción
S_OK Los cambios realizados en el objeto de almacenamiento se han confirmado correctamente en el nivel primario. Si se especificó STGC_CONSOLIDATE, el almacenamiento se consolidó correctamente o el almacenamiento ya era demasiado compacto para consolidarse aún más.
STG_S_MULTIPLEOPENS La operación de confirmación se realizó correctamente, pero el almacenamiento no se pudo consolidar porque se había abierto varias veces con la marca STGM_NOSNAPSHOT.
STG_S_CANNOTCONSOLIDATE La operación de confirmación se realizó correctamente, pero el almacenamiento no se pudo consolidar debido a un modo de almacenamiento incorrecto. En el caso de los archivos compuestos, es posible que el almacenamiento se haya abierto con la marca STGM_NOSCRATCH o que el almacenamiento no sea el nivel de transacción más externo.
STG_S_CONSOLIDATIONFAILED La operación de confirmación se realizó correctamente, pero el almacenamiento no se pudo consolidar debido a un error interno (por ejemplo, un error de asignación de memoria).
E_PENDING Solo almacenamiento asincrónico: la parte o todos los datos que se van a confirmar no están disponibles actualmente.
STG_E_INVALIDFLAG El valor del parámetro grfCommitFlags no es válido.
STG_E_INVALIDPARAMETER Uno de los parámetros no era válido.
STG_E_NOTCURRENT Otra instancia abierta del objeto de almacenamiento ha confirmado cambios. Como resultado, la operación de confirmación actual puede sobrescribir los cambios anteriores.
STG_E_MEDIUMFULL No queda espacio en el dispositivo para confirmarlo.
STG_E_TOOMANYOPENFILES No se pudo completar la operación de confirmación porque hay demasiados archivos abiertos.
STG_E_REVERTED El objeto de almacenamiento se ha invalidado mediante una operación de reversión encima de él en el árbol de transacciones.

Comentarios

IStorage::Commit realiza cambios permanentes en un objeto de almacenamiento que está en modo de transacción, en el que los cambios se acumulan en un búfer y no se reflejan en el objeto de almacenamiento hasta que haya una llamada a este método. La alternativa es abrir un objeto en modo directo, en el que los cambios se reflejan inmediatamente en el objeto de almacenamiento. Un objeto abierto en el modo directo no requiere llamar a IStorage::Commit para realizar cambios permanentes en el objeto de almacenamiento. Llamar al método IStorage::Commit en un almacenamiento noroot abierto en modo directo no tiene ningún efecto. Abrir un objeto de almacenamiento raíz en modo directo garantiza que los cambios en los búferes de memoria se escriben en el dispositivo de almacenamiento subyacente.

La operación de confirmación publica los cambios actuales en este objeto de almacenamiento y sus elementos secundarios en el siguiente nivel superior en la jerarquía de almacenamiento. Para deshacer los cambios actuales antes de confirmarlos, llame a IStorage::Revert para revertir a la última versión confirmada.

Llamar a IStorage::Commit no tiene ningún efecto en los elementos anidados abiertos actualmente de este objeto de almacenamiento. Siguen siendo válidos y se pueden usar. Sin embargo, el método IStorage::Commit no confirma automáticamente los cambios en estos elementos anidados. La operación de confirmación solo publica los cambios conocidos en el siguiente nivel superior de la jerarquía de almacenamiento. Por lo tanto, las transacciones a niveles anidados deben confirmarse en este objeto de almacenamiento para poder confirmarse en niveles superiores.

En las operaciones de confirmación, debe realizar pasos para asegurarse de que los datos están protegidos durante el proceso de confirmación:

  • Al confirmar cambios en los objetos de almacenamiento raíz, el autor de la llamada debe comprobar el valor devuelto para determinar si la operación se ha completado correctamente y, si no es así, que el contenido confirmado anterior de IStorage sigue intacto y se puede restaurar.
  • Si este objeto de almacenamiento se abrió con algunos de sus elementos excluidos, el autor de la llamada es responsable de reescribirlos antes de llamar a commit. El modo de escritura es necesario en la apertura del almacenamiento para que la confirmación se realice correctamente.
  • A menos que se prohíben varios escritores simultáneos en el mismo objeto de almacenamiento, una aplicación que llama a este método debe especificar al menos STGC_ONLYIFCURRENT en el parámetro grfCommitFlags para evitar que un escritor sobrescriba accidentalmente los cambios realizados por otro.
Si la marca de STGC_CONSOLIDATE no es compatible con una implementación de almacenamiento, llamar a IStorage::Commit con STGC_CONSOLIDATE especificado en el parámetro grfCommitFlags devuelve el valor STG_E_INVALIDFLAG.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado objidl.h
Library Uuid.lib
Archivo DLL Ole32.dll

Consulte también

IStorage: implementación de archivos compuestos

IStorage::Revert

STGC