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

Статья
08/22/2023

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

Синтаксис

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Параметры

[in] plkbyt

ILockBytes — указатель на базовый объект массива байтов, содержащий открываемый объект хранилища.

[in] pstgPriority

Указатель на интерфейс IStorage , который должен иметь значение NULL. Если значение не равно NULL, этот параметр используется, как описано ниже в разделе Примечания.

После возврата StgOpenStorageOnILockBytes объект хранилища, указанный в pStgPriority , может быть освобожден и больше не должен использоваться.

[in] grfMode

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

[in] snbExclude

Может иметь значение NULL. Если значение не равно NULL, этот параметр указывает на блок элементов в этом хранилище, которые должны быть исключены при открытии объекта хранилища. Это исключение происходит независимо от того, выполняется ли snapshot копирование при открытии.

[in] reserved

Указывает, зарезервировано для использования в будущем; значение должно быть равно нулю.

[out] ppstgOpen

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

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

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

StgOpenStorageOnILockBytes открывает указанный корневой объект хранилища. Указатель на интерфейс IStorage в открытом объекте хранилища предоставляется с помощью параметра ppstgOpen .

Объект хранилища должен быть ранее создан функцией StgCreateDocfileOnILockBytes .

За исключением указания предоставленного программистом объекта массива байтов, StgOpenStorageOnILockBytes аналогичен функции StgOpenStorage . Объект хранилища открывается в соответствии с режимами доступа в параметре grfMode с учетом следующих ограничений:

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

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

Параметр pStgPriority предназначен для удобства для вызывающих объектов, заменяющих существующий объект хранилища, часто открытый в режиме приоритета, новым объектом хранилища, открытым в том же массиве байтов. В отличие от параметра pStgPrioritystgOpenStorage, этот параметр не влияет на операцию открытия, выполняемую StgOpenStorageOnILockBytes , и является просто существующим объектом хранилища, который вызывающий объект хотел бы освободить. Вызывающие объекты всегда должны передавать значение NULL для этого параметра, так как StgOpenStorageOnILockBytes при некоторых обстоятельствах освобождает объект и не освобождает его при других обстоятельствах. Использование параметра pStgPriority может быть дублировано вызывающим объектом более безопасным способом, вместо этого отпустив объект перед вызовом StgOpenStorageOnILockBytes, как показано в следующем примере:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &amp;pstgNew);

pStgPriority-&gt;Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &amp;pstgNew);

Дополнительные сведения см. в статье StgOpenStorage.

Требования

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

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

StgCreateDocfileOnILockBytes

StgOpenStorage