Fungsi RtlAnsiStringToUnicodeString (wdm.h)

Artikel
03/08/2023

RtlAnsiStringToUnicodeString mengonversi string sumber ANSI yang diberikan menjadi string Unicode.

Sintaks

NTSYSAPI NTSTATUS RtlAnsiStringToUnicodeString(
  [in, out] PUNICODE_STRING DestinationString,
  [in]      PCANSI_STRING   SourceString,
  [in]      BOOLEAN         AllocateDestinationString
);

Parameter

[in, out] DestinationString

Arahkan ke struktur UNICODE_STRING untuk menahan string Unicode yang dikonversi. Jika AllocateDestinationStringTRUE, rutinitas mengalokasikan buffer baru untuk menyimpan data string, dan memperbarui anggota BufferDestinationString untuk menunjuk ke buffer baru. Jika tidak, rutinitas menggunakan buffer yang saat ini ditentukan untuk menahan string.

[in] SourceString

Penunjuk ke string ANSI yang akan dikonversi ke Unicode.

[in] AllocateDestinationString

Menentukan apakah rutinitas ini harus mengalokasikan ruang buffer untuk string tujuan. Jika ya, pemanggil harus membatalkan alokasi buffer dengan memanggil RtlFreeUnicodeString.

Nilai kembali

Jika konversi berhasil, RtlAnsiStringToUnicodeString mengembalikan STATUS_SUCCESS. Jika gagal, rutinitas tidak mengalokasikan memori apa pun.

Keterangan

Terjemahan sesuai dengan informasi lokal sistem saat ini.

Jika penelepon mengatur AllocateDestinationString ke TRUE, rutinitas mengganti anggota BufferDestinationString dengan penunjuk ke buffer yang dialokasikannya. Nilai lama dapat ditimpa bahkan ketika rutin mengembalikan kode status kesalahan.

Rutinitas ini tidak dideklarasikan dalam file header. Namun, Anda dapat menyalin deklarasi berikut ke kode sumber Anda:

NTSYSAPI
WCHAR
NTAPI
RtlAnsiCharToUnicodeChar(
    __inout PUCHAR *SourceCharacter
    );

Anda dapat menggunakan rutinitas berikut untuk mengonversi karakter byte tunggal dan byte ganda ke karakter Unicode:

Untuk informasi selengkapnya tentang ini dan rutinitas penanganan string lainnya, lihat Rutinitas Pustaka Run-Time (RTL).

RtlAnsiCharToUnicodeChar memiliki kekurangan keamanan. Pertimbangkan untuk menggunakan rutinitas RtlAnsiStringToUnicodeString sebagai gantinya.

Jika, pada entri, *SourceCharacter menunjuk ke buffer satu byte yang berisi byte pertama dari kode karakter dua byte, RtlAnsiCharToUnicodeChar mengesampingkan buffer saat mencoba membaca byte kedua.

Pada permulaan sistem, sistem operasi menentukan bahasa pengguna dari pengaturan lokal dan menginstal halaman kode ANSI sistem yang sesuai. RtlAnsiCharToUnicodeChar menggunakan halaman kode ini untuk mengonversi karakter byte tunggal atau byte ganda ke karakter Unicode yang sesuai.

Jika halaman kode ANSI sistem mendefinisikan kumpulan karakter byte tunggal (yaitu, set karakter ANSI), RtlAnsiCharToUnicodeChar mempercepat operasi konversi hanya dengan memperpanjang nol karakter ANSI dalam rentang 0x00 untuk 0x7f menghasilkan karakter Unicode yang sesuai. Rutinitas mengonversi nilai ANSI 0x5c ke karakter garis miring terbalik ("\"), bahkan jika halaman kode byte tunggal mendefinisikan karakter ini sebagai tanda yen.

Jika, pada entri, *SourceCharacter menunjuk ke kode karakter yang tidak valid, RtlAnsiCharToUnicodeChar mengembalikan kode karakter spasi Unicode, 0x0020. Daftar berikut ini memperlihatkan contoh kode karakter yang tidak valid:

Byte pertama dari kode karakter adalah nilai yang hanya valid sebagai byte kedua dari kode karakter dua byte.
Byte kedua dari kode karakter dua byte adalah nilai yang hanya valid sebagai byte pertama.