Реализация файла IStorage-Compound

  • Статья

Реализация составного файла IStorage позволяет создавать вложенные журналы и потоки в объекте хранилища, размещенном в составном объекте файла, и управлять ими. Чтобы создать составной файловый объект и получить указатель IStorage , вызовите функцию API StgCreateStorageEx. Чтобы открыть существующий составной файловый объект и получить его корневой указатель IStorage , вызовите StgOpenStorageEx.

Приложения, использующие составное хранилище, должны быть зарегистрированы в HKEY_CLASSES_ROOT\SystemFileAssociations и предоставлять собственные обработчики свойств. Дополнительные сведения см. в разделе "Регистрация глаголов и других сведений о сопоставлении файлов" статьи Регистрация приложений.

Назначение

Большинство приложений используют эту реализацию для создания хранилищ и потоков и управления ими.

Методы

IStorage::CreateStream

Создает и открывает объект потока с указанным именем, содержащимся в этом объекте хранилища. Длина имени не должна превышать 31 символ (без учета признака конца строки). Символы от 000 до 01f, служащие как первый символ имени потока/хранилища, зарезервированы для использования OLE. Это ограничение составного файла, а ограничение структурированного хранения. Предоставленная COM реализация составного файла метода IStorage::CreateStream не поддерживает следующее поведение:

  • Флаг STGM_DELETEONRELEASE не поддерживается.
  • Режим транзакций (STGM_TRANSACTED) не поддерживается для объектов потока.
  • Открытие одного потока несколько раз из одного хранилища не поддерживается. Флаг режима общего доступа STGM_SHARE_EXCLUSIVE должен быть указан в параметре grfMode .

IStorage::OpenStream

Открывает существующий объект потока в этом объекте хранилища, используя режимы доступа, указанные в параметре grfMode . Символы от 000 до 01f, служащие как первый символ имени потока/хранилища, зарезервированы для использования OLE. Это ограничение составного файла, а ограничение структурированного хранения. Предоставленная COM реализация составного файла метода IStorage::OpenStream не поддерживает следующее поведение:

  • Флаг STGM_DELETEONRELEASE.
  • Режим транзакций (STGM_TRANSACTED) для объектов потока.
  • Открытие одного и того же потока несколько раз из одного хранилища. Необходимо указать флаг STGM_SHARE_EXCLUSIVE.

IStorage::CreateStorage

Создает и открывает новый объект хранилища с указанным именем в указанном режиме доступа. Длина имени не должна превышать 31 символ (без учета признака конца строки). Символы от 000 до 01f, служащие как первый символ имени потока/хранилища, зарезервированы для использования OLE. Это ограничение составного файла, а ограничение структурированного хранения. Предоставленная COM реализация составного файла метода IStorage::CreateStorage не поддерживает следующее поведение:

  • Флаг STGM_PRIORITY для некоревых хранилищ.
  • Открытие одного и того же объекта хранилища несколько раз из одного родительского хранилища. Необходимо указать флаг STGM_SHARE_EXCLUSIVE.
  • Флаг STGM_DELETEONRELEASE. Если этот флаг указан, функция возвращает STG_E_INVALIDFLAG.

IStorage::OpenStorage

Открывает существующий объект хранилища с указанным именем в указанном режиме доступа. Символы от 000 до 01f, служащие как первый символ имени потока/хранилища, зарезервированы для использования OLE. Это ограничение составного файла, а ограничение структурированного хранения. Предоставляемая COM реализация составного файла метода IStorage::OpenStorage не поддерживает следующее поведение:

  • Флаг STGM_PRIORITY для некоревых хранилищ.
  • Открытие одного и того же объекта хранилища несколько раз из одного родительского хранилища. Необходимо указать флаг STGM_SHARE_EXCLUSIVE.
  • Флаг STGM_DELETEONRELEASE. Если этот флаг указан, функция возвращает STG_E_INVALIDFUNCTION.

IStorage::CopyTo

Копирует только вложенные журналы и потоки этого открытого объекта хранилища в другой объект хранения. Параметру rgiidExclude можно задать значение IID_IStream для копирования только вложенных журналов или для IID_IStorage для копирования только потоков.

IStorage::MoveElementTo

