Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Fungsi CreateILockBytesOnHGlobal membuat objek array byte yang menggunakan handel memori HGLOBAL untuk menyimpan byte yang ditujukan untuk penyimpanan dalam memori file majemuk. Objek ini adalah implementasi antarmuka ILockBytes yang disediakan OLE.
Objek array byte yang dikembalikan mendukung pembacaan dan penulisan, tetapi tidak mendukung penguncian wilayah . Objek memanggil fungsi GlobalReAlloc untuk menumbuhkan blok memori sesuai kebutuhan.
Sintaks
HRESULT CreateILockBytesOnHGlobal(
[in] HGLOBAL hGlobal,
[in] BOOL fDeleteOnRelease,
[out] LPLOCKBYTES *pplkbyt
);
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
Bendera yang menentukan apakah handel yang mendasar untuk objek array byte ini harus dibebaskan secara otomatis saat objek dilepaskan. Jika diatur ke FALSE, pemanggil harus membebaskan hGlobal setelah rilis akhir. Jika diatur ke TRUE, rilis akhir akan secara otomatis membebaskan parameter hGlobal .
[out] pplkbyt
Alamat variabel penunjuk ILockBytes yang menerima penunjuk antarmuka ke objek array byte baru.
Nilai kembali
Fungsi ini mendukung nilai pengembalian standar E_INVALIDARG dan E_OUTOFMEMORY, serta yang berikut:
Keterangan
Jika hGlobal adalah NULL, CreateILockBytesOnHGlobal mengalokasikan handel memori baru dan array byte awalnya kosong.
Jika hGlobal bukan NULL, konten awal objek array byte adalah konten blok memori saat ini. Dengan demikian, fungsi ini dapat digunakan untuk membuka array byte yang ada dalam memori, misalnya untuk memuat ulang objek penyimpanan yang sebelumnya dibuat oleh fungsi StgCreateDocfileOnILockBytes . Handel memori dan isinya tidak terganggu oleh pembuatan objek array byte baru.
Ukuran awal array byte adalah ukuran hGlobal seperti yang dikembalikan oleh fungsi GlobalSize . Ini belum tentu ukuran yang sama yang awalnya dialokasikan untuk handel karena pembulatan. Jika ukuran logis array byte penting, ikuti panggilan ke CreateILockBytesOnHGlobal dengan panggilan ke ILockBytes::SetSize.
Setelah membuat objek array byte dengan CreateStreamOnHGlobal, StgCreateDocfileOnILockBytes dapat digunakan untuk membuat objek penyimpanan baru dalam memori, atau StgOpenStorageOnILockBytes dapat digunakan untuk membuka kembali objek penyimpanan yang sudah ada sebelumnya yang sudah terkandung dalam blok memori. GetHGlobalFromILockBytes dapat dipanggil untuk mengambil handel memori yang terkait dengan objek array byte.
Jika handel memori diteruskan ke CreateILockBytesOnHGlobal atau jika GetHGlobalFromILockBytes dipanggil, handel memori fungsi ini dapat langsung diakses oleh pemanggil saat masih digunakan oleh objek array byte. Perhatian yang tepat harus dilakukan dalam penggunaan kemampuan ini dan implikasinya:
- Jangan bebaskan handel memori hGlobal selama masa pakai objek array byte. ILockBytes::Release harus dipanggil sebelum handel memori dibebaskan.
- Jangan panggil GlobalReAlloc untuk mengubah ukuran handel memori selama masa pakai objek array byte. Ini dapat menyebabkan crash aplikasi atau kerusakan memori. Hindari membuat beberapa objek array byte pada handel memori yang sama, karena metode ILockBytes::WriteAt dan ILockBytes::SetSize dapat secara internal memanggil GlobalReAlloc.
- Jika memungkinkan, hindari mengakses blok memori selama masa pakai objek array byte, 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 handel memori dikunci dengan GlobalLock. Hal ini dapat menyebabkan panggilan metode gagal secara tak terduga.
HGLOBAL hMem = ::GlobalAlloc(GMEM_MOVEABLE,iSize);
if (!hMem)
AfxThrowMemoryException();
LPVOID pCompoundFile = ::GlobalLock(hMem);
... // Fill memory
::GlobalUnlock(hMem);
CComPtr<ILockBytes> spLockBytes;
HRESULT hr = ::CreateILockBytesOnHGlobal(hMem,FALSE,&spLockBytes);
CreateILockBytesOnHGlobal akan menerima memori yang dialokasikan dengan GMEM_FIXED, tetapi penggunaan ini tidak disarankan. HGLOBALs yang dialokasikan dengan GMEM_FIXED tidak benar-benar menangani dan nilainya dapat berubah ketika mereka dialokasikan kembali. Jika handel memori dialokasikan dengan GMEM_FIXED dan fDeleteOnRelease adalah FALSE, maka pemanggil harus memanggil GetHGlobalFromILockBytes untuk mendapatkan nilai HGLOBAL yang benar untuk membebaskan handel.
Implementasi ILockBytes ini tidak mendukung penguncian wilayah. Aplikasi yang menggunakan implementasi ini dengan fungsi StgCreateDocfileOnILockBytes atau StgOpenStorageOnILockBytes harus menghindari pembukaan beberapa instans bersamaan pada objek ILockBytes yang sama.
Sebelum Windows 7 dan Windows Server 2008 R2, implementasi ini tidak nol memori saat memanggil GlobalReAlloc untuk menumbuhkan blok memori. Meningkatkan ukuran array byte dengan ILockBytes::SetSize atau dengan menulis ke lokasi yang melewati akhir array byte saat ini akan membuat bagian yang tidak ditulis dari memori yang baru dialokasikan tidak diinisialisasi. Objek penyimpanan yang dikembalikan oleh StgCreateDocfileOnILockBytes dan StgOpenStorageOnILockBytes dapat meningkatkan ukuran array byte tanpa menginisialisasi semua ruang yang baru dialokasikan.
File campuran dalam memori biasanya digunakan sebagai ruang goresan atau dengan API yang memerlukan objek penyimpanan, dan dalam kasus ini memori yang tidak diinisialisasi umumnya bukan masalah. Namun, jika konten blok memori akan ditulis ke file, pertimbangkan alternatif berikut untuk menghindari potensi pengungkapan informasi:
- Salin konten logis dari file senyawa dalam memori ke file tujuan menggunakan metode IStorage::CopyTo daripada secara langsung menulis konten blok memori.
- Alih-alih file campuran dalam memori, buat file sementara dengan memanggil StgCreateStorageEx dengan nilai NULL untuk parameter pwcsName . Ketika saatnya untuk menulis ke file tujuan, gunakan metode IRootStorage::SwitchToFile .
- Terapkan antarmuka ILockBytes sehingga realokasi memori di-nol (lihat misalnya bendera HEAP_ZERO_MEMORY di HeapReAlloc). Isi memori dari array byte ini kemudian dapat ditulis ke file.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| 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 | coml2api.h (termasuk Ole2.h) |
| Pustaka | Ole32.lib |
| DLL | Ole32.dll |