Функция StgCreateDocfileOnILockBytes (coml2api.h)

  • Статья

Функция StgCreateDocfileOnILockBytes создает и открывает новый объект хранилища составных файлов поверх объекта массива байтов, предоставленного вызывающим объектом. Объект хранилища поддерживает предоставленную COM реализацию составного файла для интерфейса IStorage .

Синтаксис

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Параметры

[in] plkbyt

Указатель на интерфейс ILockBytes для базового объекта массива байтов, на котором создается составной файл.

[in] grfMode

Указывает режим доступа, используемый при открытии нового составного файла. Дополнительные сведения см. в разделе Константы STGM и в разделе Примечания ниже.

[in] reserved

Зарезервировано для будущего использования; должно иметь значение нуль.

[out] ppstgOpen

Указатель на расположение указателя IStorage на новом объекте хранилища.

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

Функция StgCreateDocfileOnILockBytes также может возвращать любые ошибки файловой системы или системные ошибки, заключенные в HRESULT, или возвращаемые значения ошибок интерфейса ILockBytes . Дополнительные сведения см. в разделах Стратегии обработки ошибок и Обработка неизвестных ошибок.

Комментарии

Функция StgCreateDocfileOnILockBytes создает объект хранилища поверх объекта массива байтов, используя предоставленную COM реализацию составного файла интерфейса IStorage . StgCreateDocfileOnILockBytes можно использовать для хранения документа в произвольном хранилище данных, например в памяти или реляционной базе данных. Массив байтов (обозначается параметром pLkbyt , указывающим на интерфейс ILockBytes объекта) используется для базового хранилища вместо файла диска.

За исключением указания предоставленного программистом объекта массива байтов, StgCreateDocfileOnILockBytes аналогичен функции StgCreateDocfile .

Вновь созданный составной файл открывается в соответствии с режимами доступа в параметре grfMode с учетом следующих ограничений:

Режим совместного использования и изоляция транзакций зависят от реализации ILockBytes , поддерживающей LockRegion и UnlockRegion с LOCK_ONLYONCE семантикой. Реализации могут указывать на то, что структурированное хранилище поддерживает эту функцию, задав бит LOCK_ONLYONCE в элементе grfLocksSupportedSTATSTG. Если реализация ILockBytes не поддерживает эту функцию, режимы совместного использования не будут применяться, а фиксации транзакций корневого уровня не будут должным образом координироваться с другими экземплярами транзакций, открытыми в том же массиве байтов. Приложения, использующие реализацию ILockBytes , не поддерживающую блокировку регионов, такие как реализация CreateStreamOnHGlobal , не должны открывать несколько параллельных экземпляров в одном массиве байтов.

StgCreateDocfileOnILockBytes не поддерживает простой режим. Флаг STGM_SIMPLE , если он присутствует, игнорируется.

В целях преобразования файл считается уже существующим. В результате использовать значение STGM_FAILIFTHERE бесполезно, так как это приводит к возврату ошибки. Однако STGM_CREATE и STGM_CONVERT остаются полезными.

Возможность создания составного файла на основе объекта массива байтов предоставляется для поддержки размещения данных (под структурой дерева IStorage и IStream ) в неперсистентном пространстве. Учитывая эту возможность, ничто не мешает документу, хранящейся в файле, использовать эту возможность. Например, контейнер может сделать это, чтобы свести к минимуму влияние на его формат файла, вызванное внедрением COM. Однако рекомендуется, чтобы com-документы приняли интерфейс IStorage для собственного хранилища внешнего уровня. Подобное разделение обеспечивает следующие преимущества.

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

Требования

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

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

StgCreateDocfile