Fungsi WindowsPreallocateStringBuffer (winstring.h)

Artikel
10/20/2023

Mengalokasikan buffer karakter yang dapat diubah untuk digunakan dalam pembuatan HSTRING .

Sintaks

HRESULT WindowsPreallocateStringBuffer(
  UINT32         length,
  WCHAR          **charBuffer,
  HSTRING_BUFFER *bufferHandle
);

Parameter

length

Jenis: [in] UINT32

Ukuran buffer yang akan dialokasikan. Nilai nol sesuai dengan string kosong.

charBuffer

Jenis: [out] WCHAR**

Buffer yang dapat diubah yang menyimpan karakter. Perhatikan bahwa buffer sudah berisi karakter NULL yang mengakhiri.

bufferHandle

Jenis: [out] HSTRING_BUFFER*

Buffer string yang dialokasikan sebelumnya, atau NULL jika panjangnya adalah 0.

Mengembalikan nilai

Jenis: HRESULT

Fungsi ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode	Deskripsi
S_OK	HSTRING berhasil dibuat.
E_POINTER	mutableBuffer atau bufferHandle adalah NULL.
MEM_E_INVALID_SIZE	Ukuran alokasi HSTRING yang diminta terlalu besar.
E_OUTOFMEMORY	Gagal mengalokasikan HSTRING.

Keterangan

Gunakan fungsi WindowsPreallocateStringBuffer untuk membuat buffer karakter yang dapat diubah yang dapat Anda manipulasi sebelum menerapkannya ke HSTRING yang tidak dapat diubah. Setelah Anda selesai mengisi mutableBuffer dengan string Anda, panggil fungsi WindowsPromoteStringBuffer dengan parameter bufferHandle untuk membuat HSTRING. Anda harus menulis karakter panjang persis ke dalam buffer. Windows 10 Versi 1803, Windows Server Versi 1803, dan yang lebih baru: Anda diizinkan untuk menulis terminator null setelah karakter panjang.

Panggil fungsi WindowsDeleteStringBuffer untuk membuang buffer yang dapat diubah sebelum promosi. Jika buffer telah dipromosikan oleh panggilan ke WindowsPromoteStringBuffer, panggil fungsi WindowsDeleteString untuk membuang string. Jika panggilan WindowsPromoteStringBuffer gagal, Anda dapat memanggil fungsi WindowsDeleteStringBuffer untuk membuang buffer yang dapat diubah.

Contoh

Contoh kode berikut menunjukkan cara menggunakan fungsi WindowsPreallocateStringBuffer .

#include <winstring.h>

int main()
{
    HSTRING hString = NULL;
    HSTRING_BUFFER hStringBuffer = NULL;
    PWSTR strBuffer = NULL;

    HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer);

    if (SUCCEEDED(hr))
    {
        CopyMemory(strBuffer, L"1234567890", 10 * sizeof(wchar_t));
        hr = WindowsPromoteStringBuffer(hStringBuffer, &hString);
    }

    WindowsDeleteString(hString);  
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2012 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	winstring.h
Pustaka	RuntimeObject.lib
DLL	ComBase.dll