Копирует или перемещает вложенный журнал или поток из этого объекта хранилища в другой объект хранилища.

IStorage::Commit

Гарантирует, что все изменения, внесенные в объект хранилища, открытый в режиме транзакций, отражаются в родительском хранилище; для корневого хранилища отражает изменения на фактическом устройстве; например, файл на диске. Для корневого объекта хранилища, открытого в прямом режиме, этот метод не оказывает никакого влияния, за исключением очистки всех буферов памяти на диск. Этот метод не действует для объектов, не относящихся к корню, в прямом режиме.

В реализации составных файлов, предоставляемых COM, используется двухэтапный процесс фиксации, если STGC_OVERWRITE не указан в параметре grfCommitFlags . Этот двухэтапный процесс обеспечивает надежность данных в случае сбоя операции фиксации. Во-первых, все новые данные записываются в неиспользуемое пространство в базовом файле. При необходимости для файла выделяется новое пространство. После завершения этого шага таблица в файле обновляется с помощью операции записи в одном секторе, чтобы указать, что новые данные будут использоваться вместо старых. Старые данные становятся свободными для использования при следующей операции фиксации. Таким образом, старые данные доступны и могут быть восстановлены при возникновении ошибки при фиксации изменений. Если указано STGC_OVERWRITE, используется однофазная операция фиксации. Дополнительные сведения о флагах режима транзакций см. в разделе Перечисление STGC .

IStorage::Revert

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

IStorage::EnumElements

Создает и извлекает указатель на объект перечислителя, который можно использовать для перечисления объектов хранилища и потоков, содержащихся в этом объекте хранилища. Реализация составного файла, предоставляемая COM, принимает snapshot этих сведений. Поэтому изменения в потоках и хранилищах не отражаются в перечислителе, пока не будет получен новый перечислитель.

IStorage::D etraitsElement

Удаляет указанный элемент (вложенный журнал или поток) из этого объекта хранилища.

IStorage::RenameElement

Переименовывает указанный вложенный журнал или поток в этом объекте хранилища. Символы от 000 до 01f, служащие как первый символ имени потока/хранилища, зарезервированы для использования OLE. Это ограничение составного файла, а ограничение структурированного хранения.

IStorage::SetElementTimes

Задает время изменения, доступа и создания указанного элемента хранилища. Реализация составного файла, предоставляемая COM, поддерживает изменения и время изменения для внутренних объектов хранения. Объекты корневого хранилища поддерживают все, что поддерживается базовой файловой системой (или ILockBytes). Реализация составного файла не поддерживает метки времени для внутренних потоков. Неподдерживаемые метки времени отображаются как ноль, что позволяет вызывающей стороны проверить поддержку.

IStorage::SetClass

Назначает указанный идентификатор CLSID этому объекту хранилища.

IStorage::SetStateBits

Хранит до 32 бит сведений о состоянии в этом объекте хранилища. Состояние, заданное этим методом, предназначено только для внешнего использования. Реализация составного файла, предоставляемая COM, не выполняет никаких действий в зависимости от состояния.

IStorage::Stat

Извлекает структуру STATSTG для этого открытого объекта хранилища.

Комментарии

Если объект хранилища открыт в простом режиме, использование указанных выше методов ограничено. Хранилище находится в простом режиме, если оно открыто с помощью элемента STGM_SIMPLE, указанного в параметре grfMode функции StgCreateStorageEx или StgOpenStorageEx . Дополнительные сведения о хранилищах в простом режиме см. в разделе Константы STGM. Если объект хранения в простом режиме был получен из функции StgCreateStorageEx , можно вызвать метод CreateStream , но метод OpenStream — нет. Если объект хранения в простом режиме был получен из функции StgOpenStorageEx , можно вызвать метод OpenStream , но метод CreateStream — нет.

Если для создания потока используется объект хранилища в простом режиме, минимальный размер этого потока обычно составляет 4096 байт. Если в поток записывается меньше данных, размер округляется до 4096 байт.

Ограничения реализации составных файлов

IFillLockBytes

ILockBytes

IRootStorage

IStorage

IStream

StgCreateDocfile

StgCreateStorageEx

StgOpenStorage

StgOpenStorageEx