Функция CreateStreamOnHGlobal (combaseapi.h)

Статья
08/22/2023

Функция CreateStreamOnHGlobal создает объект потока, который использует дескриптор памяти HGLOBAL для хранения содержимого потока. Этот объект является реализацией интерфейса IStream , предоставляемой OLE.

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

Совет Рассмотрите возможность использования функции SHCreateMemStream , которая обеспечивает более высокую производительность, или для приложений Магазина Windows рассмотрите возможность использования InMemoryRandomAccessStream.

Синтаксис

HRESULT CreateStreamOnHGlobal(
  [in]  HGLOBAL  hGlobal,
  [in]  BOOL     fDeleteOnRelease,
  [out] LPSTREAM *ppstm
);

Параметры

[in] hGlobal

Дескриптор памяти, выделенный функцией GlobalAlloc , или, если значение NULL , выделяется новый дескриптор. Дескриптор должен быть выделен как перемещаемый и неразглавный.

[in] fDeleteOnRelease

Значение типа , указывающее, должен ли базовый дескриптор этого объекта потока автоматически освобождаться при освобождении объекта потока. Если задано значение FALSE, вызывающий объект должен освободить hGlobal после окончательного выпуска. Если задано значение TRUE, окончательный выпуск автоматически освободит базовый дескриптор. Дополнительные сведения о случае, когда fDeleteOnRelease имеет значение FALSE, см. в примечаниях.

[out] ppstm

Адрес переменной указателя IStream*, которая получает указатель интерфейса на новый объект потока. Его значение не может быть NULL.

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

Эта функция поддерживает стандартные возвращаемые значения E_INVALIDARG и E_OUTOFMEMORY, а также следующие.

Если hGlobal не равно NULL, начальное содержимое потока является текущим содержимым блока памяти. Таким образом, createStreamOnHGlobal можно использовать для открытия существующего потока в памяти. Дескриптор памяти и его содержимое не нарушаются при создании нового объекта потока.

Начальный размер потока — это размер hGlobal , возвращаемый функцией GlobalSize . Из-за округления это не обязательно тот же размер, который был изначально выделен для дескриптора. Если важен логический размер потока, выполните вызов этой функции с вызовом метода IStream::SetSize .

Начальная позиция поиска нового объекта потока является началом потока.

После создания объекта потока с помощью CreateStreamOnHGlobal вызовите Метод GetHGlobalFromStream , чтобы получить дескриптор памяти, связанный с объектом потока.

Если дескриптор памяти передается в CreateStreamOnHGlobal или вызывается метод GetHGlobalFromStream , вызывающий объект может напрямую обращаться к дескриптору памяти этой функции, пока он все еще используется объектом потока. Следует проявлять соответствующую осторожность при использовании этой возможности и ее последствиях:

Не освобождайте дескриптор памяти hGlobal в течение времени существования объекта потока. IStream::Release необходимо вызвать перед освобождением дескриптора памяти.
Не вызывайте GlobalReAlloc для изменения размера дескриптора памяти в течение времени существования объекта потока или его клонов. Это может привести к сбоям приложения или повреждению памяти. Избегайте создания нескольких объектов потока по отдельности в одном дескрипторе памяти, так как методы IStream::Write и IStream::SetSize могут вызывать GlobalReAlloc. Метод IStream::Clone можно использовать для создания нового объекта потока на основе того же дескриптора памяти, который будет правильно координировать доступ к исходному объекту потока.
По возможности избегайте доступа к блоку памяти в течение времени существования объекта потока, так как объект может вызывать GlobalReAlloc и не делать предположений о его размере и расположении. Если требуется доступ к блоку памяти, вызовы доступа к памяти должны быть окружены вызовами GlobalLock и GlobalUnLock.
Избегайте вызова методов объекта, пока дескриптор памяти заблокирован с помощью GlobalLock. Это может привести к непредсказуемой ошибке вызовов методов.

Если параметр fDeleteOnRelease имеет значение FALSE, вызывающий объект отвечает за освобождение базового дескриптора памяти, даже если параметр hGlobal имеет значение NULL. Используйте функцию GetHGlobalFromStream , чтобы получить базовый дескриптор памяти и GlobalFree , что память после освобождения последней ссылки на поток. Если вызывающий объект задает для параметра fDeleteOnReleaseзначение TRUE, окончательный выпуск автоматически освободит базовый дескриптор памяти.

Дескриптор памяти, переданный в качестве параметра hGlobal , должен быть выделен как перемещаемый и неразглашенный, как показано в следующем примере:

HGLOBAL	hMem = ::GlobalAlloc(GMEM_MOVEABLE,iSize);
if (!hMem)
    AfxThrowMemoryException();

LPVOID pImage = ::GlobalLock(hMem);
... // Fill memory
::GlobalUnlock(hMem);

CComPtr<IStream> spStream;
HRESULT hr = ::CreateStreamOnHGlobal(hMem,FALSE,&spStream);

CreateStreamOnHGlobal принимает дескриптор памяти, выделенный с GMEM_FIXED, но это использование не рекомендуется. HGLOBALs, выделенные с помощью GMEM_FIXED , на самом деле не являются дескрипторами, и их значение может измениться при перераспределении. Если дескриптор памяти был выделен с помощью GMEM_FIXED а fDeleteOnRelease имеет значение FALSE, вызывающий объект должен вызвать GetHGlobalFromStream , чтобы получить правильный дескриптор, чтобы освободить его.

До Windows 7 и Windows Server 2008 R2 эта реализация не обнуляла память при вызове GlobalReAlloc для увеличения блока памяти. Увеличение размера потока с помощью IStream::SetSize или путем записи в расположение после текущего конца потока может оставить части вновь выделенной памяти неинициализированными.

Требования


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

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

GetHGlobalFromStream

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

IStream::SetSize

InMemoryRandomAccessStream