Fungsi SHUnicodeToAnsi (shlwapi.h)

Artikel
03/02/2024

[Fungsi ini tersedia melalui Windows XP dan Windows Server 2003. Ini mungkin diubah atau tidak tersedia dalam versi Windows berikutnya.]

Mengonversi string dari halaman kode Unicode ke halaman kode ANSI.

Sintaks

int SHUnicodeToAnsi(
  [in]  PCWSTR pwszSrc,
  [out] PSTR   pszDst,
        int    cchBuf
);

Parameter

[in] pwszSrc

Jenis: PCWSTR

Penunjuk ke string Unicode yang dihentikan null untuk dikonversi ke ANSI.

[out] pszDst

Jenis: PSTR

Penunjuk ke buffer yang, ketika fungsi ini berhasil dikembalikan, menerima karakter yang dikonversi. Buffer harus cukup besar untuk berisi jumlah karakter CHAR yang ditentukan oleh parameter cchBuf , termasuk ruang untuk karakter null yang mengakhiri.

cchBuf

Jenis: int

Jumlah nilai CHAR yang dapat dimuat oleh buffer yang diacu oleh pszDst. Nilai yang ditetapkan ke parameter harus lebih besar dari nol.

Mengembalikan nilai

Jenis: int

Mengembalikan jumlah nilai CHAR yang ditulis ke buffer output, termasuk karakter null yang mengakhiri. Mengembalikan 0 jika tidak berhasil.

Keterangan

Peringatan Keamanan: Menggunakan fungsi ini salah dapat membahayakan keamanan aplikasi Anda. Misalnya, jika buffer pszDst tidak cukup besar untuk berisi jumlah karakter yang ditentukan oleh cchBuf, overrun buffer dapat terjadi. Buffer overruns dapat menyebabkan penolakan serangan layanan terhadap aplikasi jika pelanggaran akses terjadi. Dalam kasus terburuk, buffer overrun mungkin memungkinkan penyerang untuk menyuntikkan kode yang dapat dieksekusi ke dalam proses Anda, terutama jika pszDst adalah buffer berbasis tumpukan. Selain itu, string output dipotong secara diam-diam jika terlalu besar untuk buffer. Ini dapat menyebabkan kanonisisasi atau kerentanan keamanan lainnya.

Jika buffer pszDst tidak cukup besar untuk berisi seluruh string output yang dikonversi, string dipotong agar pas dengan buffer. Tidak ada cara untuk mendeteksi bahwa string pengembalian telah dipotong. String akan selalu dihentikan null, bahkan jika telah dipotong. Fungsi ini berhati-hatilah untuk tidak memotong antara byte prospek dan jejak dari pasangan karakter DBCS. Dalam hal ini, hanya karakter cchBuf-1 yang dikembalikan.

Jika buffer pwszSrc dan pszDst tumpang tindih, perilaku fungsi tidak terdefinisi.

Catatan Jangan berasumsi bahwa fungsi belum mengubah karakter apa pun dalam buffer output yang mengikuti karakter null penghentian string. Konten buffer output yang mengikuti karakter null yang mengakhiri string tidak terdefinisi, hingga dan menyertakan karakter terakhir dalam buffer.

SHTCharToAnsi didefinisikan sama dengan SHUnicodeToAnsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional, Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server, Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	shlwapi.h
DLL	Shlwapi.dll (versi 5.0 atau yang lebih baru)