Метод IStorage::Commit (objidl.h)

Статья
08/25/2023

Метод Commit гарантирует, что все изменения, внесенные в объект хранилища, открытый в режиме транзакций, отражаются в родительском хранилище. Для объектов некорневых хранилищ в режиме прямого подключения этот метод не оказывает никакого влияния. Для корневого хранилища оно отражает изменения в фактическом устройстве; например, файл на диске. Для корневого объекта хранилища, открытого в прямом режиме, всегда вызывайте метод IStorage::Commit до выпуска. IStorage::Commit сбрасывает все буферы памяти на диск для корневого хранилища в прямом режиме и возвращает код ошибки в случае сбоя. Хотя выпуск также сбрасывает буферы памяти на диск, он не может возвращать коды ошибок в случае сбоя. Таким образом, вызов Release без предварительного вызова commit приводит к неопределенным результатам.

Синтаксис

HRESULT Commit(
  [in] DWORD grfCommitFlags
);

Параметры

[in] grfCommitFlags

Управляет фиксацией изменений в объекте хранилища. Определение этих значений см. в перечислении STGC .

Возвращаемое значение

Этот метод может возвращать одно из этих значений.

Код возврата	Описание
S_OK	Изменения объекта хранилища успешно зафиксированы на родительском уровне. Если STGC_CONSOLIDATE указано, хранилище было успешно консолидировано или оно уже было слишком компактным для дальнейшей консолидации.
STG_S_MULTIPLEOPENS	Операция фиксации выполнена успешно, но не удалось объединить хранилище, так как оно было открыто несколько раз с помощью флага STGM_NOSNAPSHOT.
STG_S_CANNOTCONSOLIDATE	Операция фиксации выполнена успешно, но не удалось объединить хранилище из-за неправильного режима хранения. Для составных файлов хранилище может быть открыто с помощью флага STGM_NOSCRATCH или хранилище может быть не самым внешним уровнем транзакций.
STG_S_CONSOLIDATIONFAILED	Операция фиксации завершилась успешно, но не удалось объединить хранилище из-за внутренней ошибки (например, сбоя выделения памяти).
E_PENDING	Только асинхронное хранилище. Часть или все данные, которые необходимо зафиксировать, в настоящее время недоступны.
STG_E_INVALIDFLAG	Недопустимое значение параметра grfCommitFlags .
STG_E_INVALIDPARAMETER	Один из параметров был недопустимым.
STG_E_NOTCURRENT	Еще один открытый экземпляр объекта хранилища зафиксировал изменения. В результате текущая операция фиксации может перезаписать предыдущие изменения.
STG_E_MEDIUMFULL	На устройстве не осталось места для фиксации.
STG_E_TOOMANYOPENFILES	Не удалось выполнить операцию фиксации, так как открыто слишком много файлов.
STG_E_REVERTED	Объект хранилища был признан недействительным в результате операции отменить изменения над ним в дереве транзакций.

IStorage::Commit вносит постоянные изменения в объект хранилища, который находится в режиме транзакций, в котором изменения накапливаются в буфере и не отражаются в объекте хранилища до тех пор, пока не будет вызов этого метода. Альтернативой является открытие объекта в режиме прямого подключения, в котором изменения немедленно отражаются в объекте хранилища. Объект, открытый в режиме прямого подключения, не требует вызова IStorage::Commit для внесения постоянных изменений в объект хранилища. Вызов метода IStorage::Commit для нескоротового хранилища, открытого в режиме прямого подключения, не оказывает никакого влияния. Открытие корневого объекта хранилища в режиме прямого доступа гарантирует запись изменений в буферах памяти на базовое устройство хранения.

Операция фиксации публикует текущие изменения в этом объекте хранилища и его дочерних элементах на следующем уровне выше в иерархии хранилища. Чтобы отменить текущие изменения перед их фиксацией, вызовите IStorage::Revert для отката до последней зафиксированной версии.

Вызов IStorage::Commit не влияет на открытые в настоящее время вложенные элементы этого объекта хранилища. Они остаются действительными и могут использоваться. Однако метод IStorage::Commit не фиксирует изменения во вложенных элементах автоматически. Операция фиксации публикует только известные изменения на следующем более высоком уровне в иерархии хранилища. Таким образом, транзакции на вложенных уровнях должны быть зафиксированы в этом объекте хранилища, прежде чем их можно будет зафиксировать на более высоких уровнях.

В операциях фиксации необходимо выполнить действия, чтобы обеспечить защиту данных в процессе фиксации:

При фиксации изменений в объектах корневого хранилища вызывающий объект должен проверка возвращаемое значение, чтобы определить, успешно ли выполнена операция, и если нет, старое зафиксированное содержимое IStorage по-прежнему нетронуто и может быть восстановлено.
Если этот объект хранилища был открыт с исключенными элементами, вызывающий объект отвечает за их перезапись перед вызовом фиксации. Для успешной фиксации требуется режим записи в открывшемся хранилище.
Если не запрещено одновременное использование нескольких модулей записи в одном объекте хранилища, приложение, вызывающее этот метод, должно указать по крайней мере STGC_ONLYIFCURRENT в параметре grfCommitFlags , чтобы изменения, внесенные одним модулем записи, не случайно перезаписали изменения, внесенные другим.

Если флаг STGC_CONSOLIDATE не поддерживается реализацией хранилища, вызов IStorage::Commit с STGC_CONSOLIDATE, указанным в параметре grfCommitFlags , возвращает значение STG_E_INVALIDFLAG.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	objidl.h
Библиотека	Uuid.lib
DLL	Ole32.dll

См. также раздел

IStorage — реализация составного файла

IStorage::Revert

STGC