Fungsi CreateStreamOnHGlobal (combaseapi.h)

Artikel
08/22/2023

Fungsi CreateStreamOnHGlobal membuat objek aliran yang menggunakan handel memori HGLOBAL untuk menyimpan konten aliran. Objek ini adalah implementasi antarmuka IStream yang disediakan OLE.

Objek stream yang dikembalikan mendukung pembacaan dan penulisan, tidak ditransaksikan, dan tidak mendukung penguncian wilayah. Objek memanggil fungsi GlobalReAlloc untuk menumbuhkan blok memori sesuai kebutuhan.

Tips Pertimbangkan untuk menggunakan fungsi SHCreateMemStream , yang menghasilkan performa yang lebih baik, atau untuk aplikasi Windows Store, pertimbangkan untuk menggunakan InMemoryRandomAccessStream.

Sintaks

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

Parameter

[in] hGlobal

Handel memori yang dialokasikan oleh fungsi GlobalAlloc , atau jika NULL handel baru akan dialokasikan sebagai gantinya. Handel harus dialokasikan sebagai dapat dipindahkan dan tidak dapat dikodekan.

[in] fDeleteOnRelease

Nilai yang menunjukkan apakah handel yang mendasar untuk objek stream ini harus secara otomatis dibebaskan saat objek stream dirilis. Jika diatur ke FALSE, pemanggil harus membebaskan hGlobal setelah rilis akhir. Jika diatur ke TRUE, rilis akhir akan secara otomatis membebaskan handel yang mendasar. Lihat Keterangan untuk diskusi lebih lanjut tentang kasus di mana fDeleteOnReleaseadalah FALSE.

[out] ppstm

Alamat variabel pointer IStream* yang menerima penunjuk antarmuka ke objek stream baru. Nilainya tidak boleh NULL.

Mengembalikan nilai

Fungsi ini mendukung nilai pengembalian standar E_INVALIDARG dan E_OUTOFMEMORY, serta yang berikut ini.

Keterangan

Jika hGlobalNULL, fungsi mengalokasikan handel memori baru dan aliran awalnya kosong.

Jika hGlobal bukan NULL, konten awal aliran adalah konten blok memori saat ini. Dengan demikian, CreateStreamOnHGlobal dapat digunakan untuk membuka aliran yang ada dalam memori. Handel memori dan kontennya tidak terganggu oleh pembuatan objek stream baru.

Ukuran awal aliran adalah ukuran hGlobal seperti yang dikembalikan oleh fungsi GlobalSize . Karena pembulatan, ukuran ini belum tentu sama dengan yang awalnya dialokasikan untuk handel. Jika ukuran logis aliran penting, ikuti panggilan ke fungsi ini dengan panggilan ke metode IStream::SetSize .

Posisi pencarian awal objek stream baru adalah awal aliran.

Setelah membuat objek stream dengan CreateStreamOnHGlobal, panggil GetHGlobalFromStream untuk mengambil handel memori yang terkait dengan objek stream.

Jika handel memori diteruskan ke CreateStreamOnHGlobal atau jika GetHGlobalFromStream dipanggil, handel memori fungsi ini dapat langsung diakses oleh pemanggil saat masih digunakan oleh objek stream. Perhatian yang tepat harus dilakukan dalam penggunaan kemampuan ini dan implikasinya:

Jangan bebaskan handel memori hGlobal selama masa pakai objek stream. IStream::Release harus dipanggil sebelum membebaskan handel memori.
Jangan panggil GlobalReAlloc untuk mengubah ukuran handel memori selama masa pakai objek stream atau kloningnya. Ini dapat menyebabkan crash aplikasi atau kerusakan memori. Hindari membuat beberapa objek stream secara terpisah pada handel memori yang sama, karena metode IStream::Write dan IStream::SetSize dapat secara internal memanggil GlobalReAlloc. Metode IStream::Clone dapat digunakan untuk membuat objek stream baru berdasarkan handel memori yang sama yang akan mengoordinasikan aksesnya dengan benar dengan objek stream asli.
Jika memungkinkan, hindari mengakses blok memori selama masa pakai objek stream, karena objek dapat secara internal memanggil GlobalReAlloc dan tidak membuat asumsi tentang ukuran dan lokasinya. Jika blok memori harus diakses, panggilan akses memori harus dikelilingi oleh panggilan ke GlobalLock dan GlobalUnLock.
Hindari memanggil metode objek saat Anda mengunci handel memori dengan GlobalLock. Ini dapat menyebabkan panggilan metode gagal tanpa diduga.

Jika parameter fDeleteOnReleaseFALSE, pemanggil bertanggung jawab untuk membebaskan handel memori yang mendasar, bahkan jika parameter hGlobaladalah NULL. Gunakan fungsi GetHGlobalFromStream untuk mendapatkan handel memori yang mendasarinya dan GlobalFree memori tersebut setelah referensi terakhir ke aliran dirilis. Jika pemanggil mengatur parameter fDeleteOnRelease ke TRUE, rilis akhir akan secara otomatis membebaskan handel memori yang mendasar.

Handel memori yang diteruskan sebagai parameter hGlobal harus dialokasikan sebagai movable dan nondiscardable, seperti yang ditunjukkan dalam contoh berikut:

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 akan menerima handel memori yang dialokasikan dengan GMEM_FIXED, tetapi penggunaan ini tidak disarankan. HGLOBALs yang dialokasikan dengan GMEM_FIXED tidak benar-benar ditangani dan nilainya dapat berubah ketika mereka dialokasikan kembali. Jika handel memori dialokasikan dengan GMEM_FIXED dan fDeleteOnReleasefalse, pemanggil harus memanggil GetHGlobalFromStream untuk mendapatkan handel yang benar untuk membebaskannya.

Sebelum Windows 7 dan Windows Server 2008 R2, implementasi ini tidak nol memori saat memanggil GlobalReAlloc untuk menumbuhkan blok memori. Meningkatkan ukuran aliran dengan IStream::SetSize atau dengan menulis ke lokasi yang melewati akhir aliran saat ini dapat membuat bagian memori yang baru dialokasikan tidak diinisialisasi.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows 2000 Server [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	combaseapi.h
Pustaka	Ole32.lib
DLL	Ole32.dll

Lihat juga

GetHGlobalFromStream

IStream - Implementasi File Manggala

IStream::SetSize

InMemoryRandomAccessStream

Share via