CreateStreamOnHGlobal-Funktion (combaseapi.h)

  • Artikel

Die CreateStreamOnHGlobal-Funktion erstellt ein Streamobjekt, das ein HGLOBAL-Speicherhandle zum Speichern des Streaminhalts verwendet. Dieses Objekt ist die von OLE bereitgestellte Implementierung der IStream-Schnittstelle .

Das zurückgegebene Streamobjekt unterstützt sowohl Lesen als auch Schreiben, wird nicht abgewickelt und unterstützt keine Regionssperrung. Das -Objekt ruft die GlobalReAlloc-Funktion auf, um den Speicherblock nach Bedarf zu vergrößern.

Tipp Erwägen Sie, die SHCreateMemStream-Funktion zu verwenden, die eine bessere Leistung erzeugt, oder für Windows Store-Apps die Verwendung von InMemoryRandomAccessStream.
 

Syntax

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

Parameter

[in] hGlobal

Ein Speicherhandle, das von der GlobalAlloc-Funktion zugewiesen wird, oder wenn null stattdessen ein neues Handle zugewiesen werden soll. Der Handle muss als bewegliches und nicht auflösbares Element zugeordnet werden.

[in] fDeleteOnRelease

Ein Wert, der angibt, ob das zugrunde liegende Handle für dieses Streamobjekt automatisch freigegeben werden soll, wenn das Streamobjekt freigegeben wird. Wenn auf FALSE festgelegt ist, muss der Aufrufer den hGlobal nach dem endgültigen Release freigeben. Wenn auf TRUE festgelegt ist, gibt das endgültige Release automatisch den zugrunde liegenden Handle frei. Weitere Informationen zu dem Fall, in dem fDeleteOnReleasefalse ist, finden Sie in den Anmerkungen.

[out] ppstm

Die Adresse der IStream*-Zeigervariable, die den Schnittstellenzeiger auf das neue Streamobjekt empfängt. Sein Wert darf nicht NULL sein.

Rückgabewert

Diese Funktion unterstützt die Standardrückgabewerte E_INVALIDARG und E_OUTOFMEMORY sowie folgendes.

Hinweise

Wenn hGlobalNULL ist, weist die Funktion ein neues Speicherhandle zu, und der Stream ist zunächst leer.

Wenn hGlobal nicht NULL ist, ist der anfängliche Inhalt des Datenstroms der aktuelle Inhalt des Speicherblocks. Daher kann CreateStreamOnHGlobal verwendet werden, um einen vorhandenen Stream im Arbeitsspeicher zu öffnen. Das Speicherhandle und dessen Inhalt werden durch die Erstellung des neuen Streamobjekts nicht gestört.

Die anfängliche Größe des Datenstroms entspricht der Größe von hGlobal , die von der GlobalSize-Funktion zurückgegeben wird. Aufgrund der Rundung ist dies nicht unbedingt die gleiche Größe, die ursprünglich für den Handle zugewiesen wurde. Wenn die logische Größe des Datenstroms wichtig ist, folgen Sie dem Aufruf dieser Funktion mit einem Aufruf der IStream::SetSize-Methode .

Die anfängliche Suchposition des neuen Streamobjekts ist der Anfang des Datenstroms.

Nachdem Sie das Streamobjekt mit CreateStreamOnHGlobal erstellt haben, rufen Sie GetHGlobalFromStream auf, um das dem Streamobjekt zugeordnete Speicherhandle abzurufen.

Wenn ein Speicherhandle an CreateStreamOnHGlobal übergeben wird oder GetHGlobalFromStream aufgerufen wird, kann der Aufrufer direkt auf das Speicherhandle dieser Funktion zugreifen, während es noch vom Streamobjekt verwendet wird. Bei der Nutzung dieser Funktion und ihrer Auswirkungen sollte mit angemessener Vorsicht vorzugehen sein:

  • Geben Sie das hGlobal-Speicherhandle während der Lebensdauer des Streamobjekts nicht frei. IStream::Release muss aufgerufen werden, bevor das Speicherhandle freigegeben wird.
  • Rufen Sie GlobalReAlloc nicht auf, um die Größe des Speicherhandles während der Lebensdauer des Streamobjekts oder seiner Klone zu ändern. Dies kann zu Anwendungsabstürzen oder Speicherbeschädigungen führen. Vermeiden Sie das separate Erstellen mehrerer Streamobjekte im selben Speicherhandle, da die Methoden IStream::Write und IStream::SetSize intern GlobalReAlloc aufrufen können. Die IStream::Clone-Methode kann verwendet werden, um ein neues Streamobjekt basierend auf demselben Speicherhandle zu erstellen, das den Zugriff ordnungsgemäß mit dem ursprünglichen Streamobjekt koordiniert.
  • Vermeiden Sie nach Möglichkeit den Zugriff auf den Speicherblock während der Lebensdauer des Streamobjekts, da das Objekt möglicherweise Intern GlobalReAlloc aufruft und keine Annahmen über seine Größe und Position treffen. Wenn auf den Speicherblock zugegriffen werden muss, sollten die Speicherzugriffsaufrufe von Aufrufen von GlobalLock und GlobalUnLock umgeben sein.
  • Vermeiden Sie das Aufrufen der Methoden des Objekts, während Sie das Speicherhandle mit GlobalLock gesperrt haben. Dies kann dazu führen, dass Methodenaufrufe unvorhersehbar ausfallen.
Wenn der fDeleteOnRelease-ParameterFALSE ist, ist der Aufrufer für das Freigeben des zugrunde liegenden Speicherhandles verantwortlich, auch wenn der hGlobal-ParameterNULL ist. Verwenden Sie die GetHGlobalFromStream-Funktion , um den zugrunde liegenden Speicherhandle und GlobalFree abzurufen, den Arbeitsspeicher nach dem letzten Verweis auf den Stream freigegeben hat. Wenn der Aufrufer den fDeleteOnRelease-Parameter auf TRUE festlegt, gibt das endgültige Release automatisch das zugrunde liegende Speicherhandle frei.

Das als hGlobal-Parameter übergebene Speicherhandle muss als verschiebbar und nicht auflösbar zugeordnet werden, wie im folgenden Beispiel gezeigt:

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 akzeptiert ein Speicherhandle, das GMEM_FIXED zugeordnet ist, aber diese Verwendung wird nicht empfohlen. HGLOBALs, die GMEM_FIXED zugeordnet sind, sind nicht wirklich Handles, und ihr Wert kann sich ändern, wenn sie neu zugeordnet werden. Wenn das Speicherhandle GMEM_FIXED zugeordnet wurde und fDeleteOnReleasefalse ist, muss der Aufrufer GetHGlobalFromStream aufrufen, um das richtige Handle zu erhalten, um es freizugeben.

Vor Windows 7 und Windows Server 2008 R2 hatte diese Implementierung beim Aufrufen von GlobalReAlloc nicht null Arbeitsspeicher, um den Arbeitsspeicherblock zu vergrößern. Wenn Sie die Größe des Datenstroms mit IStream::SetSize oder durch Schreiben an einen Speicherort am aktuellen Ende des Datenstroms erhöhen, werden Teile des neu zugewiesenen Arbeitsspeichers möglicherweise nicht initialisiert.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 2000 Professional [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile combaseapi.h
Bibliothek Ole32.lib
DLL Ole32.dll

Weitere Informationen

GetHGlobalFromStream

IStream – Implementierung zusammengesetzter Dateien

IStream::SetSize

InMemoryRandomAccessStream