Функция StgOpenStorageOnILockBytes (coml2api.h)
Функция 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, &pstgNew);
pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);
Дополнительные сведения см. в статье StgOpenStorage.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | coml2api.h (включая Objbase.h) |
| Библиотека | Ole32.lib |
| DLL | Ole32.dll |